bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(ecosystem): reconcile runtime lifecycle and verification

Browse Source
This commit is contained in:
Saravana Achu Mac 2026-04-04 11:38:07 -07:00
parent 97b731e14f
commit 977d41486a
5 changed files with 128 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md
View File

@ -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

41
docs/ecosystem/ECOSYSTEM_CONTRACT_TEST_STRATEGY.md
View File

@ -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:

26
docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md
View File

@ -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`

30
docs/ecosystem/ECOSYSTEM_VERIFICATION_MATRIX.md
View File

@ -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

12
docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md
View File

@ -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