From 1c922843147f84b329db7c2a78f77a167143c967 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Sat, 4 Apr 2026 14:59:15 -0700 Subject: [PATCH] docs(runtime): clarify Cowork direct and projected states --- .../ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md | 32 +++++++++++++++++-- ...5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md | 2 ++ .../adoption/learning_ai_claw-cowork.md | 1 + 3 files changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md b/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md index c016fcf3..c73810c2 100644 --- a/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md +++ b/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md @@ -362,9 +362,37 @@ Current state: - checkpoint summaries now preserve artifact, memory, and approval refs when Cowork provides them - Cowork session and task IPC projections now expose canonical runtime event IDs directly -Next conforming steps: +Direct observations vs projections: -1. document which Cowork transitions are direct observations versus projections derived by `cowork-service` +- direct observations from Rust / IPC: + - task lifecycle values from orchestrator task state: + - `pending` + - `running` + - `completed` + - `failed` + - `cancelled` + - session-level `waitingApproval` + - persisted checkpoint terminal flags: + - `completed` + - `cancelled` + - checkpoint `error` + - canonical audit `event_id` + - checkpoint artifact, memory, and approval refs when present +- derived by `cowork-service` projection: + - `AgentRun.status=queued` from Rust `pending` + - `AgentTask.status=queued` from Rust `pending` + - `AgentTodo.status=open|in-progress|done|dropped` from checkpoint outcome plus task state + - `AgentCheckpoint.statusAtCapture=paused` when no stronger Rust signal exists + - session `status=active` when `waitingApproval` is false + - approval/action runtime objects from audit records rather than first-class IPC records + - dispatch context normalization for shared runtime consumers + +Interpretation rule: + +- if a state comes directly from Rust task state, checkpoint flags, or session approval state, treat it + as authoritative +- if a state is produced by mapping logic in `cowork-service`, treat it as a shared-contract view for + downstream consumers, not as a replacement for native Cowork internals Conformance bar: diff --git a/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md b/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md index 64d60fa4..a7469a8f 100644 --- a/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md +++ b/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md @@ -116,11 +116,13 @@ Observed baseline: - `da2db8e` FlowMonk dedicated runtime review web UI - `19fd4e1` FlowMonk runtime run and action drill-in - `94420a8` FlowMonk checkpoint resume guidance and linked ref review +- `ec593d7` Phase 5 docs reconciled through FlowMonk checkpoint guidance ## 7. Remaining Gaps - 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. - Cowork session and task IPC projections now also expose canonical event IDs directly, and checkpoint summaries preserve artifact IDs plus artifact and memory refs when present. +- Cowork direct-vs-projected runtime semantics are now explicitly documented in the shared runtime contract. - FlowMonk now emits direct runtime projections for planning sessions, tasks, todos, runs, approvals, actions, and checkpoints with persisted native runtime records, direct PATCH editing surfaces, and a dedicated runtime review web UI for approvals, todos, checkpoints, runs, recent actions, and checkpoint resume guidance. - remaining follow-through is now evolutionary rather than blocking: - FlowMonk can later add replay affordances if needed diff --git a/docs/ecosystem/adoption/learning_ai_claw-cowork.md b/docs/ecosystem/adoption/learning_ai_claw-cowork.md index b63411f7..f364d4c2 100644 --- a/docs/ecosystem/adoption/learning_ai_claw-cowork.md +++ b/docs/ecosystem/adoption/learning_ai_claw-cowork.md @@ -46,6 +46,7 @@ Current runtime adoption state: - persisted checkpoint records now back runtime todo review and runtime checkpoint summaries - checkpoint summaries now preserve artifact, memory, and approval refs when Cowork provides them - session and task IPC projections now expose canonical event IDs directly +- the shared runtime contract now explicitly documents which Cowork states are direct Rust observations versus `cowork-service` projections Remaining follow-up: