|
| 1 | +# Phase 6: API Boundary and Control Plane Contract - Context |
| 2 | + |
| 3 | +**Gathered:** 2026-03-22 |
| 4 | +**Status:** Ready for planning |
| 5 | + |
| 6 | +<domain> |
| 7 | +## Phase Boundary |
| 8 | + |
| 9 | +Extract the existing local orchestration runtime into a host-agnostic control-plane API that both the Command Center and external callers can use. This phase defines the shared service boundary, the durable HTTP run contract, and the parity rules between UI-driven runs and API-driven runs. It does not yet host the API in Azure Functions, add durable cloud worker dispatch, or broaden the product into a multi-user SaaS surface. |
| 10 | + |
| 11 | +</domain> |
| 12 | + |
| 13 | +<decisions> |
| 14 | +## Implementation Decisions |
| 15 | + |
| 16 | +### API surface and resource model |
| 17 | +- The Phase 6 control plane should be a versioned REST surface rooted at `/api/v1`, not a collection of UI-only or framework-specific endpoints. |
| 18 | +- The durable top-level resource is a **run**. The contract should center on `run_id`, current status, stage, pause state, routing state, agents, artifacts, and control actions. |
| 19 | +- AG-UI streaming endpoints in `command_center/app.py` remain a specialized UI transport and debugger-friendly protocol surface; they are not the canonical external control-plane contract. |
| 20 | +- The control-plane HTTP surface should separate run submission, run summary, timeline or event inspection, routing/agent inspection, artifact retrieval, and control actions into explicit resources instead of one overloaded RPC-style endpoint. |
| 21 | + |
| 22 | +### Run actions and lifecycle over HTTP |
| 23 | +- `POST /api/v1/runs` should create a durable run and return the initial run summary immediately, including `run_id`, status, stage, repo/workspace context, and the accepted task payload. |
| 24 | +- Run mutation actions should stay explicit and command-like: continue, approve, retry, cancel, and append operator input should each have stable, dedicated POST actions under the run resource rather than one generic “do anything” payload. |
| 25 | +- Read surfaces should be stable and browser-independent: run summary, current stage, pause reason, route metadata, specialist state, timeline/events, and artifact manifest must all be fetchable without depending on browser session state or AG-UI event streams. |
| 26 | +- The API should preserve the existing durable run identity rules from Phase 1 and Phase 2: one stable run record across pauses, resumes, approvals, and retries, with attempts nested under that same run. |
| 27 | + |
| 28 | +### Shared control-plane ownership |
| 29 | +- The source of truth for run control must move out of UI-specific entrypoints. Phase 6 should extract a shared orchestration service layer that both `command_center/` and later Azure Functions can call directly. |
| 30 | +- The existing `autogen_dashboard` session service, store, and schemas are the strongest donor assets for the durable run contract, but `command_center/` is now the active product surface and should consume the shared service rather than duplicate runtime ownership. |
| 31 | +- Phase 6 should treat `autogen_dashboard/` as a compatibility donor and migration source, not as the long-term primary operator surface described in older Phase 5 documents. |
| 32 | +- Route, stage, specialist, approval, validation, artifact, and workspace-freshness data should come from one shared run schema and service boundary rather than separate projections in `command_center/app.py` and `autogen_dashboard/app.py`. |
| 33 | + |
| 34 | +### Auth posture and local-versus-cloud boundary |
| 35 | +- Phase 6 should define an explicit request-auth boundary even if local development remains effectively open by default on loopback. Auth must be a pluggable policy, not handler-local branching. |
| 36 | +- The contract should be ready for Azure Functions host auth in Phase 7: local no-auth or dev-auth is acceptable now, but the API shape should already separate caller identity and authorization from the orchestration handlers. |
| 37 | +- The control-plane contract must not assume local CLI sessions, direct desktop access, or mutable local repo roots as part of the HTTP interface itself. Those are worker/runtime capabilities, not API invariants. |
| 38 | +- Capability and execution-mode information should be visible in API payloads so future cloud callers can understand whether a run is local-tool-capable, cloud-safe, paused for approval, or blocked by unavailable execution capabilities. |
| 39 | + |
| 40 | +### the agent's Discretion |
| 41 | +- Exact route and artifact endpoint naming as long as the API stays versioned, resource-oriented, and consistent across local UI and external callers. |
| 42 | +- Exact summary-versus-detail payload split as long as the default run summary is enough for dashboards and the detail surfaces expose timeline, routing, agents, and artifact drill-down cleanly. |
| 43 | +- Exact implementation placement of the shared control-plane package as long as it is not owned by one UI shell and remains reusable by both the Command Center and Azure Functions. |
| 44 | + |
| 45 | +</decisions> |
| 46 | + |
| 47 | +<canonical_refs> |
| 48 | +## Canonical References |
| 49 | + |
| 50 | +**Downstream agents MUST read these before planning or implementing.** |
| 51 | + |
| 52 | +### Product and milestone scope |
| 53 | +- `.planning/PROJECT.md` - defines the v1.1 milestone, local-first runtime, cloud API goal, and requirement that the HTTP API and operator surface share one orchestration contract. |
| 54 | +- `.planning/REQUIREMENTS.md` - defines `API-01`, `API-02`, `API-03`, and `API-04`, which Phase 6 must satisfy. |
| 55 | +- `.planning/ROADMAP.md` - defines the fixed Phase 6 boundary, success criteria, and plan split. |
| 56 | +- `.planning/STATE.md` - records the active milestone, blockers, and prior decisions that constrain the API design. |
| 57 | + |
| 58 | +### Prior phase contracts that Phase 6 must preserve |
| 59 | +- `.planning/phases/01-workspace-and-durable-run-foundation/01-CONTEXT.md` - locks durable run identity, workspace targeting, and workspace freshness rules. |
| 60 | +- `.planning/phases/02-manager-led-orchestration-core/02-CONTEXT.md` - locks the manager-owned stage machine, pause semantics, and stage visibility contract. |
| 61 | +- `.planning/phases/03-specialist-delegation-and-routing-visibility/03-CONTEXT.md` - locks specialist state, route-lane control, and planned-versus-actual route visibility. |
| 62 | +- `.planning/phases/04-autonomous-repo-execution-and-validation-guardrails/04-CONTEXT.md` - locks diff, validation, approval, and artifact semantics that the HTTP API must expose without reinterpretation. |
| 63 | +- `.planning/phases/05-polished-operator-workbench/05-CONTEXT.md` - captures the earlier UI assumptions and reveals where Phase 6 must realign ownership now that `command_center/` is the active shell. |
| 64 | + |
| 65 | +### Current runtime and API seams |
| 66 | +- `command_center/app.py` - current Command Center HTTP app, AG-UI endpoint registration, repo catalog, and status surface. |
| 67 | +- `maf_starter/cli.py` - current process entrypoints for UI and DevUI, which show how the product boots today. |
| 68 | +- `maf_starter/config.py` - current runtime configuration, repo-root scoping, and fallback chain settings that any shared API service must respect. |
| 69 | +- `maf_starter/orchestration.py` - canonical stage, specialist, pause, and artifact-path contract that the API must surface directly. |
| 70 | +- `maf_starter/routing_policy.py` - route-lane semantics and route planning rules that the API must expose consistently. |
| 71 | +- `maf_starter/provider_fallback.py` - active route/fallback metadata model and capability-drift behavior. |
| 72 | +- `autogen_dashboard/app.py` - existing REST-style session API with explicit run actions and SSE event feed; strongest donor for the HTTP contract. |
| 73 | +- `autogen_dashboard/schemas.py` - existing durable run schema for summary, detail, routing, agents, approvals, and artifacts. |
| 74 | +- `autogen_dashboard/session_runner.py` - existing session-service logic for run creation, control actions, and orchestration projection. |
| 75 | +- `autogen_dashboard/session_store.py` - existing file-backed durable run persistence and artifact manifest model. |
| 76 | + |
| 77 | +### Architecture and drift watchpoints |
| 78 | +- `.planning/codebase/ARCHITECTURE.md` - maps the current runtime split between MAF runtime, command center, and legacy dashboard service layer. |
| 79 | +- `.planning/codebase/STRUCTURE.md` - identifies where runtime ownership currently lives and where a shared control-plane package can be placed. |
| 80 | +- `.planning/codebase/CONCERNS.md` - documents the current drift between `command_center/`, `autogen_dashboard/`, and planning docs, which Phase 6 should reduce. |
| 81 | +- `README.md` - documents the current Command Center and DevUI launch surface and is the public-facing runtime reference that will need API updates. |
| 82 | + |
| 83 | +</canonical_refs> |
| 84 | + |
| 85 | +<code_context> |
| 86 | +## Existing Code Insights |
| 87 | + |
| 88 | +### Reusable Assets |
| 89 | +- `autogen_dashboard/session_runner.py`: already implements durable run creation, explicit control actions, stage-aware state projection, approvals, retries, and run summaries; this is the strongest donor for the shared control-plane service. |
| 90 | +- `autogen_dashboard/session_store.py`: already persists metadata, transcript, events, attempts, runtime state, stage outputs, validation results, and artifact manifests under a stable run directory layout. |
| 91 | +- `autogen_dashboard/schemas.py`: already provides a rich operator-facing run schema that includes workspace, routing, specialist, approval, and artifact data. |
| 92 | +- `autogen_dashboard/app.py`: already demonstrates a REST-like action surface for sessions and can inform the Phase 6 HTTP route structure. |
| 93 | +- `command_center/app.py`: already owns the active product HTTP app, repo catalog, status surface, and AG-UI streaming integration, making it the natural host for the new shared API layer once the runtime ownership is extracted. |
| 94 | + |
| 95 | +### Established Patterns |
| 96 | +- Durable run state is file-backed, JSON-oriented, and explicitly modeled rather than implicit in chat history. |
| 97 | +- Manager, stage, routing, specialist, approval, validation, and artifact semantics are already shared concepts across the runtime and should remain the vocabulary of the API. |
| 98 | +- UI-specific protocol surfaces exist beside richer REST-like session surfaces; Phase 6 should reduce this duplication by extracting shared control services instead of growing both paths. |
| 99 | +- Local development is Windows-first and loopback-hosted, but the milestone explicitly requires a cloud-safe API contract that does not hard-wire local CLI assumptions into the HTTP layer. |
| 100 | + |
| 101 | +### Integration Points |
| 102 | +- A new host-agnostic control-plane service should sit between `command_center/app.py` and the existing `autogen_dashboard` session logic so both the UI and future Azure Functions host can drive the same run contract. |
| 103 | +- `command_center/app.py` should evolve from a thin AG-UI shell into a consumer of the shared run-control endpoints rather than owning separate runtime concepts. |
| 104 | +- `autogen_dashboard/app.py` should either delegate to the same shared service or be treated as a compatibility wrapper until it can be retired. |
| 105 | +- `maf_starter/cli.py` and `main.py` are the current process entrypoints and should remain thin after the control-plane extraction. |
| 106 | + |
| 107 | +</code_context> |
| 108 | + |
| 109 | +<specifics> |
| 110 | +## Specific Ideas |
| 111 | + |
| 112 | +- The external API should feel like an enterprise run-control surface, not a thin wrapper over browser interactions. |
| 113 | +- AG-UI and DevUI stay useful, but they should sit on top of the same run contract rather than define it. |
| 114 | +- The operator UI should eventually be able to fetch run status, routing, agents, timeline, and artifacts from the same endpoints that Azure Functions will expose. |
| 115 | +- Phase 6 should explicitly clean up the current planning drift: `command_center/` is the active UI, while `autogen_dashboard/` is now a donor runtime and compatibility layer. |
| 116 | + |
| 117 | +</specifics> |
| 118 | + |
| 119 | +<deferred> |
| 120 | +## Deferred Ideas |
| 121 | + |
| 122 | +- Azure Functions host wiring, local Core Tools validation, and cloud route/auth settings - Phase 7 |
| 123 | +- Background worker boundary, cloud-safe execution profiles, and local-only provider rejection/rerouting - Phase 8 |
| 124 | +- Shared multi-user auth, external operator collaboration, and broader product tenancy - later milestone |
| 125 | + |
| 126 | +</deferred> |
| 127 | + |
| 128 | +--- |
| 129 | + |
| 130 | +*Phase: 06-api-boundary-and-control-plane-contract* |
| 131 | +*Context gathered: 2026-03-22* |
0 commit comments