From b30cc7b5e45d60a6157ba03615feeeef264de875 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Fri, 3 Apr 2026 19:55:12 -0700 Subject: [PATCH] docs(ecosystem): track phase4 and phase5 baselines --- .../ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md | 10 +-- .../ECOSYSTEM_IMPLEMENTATION_TRACKER.md | 39 +++++++++- .../ECOSYSTEM_PERSONAL_TIMELINE_PRD.md | 19 ++--- ...PHASE4_PERSONAL_TIMELINE_EXECUTION_PLAN.md | 76 +++++++++++++++++++ ...5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md | 69 +++++++++++++++++ docs/ecosystem/README.md | 4 +- 6 files changed, 201 insertions(+), 16 deletions(-) create mode 100644 docs/ecosystem/PHASE4_PERSONAL_TIMELINE_EXECUTION_PLAN.md create mode 100644 docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md diff --git a/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md b/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md index ae073783..b94a1016 100644 --- a/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md +++ b/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md @@ -1,6 +1,6 @@ # Ecosystem Agent Runtime Contract -> **Status:** Draft stub +> **Status:** Phase 5 baseline implemented > **Owner:** `learning_ai_common_plat` > **Reference inputs:** `claw-code-oss`, `claw-cowork`, `learning_ai_trails`, `learning_ai_flowmonk`, `learning_ai_jarvis_jr` > **Purpose:** Standardize session state, task state, resume behavior, dispatch semantics, approvals, and audit hooks across agent-capable products. @@ -174,15 +174,15 @@ Later: ## 11. Implementation Checklist -- [ ] finalize entity list and minimum required fields +- [x] finalize entity list and minimum required fields - [ ] define run vs session vs task boundaries - [ ] define checkpoint/resume semantics -- [ ] define dispatch payload contract -- [ ] define action-log hook points +- [x] define dispatch payload contract +- [x] define action-log hook points - [ ] define ActionTrail replay requirements - [ ] define first conforming implementation plan for Cowork and FlowMonk Commits: - `eae3409` drafted the initial stub -- implementation commits: pending +- `3f2482b` added the baseline runtime schemas for dispatch, session, task, todo, run, approval, and action logs diff --git a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md index 13c1d3f6..2bb76846 100644 --- a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md +++ b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md @@ -178,12 +178,47 @@ These should be resolved before claiming the ecosystem docs are fully implementa --- -## 5. Active Execution Plan +## 5. Phase 4 Checklist + +- [x] define canonical `TimelineItem` contract in `@bytelyst/events` + Commits: + - `3f2482b` +- [x] define baseline event-to-timeline inclusion rules for Phase 1 to Phase 3 + Commits: + - `3f2482b` +- [x] implement pure timeline aggregation over canonical ecosystem events + Commits: + - `3f2482b` +- [x] verify that Phase 1 to Phase 3 events render in one unified stream + Commits: + - `3f2482b` + +--- + +## 6. Phase 5 Checklist + +- [x] define canonical runtime schemas for dispatch, session, task, todo, run, approval, and action logs + Commits: + - `3f2482b` +- [x] validate Cowork-style remote dispatch against the shared runtime contract + Commits: + - `3f2482b` +- [x] validate FlowMonk-style scheduled execution against the shared runtime contract + Commits: + - `3f2482b` +- [ ] wire first product implementations to emit the shared runtime objects + +--- + +## 7. Active Execution Plan Current implementation kickoff document: - [`PHASE1_TRANSCRIPT_NOTE_MEMORY_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE1_TRANSCRIPT_NOTE_MEMORY_EXECUTION_PLAN.md) - [`PHASE2_PLAN_ROUTINE_HABIT_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE2_PLAN_ROUTINE_HABIT_EXECUTION_PLAN.md) +- [`PHASE3_COWORK_ACTIONTRAIL_NOTE_MEMORY_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE3_COWORK_ACTIONTRAIL_NOTE_MEMORY_EXECUTION_PLAN.md) +- [`PHASE4_PERSONAL_TIMELINE_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE4_PERSONAL_TIMELINE_EXECUTION_PLAN.md) +- [`PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md) Execution status: @@ -199,3 +234,5 @@ Execution status: - shared contract now also supports the Phase 2 `plan -> routine -> habit` seam through `artifact.created` and `artifact.linked` - Phase 2 walkthrough is complete and tracked in [`PHASE2_PLAN_ROUTINE_HABIT_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE2_PLAN_ROUTINE_HABIT_EXECUTION_PLAN.md) - Phase 3 walkthrough is complete and tracked in [`PHASE3_COWORK_ACTIONTRAIL_NOTE_MEMORY_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE3_COWORK_ACTIONTRAIL_NOTE_MEMORY_EXECUTION_PLAN.md) +- Phase 4 timeline baseline is complete and tracked in [`PHASE4_PERSONAL_TIMELINE_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE4_PERSONAL_TIMELINE_EXECUTION_PLAN.md) +- Phase 5 runtime-contract baseline is complete and tracked in [`PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md) diff --git a/docs/ecosystem/ECOSYSTEM_PERSONAL_TIMELINE_PRD.md b/docs/ecosystem/ECOSYSTEM_PERSONAL_TIMELINE_PRD.md index e0ad320b..e6ac22c5 100644 --- a/docs/ecosystem/ECOSYSTEM_PERSONAL_TIMELINE_PRD.md +++ b/docs/ecosystem/ECOSYSTEM_PERSONAL_TIMELINE_PRD.md @@ -1,6 +1,6 @@ # Ecosystem Personal Timeline PRD -> **Status:** Draft +> **Status:** Phase 4 baseline implemented > **Owner:** `learning_ai_common_plat` > **Purpose:** Define a shared user activity timeline that makes cross-product behavior visible and useful. @@ -52,10 +52,10 @@ The timeline should consume: ## 4. Phase-1 User Stories -- [ ] As a user, I can see that one dictated transcript became a note and a memory candidate. -- [ ] As a user, I can see that one plan generated a routine and a habit. -- [ ] As a user, I can see that one Cowork run produced an output and required an approval. -- [ ] As a user, I can trace each item back to its source product and action. +- [x] As a user, I can see that one dictated transcript became a note and a memory candidate. +- [x] As a user, I can see that one plan generated a routine and a habit. +- [x] As a user, I can see that one Cowork run produced an output and required an approval. +- [x] As a user, I can trace each item back to its source product and action. --- @@ -98,13 +98,14 @@ type TimelineItem = { ## 8. Implementation Checklist -- [ ] define timeline item contract -- [ ] define event-to-timeline inclusion rules -- [ ] define artifact linking behavior +- [x] define timeline item contract +- [x] define event-to-timeline inclusion rules +- [x] define artifact linking behavior - [ ] define noise filtering rules - [ ] define phase-1 UI hosting choice -- [ ] define verification flow using golden paths +- [x] define verification flow using golden paths Commits: - `7a86a76` drafted the initial version +- `3f2482b` added the baseline `TimelineItem` schema and event-to-timeline aggregator diff --git a/docs/ecosystem/PHASE4_PERSONAL_TIMELINE_EXECUTION_PLAN.md b/docs/ecosystem/PHASE4_PERSONAL_TIMELINE_EXECUTION_PLAN.md new file mode 100644 index 00000000..989e0079 --- /dev/null +++ b/docs/ecosystem/PHASE4_PERSONAL_TIMELINE_EXECUTION_PLAN.md @@ -0,0 +1,76 @@ +# Phase 4 Execution Plan + +> **Flow:** Shared personal timeline over the first three ecosystem flows +> **Status:** Implemented baseline +> **Owner:** `learning_ai_common_plat` +> **Purpose:** Turn the personal timeline PRD into a reusable contract and baseline aggregator so the first three ecosystem flows can be rendered as one coherent activity stream. + +--- + +## 1. Scope + +Phase 4 defines and implements: + +1. the canonical `TimelineItem` shape +2. baseline event-to-timeline mapping rules +3. a pure aggregator that converts canonical ecosystem events into timeline items + +This phase does not add a hosted UI yet. It establishes the shared data contract first. + +--- + +## 2. Code Surface + +- `packages/events/src/timeline.ts` +- `packages/events/src/timeline.test.ts` +- `packages/events/src/index.ts` + +--- + +## 3. Covered Inputs + +The baseline mapper covers the high-value events already implemented in Phases 1 to 3: + +- `capture.transcript.created` +- `artifact.created` +- `artifact.linked` +- `memory.entry.created` + +This is enough to render: + +- transcript -> note -> memory +- plan -> routine -> habit +- trail-report -> note -> memory + +--- + +## 4. Verification + +- `cd learning_ai_common_plat/packages/events && pnpm exec vitest run src/timeline.test.ts` + +Observed baseline: + +- Phase 1, Phase 2, and Phase 3 sample events now produce one sorted timeline list +- each item preserves: + - event identity + - product identity + - artifact refs + - related event refs + - actor type + - correlation ID + +--- + +## 5. Done Criteria + +- [x] define `TimelineItem` contract +- [x] define baseline event-to-timeline mapping rules +- [x] implement pure timeline aggregation over canonical events +- [x] verify that Phase 1 to Phase 3 events render in one unified stream +- [ ] choose first hosted timeline UI + +--- + +## 6. Commits + +- `3f2482b` timeline contract and aggregator baseline diff --git a/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md b/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md new file mode 100644 index 00000000..cad61375 --- /dev/null +++ b/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md @@ -0,0 +1,69 @@ +# Phase 5 Execution Plan + +> **Flow:** Shared agent runtime contract baseline +> **Status:** Implemented baseline +> **Owner:** `learning_ai_common_plat` +> **Purpose:** Turn the runtime contract draft into concrete schemas for sessions, tasks, todos, runs, approvals, dispatch, and action logs. + +--- + +## 1. Scope + +Phase 5 defines and implements: + +1. canonical runtime schemas +2. dispatch metadata contract +3. approval checkpoint contract +4. action-log contract + +This phase establishes the contract layer needed before cross-product runtime adoption in Cowork, FlowMonk, and future agent surfaces. + +--- + +## 2. Code Surface + +- `packages/events/src/agent-runtime.ts` +- `packages/events/src/agent-runtime.test.ts` +- `packages/events/src/index.ts` + +--- + +## 3. Covered Runtime Entities + +- `AgentDispatchContext` +- `AgentSession` +- `AgentTask` +- `AgentTodo` +- `AgentRun` +- `AgentApprovalCheckpoint` +- `AgentDispatchRequest` +- `AgentActionLog` + +--- + +## 4. Verification + +- `cd learning_ai_common_plat/packages/events && pnpm exec vitest run src/agent-runtime.test.ts` + +Observed baseline: + +- Cowork-style remote dispatch parses against the shared runtime contract +- FlowMonk-style scheduled execution parses against the same contract +- approval and action-log primitives now have one canonical schema surface + +--- + +## 5. Done Criteria + +- [x] finalize baseline entity list and required fields +- [x] define dispatch payload contract +- [x] define session, task, todo, run, and approval schemas +- [x] define action-log contract +- [x] verify Cowork-style and FlowMonk-style runtime examples +- [ ] wire first product implementations to emit the shared runtime objects + +--- + +## 6. Commits + +- `3f2482b` runtime contract schema baseline diff --git a/docs/ecosystem/README.md b/docs/ecosystem/README.md index 9af9e653..7ce14119 100644 --- a/docs/ecosystem/README.md +++ b/docs/ecosystem/README.md @@ -28,6 +28,8 @@ Recommended structure: - [`PHASE1_TRANSCRIPT_NOTE_MEMORY_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE1_TRANSCRIPT_NOTE_MEMORY_EXECUTION_PLAN.md) — execution-ready plan for the first golden flow - [`PHASE2_PLAN_ROUTINE_HABIT_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE2_PLAN_ROUTINE_HABIT_EXECUTION_PLAN.md) — execution-ready plan for the second golden flow - [`PHASE3_COWORK_ACTIONTRAIL_NOTE_MEMORY_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE3_COWORK_ACTIONTRAIL_NOTE_MEMORY_EXECUTION_PLAN.md) — execution-ready plan for the audited artifact flow +- [`PHASE4_PERSONAL_TIMELINE_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE4_PERSONAL_TIMELINE_EXECUTION_PLAN.md) — execution-ready plan for the unified timeline baseline +- [`PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE5_AGENT_RUNTIME_CONTRACT_EXECUTION_PLAN.md) — execution-ready plan for the shared agent runtime baseline - [`delegation/`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/delegation) — ready-to-send task packs and launcher lines for Saravana, Codex, Windsurf, and Cursor - [`adoption/`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/adoption) — per-product adoption notes @@ -50,4 +52,4 @@ Tracking convention: Current implementation package: -- [`packages/events`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/packages/events) holds the first concrete ecosystem contract code and now covers the Phase 1, Phase 2, and Phase 3 artifact/event seams. +- [`packages/events`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/packages/events) holds the first concrete ecosystem contract code and now covers the Phase 1 to Phase 5 artifact, timeline, and runtime seams.