stable-harness 0.0.140 → 0.0.144

package/docs/protocols/coverage-matrix.md

@@ -0,0 +1,114 @@
+# Protocol Feature Coverage Matrix
+
+This page is the side-by-side support contract for Stable Harness protocols.
+It shows which runtime features and APIs are available through each protocol,
+where support is native, and where a protocol cannot expose the full Stable
+Runtime control-plane feature.
+
+The Stable Harness gateway is the public API entry point. It listens on
+`http://127.0.0.1:56789` by default, exposes first-party runtime APIs at
+`/runtime/v1`, and groups external protocol-compatible surfaces under
+`/protocols/*`.
+
+## Legend
+
+| Status | Meaning |
+| --- | --- |
+| Native | The protocol directly implements this feature with its own endpoint or method. |
+| Bridge | The feature is available through the first-party `/runtime/v1` API. |
+| Extension | Stable Harness exposes the feature through a typed extension field in the protocol payload. |
+| Partial | The protocol exposes a related concept, but not the full Stable Runtime contract. |
+| No | Not supported on that protocol. The reason is listed in the notes. |
+
+## Protocol Entry Points
+
+| Protocol surface | Default endpoint | Primary clients | Owner | Notes |
+| --- | --- | --- | --- | --- |
+| Gateway manifest | `http://127.0.0.1:56789/manifest` | Stable Harness Studio, SDKs, operators | Stable Harness | Declares product version, runtime API version, protocol base paths, capabilities, and known limitations. |
+| Protocol index | `http://127.0.0.1:56789/protocols` | Stable Harness Studio, SDKs, operators | Stable Harness | Lists protocol base paths and protocol/path versions. Each protocol also exposes `GET /protocols/<id>/version`. |
+| Stable Runtime HTTP + SSE | `http://127.0.0.1:56789/runtime/v1` | Stable Harness Studio, operator dashboards, SDKs, CLI daemon clients | Stable Harness | Canonical runtime and control-plane API. |
+| OpenAI-compatible | `http://127.0.0.1:56789/protocols/openai/v1` | OpenAI SDK-compatible chat clients | Stable Harness facade | Chat API is OpenAI-shaped; runtime control plane remains `/runtime/v1`. |
+| LangGraph-compatible | `http://127.0.0.1:56789/protocols/langgraph` | LangSmith Studio, LangGraph SDK, LangGraph CLI clients | LangGraph Agent Server | Stable Harness generates the workspace graph and environment; the internal HTTP router is upstream-owned. |
+| MCP | `http://127.0.0.1:56789/protocols/mcp` | MCP streamable HTTP clients | Stable Harness LangGraph facade | Exposes workspace tools, exposed agents, and reachable nested subagents as MCP tools for LangSmith Agent Server compatibility. |
+| ACP | `http://127.0.0.1:56789/protocols/acp` | ACP JSON-RPC clients and `stable-harness acp-stdio` | Stable Harness facade | Prompt/session APIs are native ACP. |
+| A2A | `http://127.0.0.1:56789/protocols/a2a` | A2A JSON-RPC clients | Stable Harness facade | Message/task APIs are native A2A. |
+| AG-UI | `http://127.0.0.1:56789/protocols/ag-ui` | AG-UI clients | Stable Harness facade | Run/event APIs are native AG-UI. |
+
+## System Data Support
+
+The protocol APIs read the same daemon control-plane state. `stable-harness
+start` resolves `runtime.dataRoot` and defaults to `.stable-harness`:
+
+| Data family | Default location | Source of truth | Protocol visibility |
+| --- | --- | --- | --- |
+| Runs, events, sessions, approvals, queue, recovery intents, artifact metadata | `.stable-harness/control-plane/stable.sqlite` | Stable Harness | Stable Runtime native; protocol facades project the same records where their standards allow it. |
+| Artifact content | `.stable-harness/artifacts/` | Stable Harness | Stable Runtime native; replay and protocol task/run projections include metadata and supported content reads. |
+| LangMem records and vector recall index | `.stable-harness/memory/langmem/langmem.sqlite` | LangMem provider under Stable Harness lifecycle | Stable Runtime memory APIs; other protocols use the Stable Runtime bridge. |
+| DeepAgents checkpoints | `.stable-harness/checkpoints/deepagents.sqlite` | DeepAgents substrate | Used for backend execution lifecycle, not exposed as a protocol data API. |
+| DeepAgents/LangGraph Store | `.stable-harness/store/deepagents.sqlite` | Upstream store substrate | LangGraph-compatible Store can see projected memory/resource files. |
+| LangGraph compatibility files | `.stable-harness/langgraph/` | Generated projection | LangGraph/LangSmith clients load the projection; Stable Harness source of truth remains the runtime stores. |
+
+## Feature Coverage
+
+| Feature or API family | Stable Runtime HTTP + SSE | OpenAI-compatible | LangGraph-compatible | ACP | A2A | AG-UI | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Health check | Native `GET /health` | Bridge | Partial | Native plus Bridge | Native plus Bridge | Native plus Bridge | LangGraph has upstream health and info routes, not the Stable Runtime health object. |
+| Workspace inspection | Native `GET /inspect` | Native `/v1/stable-harness/inspect` plus Bridge | Partial | Native `runtime/inspect` plus Bridge | Native `/a2a/inspect` plus Bridge | Native `/ag-ui/inspect` plus Bridge | LangGraph exposes graph and schema metadata; Stable Runtime inventory is first-party on Stable Harness protocol facades. |
+| Submit prompt run | Native `POST /runs` plus `/requests` alias | Native `POST /v1/chat/completions`, `POST /v1/responses` | Native runs and threads | Native `session/prompt` | Native `message:send` and `message:stream` | Native `POST /ag-ui/runs` | All paths execute real Stable Harness workspace requests or upstream graph runs. |
+| Streaming prompt output | Native `GET /events` | Native chat stream plus Bridge | Native upstream run stream | Native protocol stream plus Bridge | Native `message/stream` plus Bridge | Native event stream with tool events plus Bridge | OpenAI streams are scoped to one chat completion; Stable Runtime SSE is the full control-plane event source. |
+| Explicit agent selection | Native `agentId` | Native model-to-agent mapping | Native graph or assistant id | Extension `agentId` | Extension `agentId` | Extension `agentId` | Protocol facades do not infer agents from user prose. |
+| Explicit tool call | Native `toolCall` | Bridge | No | Extension plus Bridge | Extension plus Bridge | Extension plus Bridge | OpenAI client `tools` and `tool_choice` are not replayed as Stable Harness tool calls; use the typed runtime request. |
+| Workflow run | Native `workflow` | Bridge | Partial | Extension plus Bridge | Extension plus Bridge | Extension plus Bridge | LangGraph runs execute graphs; Stable Harness workflow dispatch remains a Stable Runtime request. |
+| Request list, inspect, cancel, delete | Native `/runs/*` plus `/requests/*` alias | Native `/v1/responses/:id`, delete, cancel plus Bridge | Partial | Bridge | Native task list/get/history/cancel plus Bridge | Native AG-UI run state plus Bridge | A2A task APIs now include runtime-backed history; Stable Runtime delete remains bridged. |
+| Session list, delete, and history | Native `/sessions/*` | Bridge | Partial | Native list/load/close plus Bridge | Partial plus Bridge | Partial plus Bridge | ACP sessions, A2A context/task ids, and AG-UI thread ids do not replace full runtime session history. |
+| Runtime event replay and filters | Native `GET /events`, `GET /runs/:id/events` | Native `/v1/stable-harness/runs/:id/events` plus Bridge | Partial | Bridge | Native stream partial plus Bridge | Native run replay with resume cursor plus Bridge | LangGraph has upstream run streams; Stable Runtime filtered replay is on the Stable Runtime port. |
+| Trace timeline | Native `GET /runs/:id/trace` | Native `/v1/stable-harness/runs/:id/trace` plus Bridge | Partial | Native `runtime/trace` plus Bridge | Native `/a2a/tasks/:id/trace` plus Bridge | Native `/ag-ui/runs/:id/trace` plus Bridge | LangGraph traces can be viewed through LangSmith separately; Stable Harness trace records are first-party runtime data. |
+| Span tree projection | Native `GET /runs/:id/spans` | Native `/v1/stable-harness/runs/:id/spans` plus Bridge | Partial | Native `runtime/spans` plus Bridge | Native `/a2a/tasks/:id/spans` plus Bridge | Native `/ag-ui/runs/:id/spans` plus Bridge | Span tree rendering is Stable Runtime-owned. |
+| Approval queues and decisions | Native `/approvals/*` | Native `/v1/approvals/*` plus Bridge | No | Native `/approvals/*` plus Bridge | Native `/approvals/*` plus Bridge | Native `/approvals/*` plus Bridge | LangGraph server does not expose Stable Harness approval queue routes. |
+| Memory administration and recall | Native `/memories/*` | Bridge | Partial | Bridge | Bridge | Bridge | LangGraph has its own store concepts; the bridge projects Stable Harness memory profiles into Agent Server Store files and reads edited Store memory back as run context. Stable Runtime memory lifecycle is available from Stable Runtime. |
+| Artifact import, read, and replay | Native `/artifacts/*`, `/requests/:id/replay` | Native `/v1/stable-harness/runs/:id/replay` plus Bridge | No | Native `runtime/replay` plus Bridge | Native task artifacts and `/a2a/tasks/:id/replay` plus Bridge | Native `/ag-ui/runs/:id/replay` plus Bridge | A2A exposes final output, stored runtime artifacts, and replay bundles on tasks; artifact content reads and imports remain bridged. |
+| Workflow inventory and render | Native `/workflows/*` | Bridge | Partial | Bridge | Bridge | Bridge | LangGraph can expose graph schemas; Stable Harness workflow Mermaid and plan views are Stable Runtime APIs. |
+| Metrics | Native `GET /metrics` | Native `GET /metrics` plus Bridge | Partial | Native `GET /metrics` plus Bridge | Native `GET /metrics` plus Bridge | Native `GET /metrics` plus Bridge | LangGraph observability is upstream-owned; Stable Runtime metrics are served by Stable Harness. |
+| Bearer-token auth | Native | Native | Upstream-dependent | Native | Native | Native | Stable Runtime and protocol facades can protect native routes with bearer tokens. LangGraph auth remains upstream-owned. |
+| Browser CORS helper | No | Native loopback CORS | Upstream-dependent | No | No | No | OpenAI-compatible browser clients are the current built-in CORS target. |
+| Stdio transport | No | No | No | Native `acp-stdio` | No | No | Only ACP has a Stable Harness stdio command. |
+
+## Native Stable Runtime API Families
+
+These APIs are available under `/runtime/v1` on the Stable Harness gateway.
+
+| API family | Endpoints |
+| --- | --- |
+| Runtime health and inventory | `GET /health`, `GET /metrics`, `GET /inspect` |
+| Requests and runs | `POST /runs`, `GET /runs`, `GET /runs/:id`, `POST /runs/:id/cancel`, `DELETE /runs/:id`, plus `/requests` aliases |
+| Trace and spans | `GET /runs/:id/trace`, `GET /runs/:id/spans` |
+| Runtime events | `GET /events?...`, `GET /runs/:id/events?...` |
+| Sessions | `GET /sessions`, `DELETE /sessions/:id` |
+| Workflows | `GET /workflows`, `GET /workflows/:id/mermaid`, `GET /workflows/:id/plan` |
+| Approvals | `GET /approvals?status=...`, `POST /approvals/:id/approve`, `POST /approvals/:id/reject` |
+| Memory | `POST /memories`, `GET /memories?namespace=...`, `POST /memories/recall`, `PATCH /memories/:id`, `POST /memories/:id/archive` |
+| Artifacts and replay | `GET /artifacts`, `POST /artifacts`, `GET /artifacts/:id`, `GET /artifacts/:id/content`, `GET /runs/:id/replay`, plus `/requests/:id/replay` alias |
+
+## Native Facade API Families
+
+| Protocol | Native APIs | Full-control-plane path |
+| --- | --- | --- |
+| OpenAI-compatible | `/protocols/openai/v1/models`, `/protocols/openai/v1/chat/completions`, `/protocols/openai/v1/responses`, `/protocols/openai/v1/responses/:id`, `/protocols/openai/v1/responses/:id/cancel`, `/protocols/openai/v1/capabilities` | `/runtime/v1` |
+| LangGraph-compatible | `/protocols/langgraph` upstream Agent Server assistant, thread, run, stream, store, and schema routes; Stable Harness projects memory, skills, subagents, and tools into Store files | `/runtime/v1` |
+| MCP | `/protocols/mcp` initialize, `tools/list`, and `tools/call` for workspace tools, agents, and reachable nested subagents, with stable aliases for name collisions | `/runtime/v1` |
+| ACP | `/protocols/acp` JSON-RPC initialize, session, prompt, cancel, workspace inspection, runtime inspection, approvals, metrics, and stdio methods | `/runtime/v1` |
+| A2A | `/protocols/a2a` agent card, workspace inspection, task, message, stream, cancel, approvals, and metrics methods | `/runtime/v1` |
+| AG-UI | `/protocols/ag-ui` workspace inspection, run, event stream, trace, span, replay, approvals, and metrics methods | `/runtime/v1` |
+
+## Unsupported Or Limited Areas
+
+| Area | Status | Reason |
+| --- | --- | --- |
+| LangGraph in-router Stable Runtime bridge | Not supported | The official LangGraph Agent Server owns its HTTP router. Stable Runtime control-plane APIs are grouped at `/runtime/v1` on the gateway. |
+| LangGraph cron routes | Not implemented upstream | Current JS LangGraph Agent Server cron endpoints are not faked by Stable Harness. Use Stable Runtime scheduling or an external scheduler when needed. |
+| LangGraph Agent Server MCP full session semantics | Partial | Stable Harness supports stateless `/mcp` initialization, `tools/list`, and `tools/call` for workspace tools, exposed agents, and reachable nested subagents. The current LangGraph MCP implementation is documented as stateless, so Stable Harness does not add MCP session state. |
+| OpenAI client-supplied `tools` and `tool_choice` | Not mapped to runtime tool execution | Stable Harness tool execution is governed by typed workspace inventory and explicit `RuntimeRequest.toolCall`, not arbitrary client-side tool definitions. |
+| ACP client file and terminal requests | Not implemented | Stable Harness does not ask ACP clients to perform local filesystem or terminal operations. Use governed workspace tools instead. |
+| A2A push notifications | Supported | Stable Harness stores task push notification config and posts task update payloads to the configured webhook. |
+| AG-UI reconnect resume | Supported | AG-UI run state and replayable run event endpoints are available with SSE event IDs and `Last-Event-ID` or query cursor resume. |
+| LangGraph auth | Upstream-dependent | LangGraph Agent Server authentication is owned by upstream LangGraph deployment settings, not Stable Harness protocol code. |

