# Phase 5 Execution Plan

> **Flow:** Shared agent runtime contract baseline
> **Status:** Baseline implemented, Cowork product integration implemented, FlowMonk product integration implemented and live-e2e verified
> **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
5. the first product-facing runtime projection and dispatch-validation API
6. the first hosted internal runtime console over that API

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`
- `services/platform-service/src/modules/agent-runtime/routes.ts`
- `services/platform-service/src/modules/agent-runtime/routes.test.ts`
- `dashboards/admin-web/src/app/api/agent-runtime/route.ts`
- `dashboards/admin-web/src/app/(dashboard)/agent-runtime/page.tsx`
- `dashboards/admin-web/src/__tests__/agent-runtime.test.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`
- `cd learning_ai_common_plat && pnpm --filter @lysnrai/platform-service exec vitest run src/modules/agent-runtime/routes.test.ts src/server.test.ts`
- `cd learning_ai_common_plat && pnpm --filter @lysnrai/platform-service exec tsc --noEmit`
- `cd learning_ai_common_plat/dashboards/admin-web && npm run test -- src/__tests__/agent-runtime.test.ts`
- `cd learning_ai_common_plat/dashboards/admin-web && npm run typecheck`

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
- platform-service now exposes `GET /api/agent-runtime/sessions` as a shared runtime-session projection
- platform-service now exposes `GET /api/agent-runtime/runs` as a shared runtime-run projection
- platform-service now exposes `POST /api/agent-runtime/dispatch/validate` against the canonical dispatch schema
- admin-web now exposes the first hosted internal runtime console at `/agent-runtime`
- the hosted UI supports projected session review, projected run review, and dispatch payload validation
- 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

---

## 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
- [x] add first product-facing runtime projection and dispatch validation API in platform-service
- [x] wire first product implementations to emit the shared runtime objects directly from Cowork and FlowMonk

---

## 6. Commits

- `3f2482b` runtime contract schema baseline
- `fe36296` platform-service runtime projection + dispatch validation
- `71ef2ac` admin-web hosted runtime console
- `023826e` cowork-service runtime projection routes
- `01201f8` cowork-service runtime task projection
- `b8242b4` cowork-service runtime action-log projection
- `1ccafa7` FlowMonk local shared-package resolution + runtime projection routes
- `a3ae6fe` FlowMonk queued-run projection preservation
- `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
- `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
- `4ff578e` Cowork checkpoint refs plus canonical session/task IPC event IDs
- `32b46f0` cowork-service runtime mapping for enriched checkpoint refs and IPC event IDs
- `6b1e52c` FlowMonk direct user-managed runtime todo and approval editing surfaces
- `da2db8e` FlowMonk dedicated runtime review web UI
- `19fd4e1` FlowMonk runtime run and action drill-in
- `94420a8` FlowMonk checkpoint resume guidance and linked ref review
- `51cf948` FlowMonk replay-oriented run filtering and action payload drill-in
- `71038bb` FlowMonk runtime mutations now emit replayable domain events
- `5fc778b` FlowMonk runtime review live Playwright verification plus web harness hardening
- `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, checkpoint resume guidance, and lightweight replay review.
- FlowMonk runtime mutations now also emit replayable domain events from the source planning backend so runtime review can inspect the resulting `task.updated`, `entry.confirmed`, and `entry.cancelled` actions directly.
- FlowMonk runtime review is now live-e2e verified with Playwright against the local backend and local web shell.
- remaining follow-through is now evolutionary rather than blocking:
  - FlowMonk can later add richer replay execution controls if they become necessary

## 8. Explicit Blockers And Questions

- No blocking questions remain for the Phase 5 baseline.
- Optional product question: are richer replay execution controls worth the added product complexity, or is the current review surface sufficient?
