# Phase 5 Execution Plan

> **Flow:** Shared agent runtime contract baseline
> **Status:** Baseline implemented, Cowork product integration implemented, FlowMonk product integration implemented
> **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

## 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 first conforming implementation plan still needs to be made explicit for Cowork and FlowMonk beyond the current baseline projections.

## 8. Explicit Blockers And Questions

- Question: should Cowork eventually expose canonical event IDs directly on session/task IPC projections too, or is the audit/action surface enough for Phase 5?