package/docs/protocols/http-runtime.md

@@ -8,12 +8,15 @@ OpenAI-compatible `/v1`, LangGraph-compatible, ACP, A2A, and AG-UI servers are
 ecosystem facades. They adapt external protocols to this contract rather than
 adding new runtime semantics.
 
+For the side-by-side feature and API support list, see the
+[Protocol Feature Coverage Matrix](./coverage-matrix.md).
+
 ## HTTP Commands And Queries
 
 `stable-harness start` exposes this protocol by default at:
 
 ```text
-http://127.0.0.1:8641
+http://127.0.0.1:56789/runtime/v1
 ```
 
 Configure it from runtime YAML:
@@ -23,14 +26,21 @@ apiVersion: stable-harness.dev/v1
 kind: Runtime
 spec:
   protocols:
-    stableRuntime:
+    gateway:
       enabled: true
       host: 127.0.0.1
-      port: 8641
+      port: 56789
+      bearerToken: ${env:STABLE_HARNESS_API_KEY}
 ```
 
-`POST /requests` is a protocol adapter over `RuntimeRequest`. It may pass these
-stable fields through to the runtime:
+When `bearerToken` or `apiKey` is configured, every native Stable Runtime
+route requires `Authorization: Bearer <token>`. The CLI daemon client reads the
+same runtime setting, and `--api-key` can override it for local commands.
+
+`POST /runs` is the recommended HTTP entrypoint for creating a Stable Runtime
+execution. `POST /requests` remains a compatibility alias over the same
+`RuntimeRequest` contract. Both forms may pass these stable fields through to
+the runtime:
 
 - `input`
 - `agentId`
@@ -46,15 +56,25 @@ The endpoint must not infer backend behavior, choose tools from prose, or
 rewrite workflow routes. Tool execution and workflow dispatch remain explicit
 runtime requests.
 
-Inspection endpoints expose normalized runtime state:
+Inspection endpoints expose normalized runtime state. Prefer `/runs` for new
+Studio and SDK clients; `/requests` remains supported for existing low-level
+runtime clients:
 
 - `GET /inspect`
+- `POST /runs`
+- `GET /runs?sessionId=...&agentId=...&state=...`
+- `GET /runs/:id`
+- `POST /runs/:id/cancel`
+- `DELETE /runs/:id`
+- `GET /runs/:id/events`
+- `GET /runs/:id/replay`
+- `GET /runs/:id/trace`
+- `GET /runs/:id/spans`
 - `GET /requests?sessionId=...&agentId=...&state=...`
 - `GET /requests/:id`
 - `POST /requests/:id/cancel`
 - `DELETE /requests/:id`
-- `GET /runs/:id/trace`
-- `GET /runs/:id/spans`
+- `GET /requests/:id/replay`
 - `GET /sessions`
 - `DELETE /sessions/:id`
 - `GET /workflows`
@@ -93,6 +113,8 @@ display labels.
 `GET /events` streams normalized `RuntimeEvent` records as Server-Sent Events.
 It replays matching stored events first, then streams new events from
 `runtime.subscribe`.
+`GET /runs/:id/events` is the run-scoped alias for the same stream and accepts
+the same query filters except `requestId`, which comes from the path.
 
 Supported filters:
 
@@ -107,6 +129,7 @@ Example:
 
 ```text
 GET /events?sessionId=customer-123&types=runtime.request.*,runtime.approval.*
+GET /runs/request-123/events?types=runtime.request.completed
 ```
 
 Event format:

package/docs/protocols/langgraph-compatible.md

@@ -14,16 +14,23 @@ upstream LangGraph.
 - keep OpenAI-compatible and LangGraph-compatible services under one runtime
   start command
 
+For side-by-side support across all protocol surfaces, see the
+[Protocol Feature Coverage Matrix](./coverage-matrix.md).
+
 ## Defaults
 
-`stable-harness start` starts the Stable Runtime control plane plus both
-ecosystem facades by default:
+`stable-harness start` starts one public gateway by default:
 
-| Service | Default host | Default port |
-| --- | --- | --- |
-| Stable Runtime HTTP + SSE | `127.0.0.1` | `8641` |
-| OpenAI-compatible | `127.0.0.1` | `8642` |
-| LangGraph-compatible | `127.0.0.1` | `2024` |
+| Surface | Default endpoint |
+| --- | --- |
+| Gateway manifest | `http://127.0.0.1:56789/manifest` |
+| Stable Runtime HTTP + SSE | `http://127.0.0.1:56789/runtime/v1` |
+| OpenAI-compatible | `http://127.0.0.1:56789/protocols/openai/v1` |
+| LangGraph-compatible | `http://127.0.0.1:56789/protocols/langgraph` |
+| MCP | `http://127.0.0.1:56789/protocols/mcp` |
+| ACP | `http://127.0.0.1:56789/protocols/acp` |
+| A2A | `http://127.0.0.1:56789/protocols/a2a` |
+| AG-UI | `http://127.0.0.1:56789/protocols/ag-ui` |
 
 Configure or disable services from runtime YAML:
 
