From 41673125af2ce6826b163b070a804e586f06e6ab Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Sat, 4 Apr 2026 12:15:40 -0700 Subject: [PATCH] docs(runtime): close checkpoint and primitive follow-through --- .../ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md | 18 +++++++----------- .../ECOSYSTEM_IMPLEMENTATION_TRACKER.md | 6 ++---- ...E5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md | 15 ++++++++------- .../adoption/learning_ai_claw-cowork.md | 5 ++--- .../ecosystem/adoption/learning_ai_flowmonk.md | 9 +++++---- 5 files changed, 24 insertions(+), 29 deletions(-) diff --git a/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md b/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md index 87847120..e0afd688 100644 --- a/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md +++ b/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md @@ -357,15 +357,13 @@ Current state: - sessions, tasks, runs, approvals, actions, and dispatch validation are already exposed through `cowork-service` -- todos are currently task-backed +- todos and checkpoint summaries now come from persisted Cowork checkpoint records - replay anchors now use canonical Rust audit `event_id` Next conforming steps: -1. add a first-class Cowork todo/checklist source or make the task-backed mapping an explicit long-term choice -2. expose checkpoint metadata or equivalent persisted resume summaries through product-facing runtime surfaces -3. preserve canonical event IDs anywhere approval/audit state crosses service boundaries -4. document which Cowork transitions are direct observations versus projections derived by `cowork-service` +1. preserve canonical event IDs anywhere approval/audit state crosses service boundaries +2. document which Cowork transitions are direct observations versus projections derived by `cowork-service` Conformance bar: @@ -392,15 +390,13 @@ Required external contract surface: Current state: - sessions, tasks, todos, runs, approvals, actions, and dispatch validation are exposed through the backend -- approvals are derived from agent-suggested schedule entries -- todos are derived from the planning backlog +- approvals, todos, and checkpoints are now persisted as native runtime records in FlowMonk +- run/session rollover rule: one planning workspace session exists per user, and each schedule entry becomes a new run inside that session Next conforming steps: -1. decide whether approvals remain derived or become a first-class product primitive -2. decide whether backlog tasks are the permanent todo model or whether a distinct checklist model will exist -3. expose checkpoint summaries for planning sessions so resume state is not inferred only from final records -4. document the exact rule for when a scheduled entry becomes a new run under an existing session +1. decide whether approvals and todos will eventually gain direct end-user editing surfaces or remain runtime-managed records +2. preserve richer artifact and memory refs in checkpoint summaries once downstream runtime producers are connected Conformance bar: diff --git a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md index 9aa124f2..71238ab3 100644 --- a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md +++ b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md @@ -270,10 +270,8 @@ These should be resolved before claiming the ecosystem docs are fully implementa ### 6.1 Remaining Direct Runtime TODOs -- Cowork: add `AgentTodo` direct projection once the product exposes first-class todo entities. -- FlowMonk: replace the current derived approval/todo projections once the product exposes first-class approval/todo primitives. -- Cowork: expose product-facing checkpoint summaries for resume review. -- FlowMonk: expose product-facing checkpoint summaries and document the run/session rollover rule. +- Cowork: enrich checkpoint summaries with artifact and memory refs when those runtime links are available. +- FlowMonk: decide whether runtime approvals and todos should gain direct user-managed editing surfaces or remain runtime-managed records. ### 6.2 Explicit Blockers And Questions diff --git a/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md b/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md index 970998d0..e7f3cbe7 100644 --- a/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md +++ b/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md @@ -107,16 +107,17 @@ Observed baseline: - `a57b367` cowork-service runtime projections now prefer canonical audit event IDs - `97b731e` cowork-service runtime todo projection - `faf93ec` FlowMonk approval and todo projections +- `34c9b78` Cowork persisted checkpoint IPC surface +- `9aeb9bb` shared checkpoint schema plus cowork-service checkpoint and todo review routes +- `86470b2` FlowMonk native runtime todo, approval, and checkpoint persistence ## 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 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. -- the conforming implementation plan is now explicit in the runtime contract, but the product-level follow-through still remains: - - Cowork needs a first-class todo source or an explicit decision to keep the task-backed mapping - - Cowork needs product-facing checkpoint summaries - - FlowMonk needs an explicit decision on whether approvals/todos stay derived or become first-class primitives - - FlowMonk needs product-facing checkpoint summaries and a documented run/session rollover rule +- Cowork now emits shared runtime projections from cowork-service, preserves Rust-side canonical event IDs on approval/audit records, and exposes persisted checkpoint-driven todo and resume review surfaces. +- FlowMonk now emits direct runtime projections for planning sessions, tasks, todos, runs, approvals, actions, and checkpoints with persisted native runtime records. +- remaining follow-through is now evolutionary rather than blocking: + - Cowork can later expose richer checkpoint artifact and memory refs + - FlowMonk can later add direct user-managed editing surfaces for runtime approvals and todos if desired ## 8. Explicit Blockers And Questions diff --git a/docs/ecosystem/adoption/learning_ai_claw-cowork.md b/docs/ecosystem/adoption/learning_ai_claw-cowork.md index 95da6d36..00f187b7 100644 --- a/docs/ecosystem/adoption/learning_ai_claw-cowork.md +++ b/docs/ecosystem/adoption/learning_ai_claw-cowork.md @@ -43,13 +43,11 @@ Current runtime adoption state: - shared runtime projections now exist through `cowork-service` - audit/action surfaces preserve canonical Rust `event_id` - approvals and action logs can participate in ActionTrail replay -- todos are still derived from orchestrator tasks +- persisted checkpoint records now back runtime todo review and runtime checkpoint summaries Remaining follow-up: - add an explicit product-local helper for exporting ecosystem-ready audit payloads -- decide whether task-backed todo projection is temporary or permanent -- expose product-facing checkpoint summaries for resume review - optionally emit canonical runtime events alongside the current local audit logs - add signed dispatch or upload flow from Cowork desktop into ActionTrail when runtime integration is prioritized @@ -58,3 +56,4 @@ Remaining follow-up: ## 4. Commits - existing producer surface predates Phase 3 baseline +- `34c9b78` added persisted checkpoint IPC summaries for runtime todo and resume review diff --git a/docs/ecosystem/adoption/learning_ai_flowmonk.md b/docs/ecosystem/adoption/learning_ai_flowmonk.md index 22e793be..355444b2 100644 --- a/docs/ecosystem/adoption/learning_ai_flowmonk.md +++ b/docs/ecosystem/adoption/learning_ai_flowmonk.md @@ -20,13 +20,14 @@ - [x] include correlation/session IDs for downstream linking - [x] persist latest plan indexes for downstream consumers - [x] expose direct runtime sessions, tasks, todos, runs, approvals, and actions -- [ ] decide whether approvals remain derived or become first-class primitives -- [ ] decide whether todos remain backlog-task projections or become a first-class checklist primitive -- [ ] expose product-facing checkpoint summaries for planning-session resume -- [ ] document the rule for when a scheduled entry becomes a new run under an existing session +- [x] persist native runtime todos, approvals, and checkpoints +- [x] expose product-facing checkpoint summaries for planning-session resume +- [x] document the rule for when a scheduled entry becomes a new run under an existing session +- [ ] decide whether runtime approvals and todos need direct user-managed editing surfaces Commits: - `59ab8b1` implemented the Phase 2 producer path - `1ccafa7` implemented direct runtime sessions, tasks, runs, actions, and dispatch validation - `faf93ec` implemented direct runtime approvals and todos +- `86470b2` persisted native runtime todo, approval, and checkpoint records