From 4bb8efe375b9f4b39610de65c1c38459f9c653c0 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Sat, 4 Apr 2026 11:45:12 -0700 Subject: [PATCH] docs(runtime): define ActionTrail replay requirements --- .../ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md | 74 ++++++++++++++++++- .../ECOSYSTEM_IMPLEMENTATION_TRACKER.md | 2 +- ...5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md | 2 +- 3 files changed, 73 insertions(+), 5 deletions(-) diff --git a/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md b/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md index a393f611..79a2b2c9 100644 --- a/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md +++ b/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md @@ -264,7 +264,75 @@ Current product expectations: --- -## 12. Acceptance Criteria +## 12. ActionTrail Replay Requirements + +ActionTrail replay is not required to reproduce every UI pixel of a product runtime. +For the ecosystem roadmap, replay means reconstructing the execution narrative with enough fidelity +to answer: + +1. what was requested +2. what ran +3. what approvals or pauses happened +4. what artifacts or memories were produced +5. why the final state was reached + +Minimum replay evidence for a run: + +1. stable identity + - `sessionId` + - `runId` + - `productId` + - `userId` +2. execution timing + - `startedAt` + - `completedAt` when available + - checkpoint timestamps when resumable +3. causal chain + - `correlationId` + - `causationId` + - `parentEventId` + - canonical event IDs on audit/action records when available +4. control-flow state changes + - queued + - running + - paused + - waiting-approval + - completed / failed / cancelled +5. human intervention evidence + - approval checkpoints + - approval decisions + - actor identity for approvals or overrides +6. output evidence + - `artifactRefs` + - `memoryRefs` + - relevant task and todo state at the end of the run + +Required behaviors: + +1. products must preserve runtime action logs or equivalent audit records long enough for replay and + review +2. products may keep private implementation details, but they must emit enough canonical metadata to + reconstruct the run narrative externally +3. replay consumers should trust canonical event IDs and action-log IDs over inferred timestamps +4. replay should tolerate partial fidelity + - if UI frames or low-level desktop events are unavailable, ActionTrail should still be able to + render a narrative replay from runtime actions, approvals, checkpoints, and artifacts +5. replay views must clearly distinguish between: + - observed canonical events + - inferred transitions derived from checkpoints or final state + +Current product expectations: + +- Cowork + - Rust audit records plus canonical `event_id` values are the primary replay anchor + - checkpoint/resume should explain why a run paused, resumed, or required approval +- FlowMonk + - scheduled entries, confirmations, and projected action logs are the primary replay anchor + - replay should make it obvious when an automation was queued versus actively running + +--- + +## 13. 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. @@ -274,14 +342,14 @@ Current product expectations: --- -## 13. Implementation Checklist +## 14. Implementation Checklist - [x] finalize entity list and minimum required fields - [x] define run vs session vs task boundaries - [x] define checkpoint/resume semantics - [x] define dispatch payload contract - [x] define action-log hook points -- [ ] define ActionTrail replay requirements +- [x] define ActionTrail replay requirements - [ ] define first conforming implementation plan for Cowork and FlowMonk Commits: diff --git a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md index 8edad620..4f4cb637 100644 --- a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md +++ b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md @@ -272,7 +272,7 @@ These should be resolved before claiming the ecosystem docs are fully implementa - 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. -- Shared runtime: define ActionTrail replay requirements. +- Shared runtime: define the first conforming implementation plan for Cowork and FlowMonk beyond the current baseline projections. ### 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 9f915a0d..73ef1978 100644 --- a/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md +++ b/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md @@ -112,7 +112,7 @@ Observed baseline: - 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. -- ActionTrail replay requirements still need to be formalized in the contract. +- the first conforming implementation plan still needs to be made explicit for Cowork and FlowMonk beyond the current baseline projections. ## 8. Explicit Blockers And Questions