@@ -32,19 +39,13 @@ apiVersion: stable-harness.dev/v1
 kind: Runtime
 spec:
   protocols:
-    stableRuntime:
-      enabled: true
+    gateway:
       host: 127.0.0.1
-      port: 8641
+      port: 56789
     openaiCompatible:
       enabled: true
-      host: 127.0.0.1
-      port: 8642
-      bearerToken: ${env:STABLE_HARNESS_OPENAI_API_KEY:-}
     langgraph:
       enabled: true
-      host: 127.0.0.1
-      port: 2024
       nWorkers: 10
       env: .env
       exposeAgents:
@@ -67,11 +68,68 @@ The LangGraph service is started through the official
 upstream LangGraph behavior. `stable-harness` only loads the environment before
 that server starts.
 
+Current Agent Server compatibility is intentionally passthrough-first:
+
+| Agent Server surface | Status | Notes |
+| --- | --- | --- |
+| System/info | Supported | Served by the official LangGraph server. |
+| Assistants | Supported | YAML agents are projected as graph IDs. |
+| Threads | Supported | Thread creation, state, and thread runs are handled upstream. |
+| Stateful runs | Supported | `threads/{thread_id}/runs/stream` calls the generated Stable Harness bridge graph. |
+| Stateless runs | Supported | `/runs/stream` calls the same generated bridge graph without a thread. |
+| Store | Supported | The upstream namespaced store endpoints are available to LangSmith Studio/Fleet clients. Stable Harness projects agent memory files, skill files, subagent summaries, and tool inventory into the Agent Server Store. |
+| Graph inspection | Supported | The generated graph exposes tools, subagents, skills, and memory nodes for Studio inspection, and graph inspection seeds the matching Store files so Studio can discover them before the first run. |
+| MCP | Supported | `/mcp` exposes Stable Harness workspace tools, exposed agents, and exposed agents' reachable subagents as MCP tools on the LangGraph-compatible Agent Server port. Tool calls execute through the Stable Harness runtime. |
+| A2A | Supported | `/.well-known/agent-card.json?assistant_id=...` and `/a2a/{assistant_id}` expose LangSmith Agent Server-style A2A access for each projected agent. |
+| Crons | Upstream unavailable | The current `@langchain/langgraph-api` JS server exposes cron routes but returns `Not implemented`; Stable Harness does not fake a cron surface. |
+
 Native Stable Harness spans can also be exported to LangSmith. This is separate
 from LangGraph's upstream tracing path: it projects stored runtime events through
 `projectRuntimeTraceSpans(run)` and writes the resulting run tree to LangSmith at
 request completion.
 
