diff --git a/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md b/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md index b94a1016..9af91cd2 100644 --- a/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md +++ b/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md @@ -162,7 +162,48 @@ Later: --- -## 10. Acceptance Criteria +## 10. Lifecycle Boundaries + +The current runtime model now uses these boundaries: + +- `AgentSession` + A durable container for related work over time. Sessions can outlive individual runs and can stay resumable even after one run finishes. +- `AgentRun` + A concrete execution instance. + A run is the thing that can be `queued`, `running`, `paused`, `waiting-approval`, `completed`, `failed`, or `cancelled`. +- `AgentTask` + A user-meaningful unit of intent inside a session. + Tasks should remain stable enough to describe the work, even when execution is retried or rescheduled. +- `AgentTodo` + A smaller actionable checklist item. + When a product has no separate checklist model yet, it may temporarily project todos from its native task backlog, but that mapping must be called out explicitly. + +Interpretation rules: + +1. `queued` means execution has not started yet. +2. `paused` means execution started and is intentionally halted or deferred. +3. `waiting-approval` means the run is blocked on human review. +4. a session may contain multiple runs over time +5. a task may survive multiple runs if execution is retried, resumed, or rescheduled +6. todos should never imply a separate execution history unless the product truly tracks that internally + +Current product mappings: + +- Cowork + - session: persisted/resumable workspace session + - task: orchestrator task + - run: orchestrator execution of that task + - todo: interim task-backed projection until a first-class todo source exists +- FlowMonk + - session: user planning workspace + - task: planning backlog task + - run: scheduled entry + - approval: agent-suggested schedule entry awaiting or receiving confirmation + - todo: task-backed projection until a distinct checklist primitive exists + +--- + +## 11. Acceptance Criteria 1. A dispatched Cowork task can be resumed after interruption without losing audit continuity. 2. A FlowMonk execution can emit task/todo state using the same contract. @@ -172,10 +213,10 @@ Later: --- -## 11. Implementation Checklist +## 12. Implementation Checklist - [x] finalize entity list and minimum required fields -- [ ] define run vs session vs task boundaries +- [x] define run vs session vs task boundaries - [ ] define checkpoint/resume semantics - [x] define dispatch payload contract - [x] define action-log hook points @@ -186,3 +227,6 @@ Commits: - `eae3409` drafted the initial stub - `3f2482b` added the baseline runtime schemas for dispatch, session, task, todo, run, approval, and action logs +- `97b731e` added the Cowork task-backed `AgentTodo` projection +- `faf93ec` added FlowMonk direct `AgentApprovalCheckpoint` and task-backed `AgentTodo` projections +- `ff8c5eb` promoted `queued` to a first-class `AgentRun` state diff --git a/docs/ecosystem/ECOSYSTEM_CONTRACT_TEST_STRATEGY.md b/docs/ecosystem/ECOSYSTEM_CONTRACT_TEST_STRATEGY.md index 0a7a7a51..2f8a77e8 100644 --- a/docs/ecosystem/ECOSYSTEM_CONTRACT_TEST_STRATEGY.md +++ b/docs/ecosystem/ECOSYSTEM_CONTRACT_TEST_STRATEGY.md @@ -85,23 +85,42 @@ Every consuming or producing repo should: --- -## 6. Phase-1 Contract Test Scope +## 6. Current Contract Test Scope -- [ ] artifact schema fixture validation -- [ ] event envelope fixture validation -- [ ] runtime session and task fixture validation -- [ ] approval record fixture validation -- [ ] one producer and one consumer test for each of the two golden flows +- [x] artifact schema fixture validation +- [x] event envelope fixture validation +- [x] runtime session and task fixture validation +- [x] approval record fixture validation +- [x] one producer and one consumer test for each of the first three golden flows + +Current executable anchors: + +- `learning_ai_common_plat/packages/events/src/ecosystem.test.ts` +- `learning_ai_common_plat/packages/events/src/agent-runtime.test.ts` +- `learning_ai_common_plat/services/platform-service/src/modules/audit/routes.test.ts` +- `learning_ai_common_plat/services/platform-service/src/modules/agent-runtime/routes.test.ts` +- `learning_ai_common_plat/services/cowork-service/src/modules/agent-runtime/routes.test.ts` +- `learning_ai_common_plat/dashboards/admin-web/src/__tests__/agent-runtime.test.ts` +- `learning_ai_common_plat/dashboards/admin-web/src/__tests__/timeline.test.ts` +- `learning_ai_flowmonk/backend/src/modules/agent-runtime/routes.test.ts` +- `learning_ai_trails/backend/src/lib/ecosystem-phase3.test.ts` --- ## 7. Implementation Checklist -- [ ] choose canonical fixture storage location -- [ ] define JSON fixture naming convention -- [ ] define validation approach per contract -- [ ] define how repos import or copy fixtures -- [ ] define CI/manual verification expectations +- [x] choose canonical fixture storage location +- [x] define JSON fixture naming convention +- [x] define validation approach per contract +- [x] define how repos import or copy fixtures +- [x] define CI/manual verification expectations + +Current choices: + +- canonical executable fixtures live in `learning_ai_common_plat/packages/events` +- human-readable planning docs remain in `docs/ecosystem/` +- producer and consumer repos validate against `@bytelyst/events` instead of copying schema definitions +- focused route or library tests are acceptable completion evidence when full end-to-end automation is not yet available Commits: diff --git a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md index 09979b9f..f788c59c 100644 --- a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md +++ b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md @@ -39,18 +39,18 @@ Example: ## 2. Core Spec Status -| Spec | Status | Owner Repo | Notes | Commits | -| ---------------------------------------------- | ----------- | ------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------- | -| `ECOSYSTEM_CROSS_POLLINATION_OPPORTUNITIES.md` | done | `learning_ai_common_plat` | strategy baseline created and strengthened | `d28e9d0`, `341cde7`, `3e572b6` | -| `ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md` | in-progress | `learning_ai_common_plat` | Phase 1 artifact schema and fixtures now exist in `@bytelyst/events`; broader storage rules still open | `eae3409`, `76f1b47` | -| `ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md` | in-progress | `learning_ai_common_plat` | draft stub exists, runtime normalization still open | `eae3409` | -| `ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md` | in-progress | `learning_ai_common_plat` | draft stub exists, policy matrix still needs hardening | `eae3409` | -| `ECOSYSTEM_EVENT_TAXONOMY.md` | in-progress | `learning_ai_common_plat` | Phase 1 event names and examples now exist in `@bytelyst/events`; broader taxonomy remains open | `41fa2cd`, `76f1b47` | -| `ECOSYSTEM_OWNERSHIP_MATRIX.md` | in-progress | `learning_ai_common_plat` | temporary four-party ownership model added | `41fa2cd`, `7a86a76` | -| `ECOSYSTEM_VERIFICATION_MATRIX.md` | in-progress | `learning_ai_common_plat` | draft verification model added | `41fa2cd` | -| `ECOSYSTEM_CONTRACT_TEST_STRATEGY.md` | in-progress | `learning_ai_common_plat` | draft contract-test model added | `41fa2cd` | -| `ECOSYSTEM_MARKETPLACE_UNIFICATION.md` | in-progress | `learning_ai_common_plat` | draft exists, inventory and entitlement details open | `7a86a76` | -| `ECOSYSTEM_PERSONAL_TIMELINE_PRD.md` | in-progress | `learning_ai_common_plat` | draft exists, hosting and filtering decisions open | `7a86a76` | +| Spec | Status | Owner Repo | Notes | Commits | +| ---------------------------------------------- | ----------- | ------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | +| `ECOSYSTEM_CROSS_POLLINATION_OPPORTUNITIES.md` | done | `learning_ai_common_plat` | strategy baseline created and strengthened | `d28e9d0`, `341cde7`, `3e572b6` | +| `ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md` | in-progress | `learning_ai_common_plat` | Phase 1 artifact schema and fixtures now exist in `@bytelyst/events`; broader storage rules still open | `eae3409`, `76f1b47` | +| `ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md` | in-progress | `learning_ai_common_plat` | lifecycle boundaries, queued runs, and direct Cowork/FlowMonk mappings now exist; replay semantics remain open | `eae3409`, `ff8c5eb`, `97b731e`, `faf93ec` | +| `ECOSYSTEM_APPROVALS_AND_TRUST_MODEL.md` | in-progress | `learning_ai_common_plat` | draft stub exists, policy matrix still needs hardening | `eae3409` | +| `ECOSYSTEM_EVENT_TAXONOMY.md` | in-progress | `learning_ai_common_plat` | Phase 1 event names and examples now exist in `@bytelyst/events`; broader taxonomy remains open | `41fa2cd`, `76f1b47` | +| `ECOSYSTEM_OWNERSHIP_MATRIX.md` | in-progress | `learning_ai_common_plat` | temporary four-party ownership model added | `41fa2cd`, `7a86a76` | +| `ECOSYSTEM_VERIFICATION_MATRIX.md` | in-progress | `learning_ai_common_plat` | verification layers exist; repo-level ownership still needs explicit later-phase mapping | `41fa2cd` | +| `ECOSYSTEM_CONTRACT_TEST_STRATEGY.md` | in-progress | `learning_ai_common_plat` | executable fixture locations and runtime-route test anchors are now documented | `41fa2cd` | +| `ECOSYSTEM_MARKETPLACE_UNIFICATION.md` | in-progress | `learning_ai_common_plat` | draft exists, inventory and entitlement details open | `7a86a76` | +| `ECOSYSTEM_PERSONAL_TIMELINE_PRD.md` | in-progress | `learning_ai_common_plat` | draft exists, hosting and filtering decisions open | `7a86a76` | --- @@ -244,8 +244,10 @@ These should be resolved before claiming the ecosystem docs are fully implementa - `023826e` adds `GET /api/agent-runtime/sessions`, `GET /api/agent-runtime/runs`, `GET /api/agent-runtime/approvals`, and `POST /api/agent-runtime/dispatch/validate` - `01201f8` adds `GET /api/agent-runtime/tasks` with canonical `AgentTask` projection - `b8242b4` adds `GET /api/agent-runtime/actions` with canonical `AgentActionLog` projection + - `97b731e` adds `GET /api/agent-runtime/todos` with an interim task-backed `AgentTodo` projection - FlowMonk local installs now resolve `@bytelyst/*` from the sibling `learning_ai_common_plat` workspace instead of the dead localhost registry - `1ccafa7` adds FlowMonk direct runtime projections for sessions, tasks, runs, action logs, and dispatch validation + - `faf93ec` adds FlowMonk direct approval and todo projections - [x] promote `queued` to a first-class `AgentRun` state and preserve it in shared runtime projections Commits: - `ff8c5eb` diff --git a/docs/ecosystem/ECOSYSTEM_VERIFICATION_MATRIX.md b/docs/ecosystem/ECOSYSTEM_VERIFICATION_MATRIX.md index a655eaeb..5753d173 100644 --- a/docs/ecosystem/ECOSYSTEM_VERIFICATION_MATRIX.md +++ b/docs/ecosystem/ECOSYSTEM_VERIFICATION_MATRIX.md @@ -93,10 +93,36 @@ For every major implementation item, attach: --- -## 5. Implementation Checklist +## 5. Repo-Level Verification Owners + +- `learning_ai_common_plat` + - shared schema validation in `packages/events` + - platform-service route tests + - cowork-service route tests + - admin-web proxy and dashboard route tests +- `learning_voice_ai_agent` + - transcript producer tests and artifact persistence checks +- `learning_ai_notes` + - transcript and trail import route/library tests +- `learning_multimodal_memory_agents` + - memory import route/library tests +- `learning_ai_flowmonk` + - runtime route tests and Phase 2 artifact flow tests +- `learning_ai_clock` + - routine import tests for Phase 2 +- `learning_ai_efforise` + - habit import tests for Phase 2 +- `learning_ai_trails` + - trail artifact import and causation tests for Phase 3 +- `oss/learning_ai_claw-cowork` + - native audit/runtime emission verification where local Rust tooling is available + +--- + +## 6. Implementation Checklist - [ ] finalize phase-1 golden flow checks -- [ ] define repo-level verification owners +- [x] define repo-level verification owners - [ ] define minimum evidence for “done” - [ ] add links from tracker rows to verification evidence diff --git a/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md b/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md index 5790ebc3..11d125d5 100644 --- a/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md +++ b/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md @@ -69,11 +69,14 @@ Observed baseline: - cowork-service now exposes direct product-native runtime projections at: - `GET /api/agent-runtime/sessions` - `GET /api/agent-runtime/tasks` + - `GET /api/agent-runtime/todos` - `GET /api/agent-runtime/runs` - `GET /api/agent-runtime/approvals` - `GET /api/agent-runtime/actions` - `POST /api/agent-runtime/dispatch/validate` - Cowork projections now emit canonical `AgentSession`, `AgentTask`, `AgentRun`, `AgentApprovalCheckpoint`, and `AgentActionLog` objects from the product backend instead of only relying on platform projections +- Cowork now also emits an interim task-backed `AgentTodo` projection so the external runtime contract can stay complete while the product lacks a distinct todo primitive +- FlowMonk now emits direct `AgentApprovalCheckpoint` projections from agent-suggested schedule entries and task-backed `AgentTodo` projections from the planning backlog --- @@ -102,12 +105,15 @@ Observed baseline: - `ff8c5eb` shared runtime queued-run state - `3963f63` Cowork Rust canonical audit event ID emission - `a57b367` cowork-service runtime projections now prefer canonical audit event IDs +- `97b731e` cowork-service runtime todo projection +- `faf93ec` FlowMonk approval and todo projections ## 7. Remaining Gaps -- Cowork now emits shared runtime projections from cowork-service, preserves Rust-side canonical event IDs on approval/audit records, and still lacks a first-class `AgentTodo` product source. -- FlowMonk now emits direct runtime projections for planning sessions, tasks, runs, and action logs, but it still has no first-class approval checkpoint or todo primitive. -- run-vs-session semantics for queued work now preserve `queued` directly in the shared runtime contract, but broader session/run lifecycle guidance still needs to be documented. +- Cowork now emits shared runtime projections from cowork-service, preserves Rust-side canonical event IDs on approval/audit records, and still lacks a first-class native `AgentTodo` product source behind the current task-backed projection. +- FlowMonk now emits direct runtime projections for planning sessions, tasks, todos, runs, approvals, and action logs, but it still lacks distinct native checklist and approval entities behind those projections. +- checkpoint/resume payload semantics still need to be formalized in the contract. +- ActionTrail replay requirements still need to be formalized in the contract. ## 8. Explicit Blockers And Questions