+### Store projection for LangSmith Studio
+
+LangSmith Studio and Fleet treat long-term memory as Agent Server Store data.
+Stable Harness therefore projects workspace-owned inventory into the upstream
+Store when the bridge graph is inspected or executed:
+
+- `/AGENTS.md` summarizes the selected Stable Harness agent.
+- `/memories/*.md` exposes configured Stable Harness memory profiles.
+- `/skills/*/SKILL.md` exposes workspace skills when they are attached to the
+  agent.
+- `/subagents/*.md` exposes declared subagent inventory.
+- `/tools.json` exposes model-visible tool metadata.
+
+These Store files are compatibility projections. Stable Harness remains the
+native owner for memory governance, memory providers, approvals, lifecycle
+events, replay, and diagnostics. If a LangSmith client edits Store memory files,
+the bridge reads those files back as Agent Server long-term memory context on
+subsequent LangGraph runs.
+
+### MCP and A2A compatibility routes
+
+The current JS `@langchain/langgraph-api` server package does not mount the
+LangSmith Agent Server `/mcp` or `/a2a/{assistant_id}` routes that are documented
+for Agent Server deployments. Stable Harness registers a small custom HTTP app on
+the same official LangGraph server so these routes are available without
+replacing the upstream assistant, thread, run, stream, store, or schema router.
+
+- `/mcp` supports JSON-RPC initialization, `tools/list`, and `tools/call`.
+  `tools/list` includes workspace tools, exposed Stable Harness agents, and the
+  nested subagents reachable from those exposed agents. Workspace tool calls run
+  as native Stable Harness direct tool calls; agent and subagent calls run as
+  runtime agent requests. Unique tool, agent, and subagent IDs are exposed under
+  their Stable Harness IDs; collisions remain visible with stable aliases such as
+  `tool__{id}`, `agent__{id}`, or `subagent__{id}`.
+- `/.well-known/agent-card.json?assistant_id=...` returns an A2A agent card for
+  the selected projected agent.
+- `/a2a/{assistant_id}` supports `message/send`, `message/stream`, and
+  `tasks/get` over JSON-RPC.
+
+These routes execute through Stable Harness runtime requests and preserve
+`metadata.protocol` as `langgraph-mcp` or `langgraph-a2a`.
+
 Enable native export in runtime YAML:
 
 ```yaml
@@ -115,10 +173,10 @@ spec:
       #   LANGSMITH_PROJECT: local-studio
 ```
 
-When the server prints the LangGraph URL, open Studio with:
+When the server prints the gateway URL, open Studio with the LangGraph path:
 
 ```text
-https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
+https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:56789/protocols/langgraph
 ```
 
 ## Generated Bridge

package/docs/protocols/openai-compatible.md

@@ -4,23 +4,39 @@
 
 This surface is for client compatibility. It is not a model provider, a backend adapter, or a new execution framework.
 
+For side-by-side support across all protocol surfaces, see the
+[Protocol Feature Coverage Matrix](./coverage-matrix.md).
+
 ## Supported MVP Surface
 
 - `GET /v1/models`
 - `GET /v1/capabilities`
 - `POST /v1/chat/completions`
+- `POST /v1/responses`
+- `GET /v1/responses/:response_id`
+- `DELETE /v1/responses/:response_id`
+- `POST /v1/responses/:response_id/cancel`
+- `GET /v1/stable-harness/inspect`
 - `stream: true` Server-Sent Events for chat completion chunks
+- `stream: true` Server-Sent Events for Responses API events
 - `stable_harness.tool.progress` SSE events for runtime tool progress
 - `stable_harness.progress.narration` SSE events for runtime progress narration
+- `GET /v1/stable-harness/runs/:id/trace`
+- `GET /v1/stable-harness/runs/:id/spans`
+- `GET /v1/stable-harness/runs/:id/replay`
+- `GET /v1/stable-harness/runs/:id/events`
+- `/runtime/v1/*` gateway route to the native Stable Runtime control plane
 
 The `model` field maps to workspace agent IDs. `/v1/models` lists all workspace agents by default.
+`GET /v1/capabilities` lists every native OpenAI-compatible endpoint above,
+including the Stable Harness run inspection APIs and supported event filters.
 
 ## Local Launch
 
 From a workspace checkout:
 
 ```sh
-stable-harness start -w "$PWD" --port 8642 --api-key change-me-local-dev
+stable-harness start -w "$PWD" --port 56789 --api-key change-me-local-dev
 ```
 
 For embedded applications, the server can read auth settings from runtime YAML:
@@ -32,7 +48,7 @@ metadata:
   name: app-runtime
 spec:
   protocols:
-    openaiCompatible:
+    gateway:
       bearerToken: ${env:STABLE_HARNESS_API_KEY}
 ```
 
@@ -46,7 +62,7 @@ const server = createOpenAiCompatibleHttpServer(runtime);
 Then point OpenAI-compatible clients at:
 
 ```text
-http://127.0.0.1:8642/v1
+http://127.0.0.1:56789/protocols/openai/v1
 ```
 
 For local-only development, auth is optional. When binding beyond loopback, run behind a trusted network boundary and set a bearer token in runtime YAML or pass `--api-key` as an override.
@@ -73,6 +89,12 @@ It must not:
 
 Client `tools` and `tool_choice` fields are ignored by this facade. Runtime tools still come from workspace inventory, governance policy, and the tool gateway.
 
+The gateway also exposes the native Stable Runtime control plane at
+`/runtime/v1/*`, protected by the same bearer-token setting. Use that route for
+sessions, requests, traces, approvals, memory administration, artifacts,
+workflows, replay bundles, metrics, and native event streams when an
+application is connected through the OpenAI-compatible facade.
+
 ## Message Mapping
 
 `messages` are flattened into a text transcript:
@@ -112,10 +134,6 @@ the final assistant message.
 
 Add these only after the chat-completions subset is stable:
 
-- `POST /v1/responses`
-- `previous_response_id` state handling
-- persisted response lookup
-- run event polling endpoints
 - idempotency-key response caching
 
 Each addition should remain a protocol adapter over native runtime state.

package/docs/protocols/{agent-protocols.md → protocol-facades.md}

@@ -5,38 +5,67 @@ Stable Runtime request, event, and inspection surfaces. These adapters must not
 add routing heuristics, backend execution semantics, or workspace-specific
 behavior.
 
-Enable the combined protocol server from runtime YAML:
+For side-by-side support across all protocol surfaces, see the
+[Protocol Feature Coverage Matrix](./coverage-matrix.md).
+
+By default, `stable-harness start` / `stable-harness serve` exposes every
+enabled protocol through the single Stable Harness gateway. Runtime YAML can
+disable individual protocols or override the gateway host and port.
+
+Enable individual protocol servers from runtime YAML:
 
 ```yaml
 apiVersion: stable-harness.dev/v1
 kind: Runtime
 spec:
   protocols:
-    agentProtocols:
+    gateway:
       enabled: true
       host: 127.0.0.1
-      port: 8650
-      protocols: [acp, a2a, agui]
+      port: 56789
+    acp:
+      enabled: true
+    a2a:
+      enabled: true
+    agui:
+      enabled: true
 ```
 
-You can also enable a single protocol by configuring one of `acp`, `a2a`, or
-`agui` with `enabled: true`. The CLI starts one combined HTTP server for the
-enabled adapter set.
+Protocol facades use stable gateway paths:
+
+| Protocol | Default URL |
+| --- | --- |
+| ACP | `http://127.0.0.1:56789/protocols/acp` |
+| A2A | `http://127.0.0.1:56789/protocols/a2a` |
+| AG-UI | `http://127.0.0.1:56789/protocols/ag-ui` |
+
+TCP ports must be between `0` and `65535`; the Stable Harness gateway default
+is `56789`.
 
 Shared discovery endpoints:
 
 - `GET /health`
 - `GET /capabilities`
+- `GET /metrics`
+- `GET /approvals?status=pending`
+- `POST /approvals/:id/approve`
+- `POST /approvals/:id/reject`
 
 `/capabilities` returns a normalized manifest with enabled protocol IDs,
 transports, session mapping level, and whether the protocol exposes the full
 operator session API. ACP/A2A/AG-UI report `operatorApi: false`; Stable Runtime
-HTTP/SSE remains the first-party operator API.
+HTTP/SSE remains the first-party operator API and is exposed by the gateway at
+`/runtime/v1/*`.
+`/metrics` returns the same Stable Runtime Prometheus metrics exposed by the
+first-party runtime server.
+The approval routes expose the same Stable Runtime governance queue and
+decision operations as the first-party runtime server.
 
 These facades preserve protocol-native continuity, but they are not the full
-Stable Runtime operator API. Stable Runtime HTTP/SSE and the SDK remain the
-first-party surfaces for listing sessions, deleting session history, inspecting
-requests, managing memory, approvals, artifacts, and native event filters.
+Stable Runtime operator API by themselves. The gateway also exposes the native
+control plane under `/runtime/v1/*` for listing sessions, deleting session
+history, inspecting requests, managing memory, approvals, artifacts, workflows,
+replay bundles, metrics, and native event filters.
 
 Reconnect and replay behavior is intentionally layered:
 
@@ -45,7 +74,7 @@ Reconnect and replay behavior is intentionally layered:
 | Stable Runtime SSE | Replays stored runtime events when clients reconnect with request/session/type filters. |
 | A2A streaming | Emits live task status updates for a request stream. |
 | A2A task subscribe | Replays the current task snapshot and streams future updates when the task is still running. |
-| AG-UI stream | Emits one run stream; use Stable Runtime SSE for first-party replay/resume. |
+| AG-UI stream | Emits one run stream; `GET /ag-ui/runs/:runId/events` replays stored run events and accepts `Last-Event-ID`, `afterEventId`, or `after` resume cursors. |
 | ACP stdio/HTTP | Session IDs resume prompt continuity; progress replay is not provided through ACP. |
 
 For external SDK compatibility status, see
@@ -57,6 +86,7 @@ A2A is exposed as an HTTP+JSON and SSE facade:
 
 - `GET /.well-known/agent-card.json`
 - `GET /a2a/agent-card.json`
+- `GET /a2a/inspect`
 - `POST /a2a/message:send`
 - `POST /a2a/message:stream`
 - `POST /a2a/rpc`
@@ -64,6 +94,11 @@ A2A is exposed as an HTTP+JSON and SSE facade:
 - `GET /a2a/tasks/:id`
 - `POST /a2a/tasks/:id:cancel`
 - `GET /a2a/tasks/:id:subscribe`
+- `GET /a2a/tasks/:id/trace`
+- `GET /a2a/tasks/:id/spans`
+- `GET /a2a/tasks/:id/replay`
+- `GET /a2a/tasks/:id/pushNotificationConfig`
+- `POST /a2a/tasks/:id/pushNotificationConfig:set`
 
 `message:send` and JSON-RPC `SendMessage` map to a native `RuntimeRequest`.
 Streaming responses subscribe to native runtime events and project them as A2A
@@ -82,20 +117,28 @@ Compliance notes:
 | Capability | Status | Notes |
 | --- | --- | --- |
 | Agent card | Supported | Exposed at `/.well-known/agent-card.json` and `/a2a/agent-card.json`. |
+| Workspace inspection | Supported | `GET /a2a/inspect` exposes the Stable Runtime workspace inventory behind the A2A facade. |
 | Version header | Supported | Empty, `0.3`, and `1.0` are accepted; unsupported versions fail clearly. |
 | Send message | Supported | Returns a Task backed by a Stable Runtime request. |
 | Streaming message | Supported | Emits an initial Task snapshot, then task status update events, then closes on completion. |
-| Task artifacts | Supported | Final text output is exposed as an output artifact while status messages remain available. |
-| Task subscription | Partial | `GET /a2a/tasks/:id:subscribe` replays the current task and streams future runtime updates for running tasks. |
-| Push notifications | Not implemented | Capability advertises `pushNotifications: false`; use Stable Runtime SSE or A2A streaming. |
-| Full task history | Partial | Stable Runtime stores request records; A2A history projection is intentionally limited. |
+| Task artifacts | Supported | Final text output and stored Stable Runtime artifacts are exposed as A2A task artifacts. Runtime artifact metadata is preserved on each artifact. |
+| Task subscription | Supported | `GET /a2a/tasks/:id:subscribe` replays the current task, including history, and streams future runtime updates for running tasks. |
+| Trace, spans, and replay | Supported | `GET /a2a/tasks/:id/trace`, `/spans`, and `/replay` expose the stored Stable Runtime run record behind the A2A task. |
+| Push notifications | Supported | Task push notification config can be supplied with send requests or managed with task config endpoints; the server posts task update payloads to the configured webhook. |
+| Full task history | Supported | `GET /a2a/tasks/:id` projects stored Stable Runtime timeline events as A2A task history messages and preserves the original runtime event in message metadata. |
 
 ## AG-UI
 
 AG-UI is exposed as an HTTP+SSE event stream:
 
 - `GET /ag-ui/capabilities`
+- `GET /ag-ui/inspect`
 - `POST /ag-ui/runs`
+- `GET /ag-ui/runs/:runId/state`
+- `GET /ag-ui/runs/:runId/events`
+- `GET /ag-ui/runs/:runId/trace`
+- `GET /ag-ui/runs/:runId/spans`
+- `GET /ag-ui/runs/:runId/replay`
 
 `POST /ag-ui/runs` emits canonical AG-UI event enum values: `RUN_STARTED`,
 `CUSTOM` events for Stable Runtime events, `TEXT_MESSAGE_START`,
@@ -112,10 +155,13 @@ Compliance notes:
 | Capability | Status | Notes |
 | --- | --- | --- |
 | Run lifecycle | Supported | Emits `RUN_STARTED`, `RUN_FINISHED`, and `RUN_ERROR`. |
+| Workspace inspection | Supported | `GET /ag-ui/inspect` exposes the Stable Runtime workspace inventory behind the AG-UI facade. |
 | Text message lifecycle | Supported | Emits start/content/end events for final assistant text. |
-| Tool events | Partial | Direct runtime tool start/result events are projected to AG-UI tool events. |
+| Tool events | Supported | Direct runtime tool start/result events and upstream adapter `agent.tool.*` events are projected to AG-UI tool events. |
 | Runtime events | Supported | Non-native events remain available through `CUSTOM` payloads. |
-| Reconnect/resume | Not implemented | Use Stable Runtime event replay when first-party resume behavior is required. |
+| Run state | Supported | `GET /ag-ui/runs/:runId/state` projects stored runtime output and messages. |
+| Trace, spans, and replay | Supported | `GET /ag-ui/runs/:runId/trace`, `/spans`, and `/replay` expose the same stored run record used by Stable Runtime inspection. |
+| Reconnect/resume | Supported | `GET /ag-ui/runs/:runId/events` replays stored run events with SSE event IDs and accepts `Last-Event-ID`, `afterEventId`, or `after` resume cursors. |
 
 ## ACP
 
@@ -140,10 +186,19 @@ Supported methods:
 - `session/list`
 - `session/prompt`
 - `session/cancel`
+- `session/close`
+- `runtime/inspect`
+- `runtime/trace`
+- `runtime/spans`
+- `runtime/replay`
 
 `session/prompt` maps to a native `RuntimeRequest` and returns the ACP stop
 reason plus Stable Harness request metadata. Stdio and HTTP use the same
 JSON-RPC method handler and do not change runtime semantics.
+`runtime/inspect` exposes the Stable Runtime workspace inventory. `runtime/trace`,
+`runtime/spans`, and `runtime/replay` are Stable Harness extensions that accept
+`{ "requestId": "..." }` and expose the stored run record without leaving the
+ACP JSON-RPC transport.
 
 Stable Harness clients may include `params.runtimeRequest` to carry explicit
 runtime fields through the ACP-shaped transport.
@@ -162,4 +217,7 @@ Compliance notes:
 | session/list | Supported | Projects Stable Runtime session summaries. |
 | session/prompt | Supported | Maps prompt turns to Stable Runtime requests. |
 | session/cancel | Supported | Cancels currently running requests in the session. |
+| session/close | Supported | Deletes stored Stable Runtime session history for the requested session ID. |
+| runtime/inspect | Supported | Stable Harness extension method exposes workspace inventory through ACP JSON-RPC. |
+| runtime/trace, runtime/spans, runtime/replay | Supported | Stable Harness extension methods expose stored runtime inspection data for the requested run. |
 | client file/terminal requests | Not implemented | Stable Harness does not request client-side filesystem or terminal operations through ACP. |