stable-harness 0.0.8 → 0.0.9

package/docs/architecture/runtime-events.zh.md

@@ -0,0 +1,248 @@
+# Runtime Event Model 运行时事件模型
+
+本文档定义 stable-harness 的事件分层模型。这里列出的名称就是当前物理事件
+schema；不再保留旧事件名兼容层。
+
+章节结构：
+
+- 大分类：Owner，从 `agent` 开始。
+- 中分类：Category，例如 Signal、Fact、Envelope、View。
+- 小分类：具体 event group，例如 `agent.tool.*`、`runtime.request.*`。
+
+本文档里的 `runtime.*` / `agent.*` 是稳定命名空间。`event type` 表示顶层
+runtime event；`payload phase` 表示 `runtime.adapter.event.event.phase`。
+
+代码 source of truth：
+
+- 顶层 runtime events：`packages/core/src/runtime/events.ts`
+- Trace projection：`packages/core/src/trace.ts`
+- OpenAI-compatible SSE projection：`packages/protocols/src/openai-stream.ts`
+
+## 1. Owner: Agent Runtime / Backend Adapter
+
+Agent owner 指 upstream agent runtime 或 backend adapter，例如 DeepAgents、
+LangGraph workflow adapter 或未来的 OpenAI Agents SDK / Gemini SDK adapter。
+
+stable-harness 不拥有这层的执行语义，只通过 `runtime.adapter.event` envelope
+观察、记录、持久化和投影这些信号。
+
+### 1.1 Category: Agent Signals
+
+Agent signals 是 upstream/backend 执行过程中的可观察信号。
+
+#### 1.1.1 Event Group: `agent.lifecycle.*`
+
+| 事件 | payload phase | Owner | 常见字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `agent.handoff` | `agent.handoff` | backend adapter | `adapter`, `phase`, `modelRef`, `tools`, `subagents` | adapter 接管执行。 |
+
+#### 1.1.2 Event Group: `agent.output.*`
+
+| 事件 | payload phase | Owner | 常见字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `agent.output.delta` | `agent.output.delta` | upstream agent runtime | `adapter`, `phase`, `text` | assistant stream delta。 |
+
+#### 1.1.3 Event Group: `agent.tool.*`
+
+| 事件 | payload phase | Owner | 常见字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `agent.tool.start` | `agent.tool.start` | upstream / adapter | `adapter`, `phase`, `toolId`, `args` | upstream/adapter 工具调用开始。 |
+| `agent.tool.result` | `agent.tool.result` | upstream / adapter | `adapter`, `phase`, `toolId`, `output`, `error` | upstream/adapter 工具调用完成或失败。 |
+
+#### 1.1.4 Event Group: `agent.workflow.*`
+
+| 事件 | payload phase | Owner | 常见字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `agent.langgraph.invoke` | `agent.langgraph.invoke` | upstream workflow runtime | `adapter`, `phase`, `workflowId` | LangGraph workflow invocation 开始。 |
+| `agent.node.completed` | `agent.node.completed` | upstream workflow runtime | `adapter`, `phase`, `workflowId`, `nodeId` | workflow node 完成。 |
+
+## 2. Owner: Stable Harness Runtime / Control Plane
+
+Stable Harness runtime/control-plane owner 指 stable-harness 自己拥有的事实事件、
+运行契约、memory lifecycle、artifact、tool gateway 和 adapter envelope。
+
+这些事件是 store、audit、replay、test 的 source of truth。
+
+### 2.1 Category: Runtime Facts
+
+Runtime facts 是稳定、类型化、可审计、会写入 run record 的事实事件。
+
+#### 2.1.1 Event Group: `runtime.request.*`
+
+| 事件 | event type | 必填字段 | 可选字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `runtime.request.started` | `runtime.request.started` | `requestId`, `sessionId`, `agentId` | | request 开始。 |
+| `runtime.request.completed` | `runtime.request.completed` | `requestId`, `sessionId`, `agentId`, `output` | | request 成功完成。 |
+| `runtime.request.failed` | `runtime.request.failed` | `requestId`, `sessionId`, `agentId`, `error` | | request 失败。 |
+| `runtime.request.cancelled` | `runtime.request.cancelled` | `requestId`, `sessionId`, `agentId` | `reason` | request 被取消。 |
+
+#### 2.1.2 Event Group: `runtime.execution.*`
+
+| 事件 | event type | 必填字段 | 可选字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `runtime.execution.contract.failed` | `runtime.execution.contract.failed` | `requestId`, `sessionId`, `agentId`, `reason` | `missingEvidenceTools` | 执行证据契约失败。 |
+
+#### 2.1.3 Event Group: `runtime.tool.direct.*`
+
+这些事件只表示 stable-harness direct tool request 通过 runtime tool gateway
+执行。它们不表示 agent/upstream 在执行过程中选择了 tool；agent 内部 tool call
+属于 `agent.tool.*` signal。
+
+| 事件 | event type | 必填字段 | 可选字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `runtime.tool.direct.started` | `runtime.tool.direct.started` | `requestId`, `sessionId`, `agentId`, `toolId` | | direct tool request 开始执行。 |
+| `runtime.tool.direct.completed` | `runtime.tool.direct.completed` | `requestId`, `sessionId`, `agentId`, `toolId`, `output` | | direct tool request 执行完成。 |
+
+#### 2.1.4 Event Group: `runtime.workflow.*`
+
+这些事件的 owner 是 stable-harness workflow runtime。它们作为顶层
+`runtime.workflow.*` fact 发出，不再通过 adapter payload 表达；adapter payload
+只保留 upstream/backend 拥有的 workflow signal，例如 `agent.langgraph.invoke`。
+
+| 事件 | event type | 必填字段 | 可选字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `runtime.workflow.started` | `runtime.workflow.started` | `requestId`, `sessionId`, `agentId`, `workflowId`, `adapter` | | stable-harness workflow execution 开始。 |
+| `runtime.workflow.completed` | `runtime.workflow.completed` | `requestId`, `sessionId`, `agentId`, `workflowId`, `adapter` | | stable-harness workflow execution 完成。 |
+
+#### 2.1.5 Event Group: `runtime.artifact.*`
+
+| 事件 | event type | 必填字段 | 可选字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `runtime.artifact.created` | `runtime.artifact.created` | `requestId`, `sessionId`, `agentId`, `artifact` | | artifact 被创建。 |
+
+#### 2.1.6 Event Group: `runtime.specDriven.*`
+
+这些事件属于 stable-harness 的 spec-driven workflow runtime capability。它们记录
+control-plane 阶段事实和产物，不替代 backend agent execution semantics。
+
+| 事件 | event type | 必填字段 | 可选字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `runtime.specDriven.phase.started` | `runtime.specDriven.phase.started` | `requestId`, `sessionId`, `agentId`, `phaseId` | `workflowId` | spec-driven 阶段开始。 |
+| `runtime.specDriven.phase.blocked` | `runtime.specDriven.phase.blocked` | `requestId`, `sessionId`, `agentId`, `phaseId`, `reason` | `workflowId` | spec-driven 阶段被 gate 或 policy 阻塞。 |
+| `runtime.specDriven.phase.completed` | `runtime.specDriven.phase.completed` | `requestId`, `sessionId`, `agentId`, `phaseId` | `workflowId`, `artifact` | spec-driven 阶段完成。 |
+| `runtime.specDriven.phase.verified` | `runtime.specDriven.phase.verified` | `requestId`, `sessionId`, `agentId`, `phaseId` | `workflowId`, `artifact` | spec-driven 阶段完成验证。 |
+
+#### 2.1.7 Event Group: `runtime.skill.*`
+
+| 事件 | event type | 必填字段 | 可选字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `runtime.skill.candidate.created` | `runtime.skill.candidate.created` | `requestId`, `sessionId`, `agentId`, `candidateId`, `name`, `confidence`, `evidenceCount`, `status` | `proposedPath` | skill candidate 被发现。 |
+
+### 2.2 Category: Runtime Memory Facts
+
+Memory 是 stable-harness runtime/control-plane 能力，所以归入 `runtime.memory.*`。
+
+#### 2.2.1 Event Group: `runtime.memory.lifecycle`
+
+| 事件 | event type | 必填字段 | 可选字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `runtime.memory.lifecycle` | `runtime.memory.lifecycle` | `requestId`, `sessionId`, `agentId`, `hook` | | memory lifecycle hook 被触发。 |
+
+当前 hook：
+
+| Hook | 含义 |
+| --- | --- |
+| `read-before-plan` | planning 前读取 memory。 |
+| `read-before-finalize` | final output 定稿前读取 memory。 |
+| `write-after-run` | run 结束后写入 memory。 |
+
+#### 2.2.2 Event Group: `runtime.memory.recall.*`
+
+| 事件 | event type | 必填字段 | 可选字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `runtime.memory.recall.completed` | `runtime.memory.recall.completed` | `requestId`, `sessionId`, `agentId`, `namespace`, `recordIds`, `context` | | memory recall 完成。 |
+
+#### 2.2.3 Event Group: `runtime.memory.write.*`
+
+| 事件 | event type | 必填字段 | 可选字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `runtime.memory.candidate.submitted` | `runtime.memory.candidate.submitted` | `requestId`, `sessionId`, `agentId`, `candidate`, `decision` | `record` | memory 写入候选被提交。 |
+| `runtime.memory.approval.requested` | `runtime.memory.approval.requested` | `requestId`, `sessionId`, `agentId`, `approval` | | memory 操作需要 approval。 |
+
+#### 2.2.4 Event Group: `runtime.memory.plugin.*`
+
+| 事件 | event type | 必填字段 | 可选字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `runtime.memory.plugin.started` | `runtime.memory.plugin.started` | `requestId`, `sessionId`, `agentId`, `memoryId`, `provider`, `namespace` | | memory plugin 开始。 |
+| `runtime.memory.plugin.completed` | `runtime.memory.plugin.completed` | `requestId`, `sessionId`, `agentId`, `memoryId`, `provider`, `namespace`, `candidateCount` | | memory plugin 完成。 |
+| `runtime.memory.plugin.failed` | `runtime.memory.plugin.failed` | `requestId`, `sessionId`, `agentId`, `memoryId`, `provider`, `namespace`, `error` | | memory plugin 失败。 |
+
+#### 2.2.5 Event Group: `runtime.memory.maintenance.*`
+
+| 事件 | event type | 必填字段 | 可选字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `runtime.memory.maintenance.started` | `runtime.memory.maintenance.started` | `requestId`, `sessionId`, `agentId`, `target` | | memory maintenance 开始。 |
+| `runtime.memory.maintenance.completed` | `runtime.memory.maintenance.completed` | `requestId`, `sessionId`, `agentId`, `target`, `operationCount` | | memory maintenance 完成。 |
+| `runtime.memory.maintenance.failed` | `runtime.memory.maintenance.failed` | `requestId`, `sessionId`, `agentId`, `target`, `error` | | memory maintenance 失败。 |
+
+### 2.3 Category: Runtime Envelope
+
+Envelope 是 stable-harness 拥有的稳定容器；nested payload 由 agent/backend 拥有。
+
+#### 2.3.1 Event Group: `runtime.adapter.*`
+
+| 事件 | event type | 必填字段 | 可选字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `runtime.adapter.event` | `runtime.adapter.event` | `requestId`, `sessionId`, `agentId`, `event` | | backend/agent signal 的稳定 envelope。 |
+
+## 3. Owner: Stable Harness Views / Protocol
+
+Views/protocol owner 指 stable-harness 对 facts 和 signals 做的展示、投影、传输、
+叙事层。它们不替代原始事实，也不创造执行语义。
+
+### 3.1 Category: Runtime Trace Views
+
+#### 3.1.1 Event Group: `runtime.trace.*`
+
+| 逻辑 view | 当前实现 | 来源 | 用途 |
+| --- | --- | --- | --- |
+| `runtime.trace.request` | trace category `request` | `runtime.request.*`, `runtime.execution.contract.failed` | request timeline。 |
+| `runtime.trace.tool.direct` | trace category `tool` | `runtime.tool.direct.started`, `runtime.tool.direct.completed` | direct/gateway tool timeline。 |
+| `runtime.trace.agent.tool` | trace category `adapter` | `runtime.adapter.event` payload `agent.tool.start` / `agent.tool.result` | agent/upstream tool timeline。 |
+| `runtime.trace.adapter` | trace category `adapter` | `runtime.adapter.event` | backend signal timeline。 |
+| `runtime.trace.memory` | trace category `memory` | `runtime.memory.*` | memory timeline。 |
+| `runtime.trace.artifact` | trace category `artifact` | `runtime.artifact.created` | artifact timeline。 |
+| `runtime.trace.spec` | trace category `spec` | `runtime.specDriven.phase.*` | spec-driven phase timeline。 |
+| `runtime.trace.plan` | trace category `plan` | `runtime.adapter.event.traceType: "plan"` | plan/TODO 展示。 |
+| `runtime.trace.delegation` | trace category `delegation` | `runtime.adapter.event.traceType: "delegation"` | delegation 展示。 |
+
+### 3.2 Category: Runtime Stream Views
+
+#### 3.2.1 Event Group: `runtime.stream.*`
+
+| 逻辑 view | 当前实现 | 来源 | 用途 |
+| --- | --- | --- | --- |
+| `runtime.stream.tool.progress` | SSE `stable_harness.tool.progress` | `runtime.tool.direct.*` 或 `agent.tool.*` signal | OpenAI-compatible tool progress stream。 |
+| `runtime.stream.progress.narration` | SSE `stable_harness.progress.narration` | `runtime.progress.narration` | OpenAI-compatible narration stream。 |
+
+### 3.3 Category: Runtime Progress Views
+
+#### 3.3.1 Event Group: `runtime.progress.*`
+
+| 逻辑事件 | 当前实现 | 必填字段 | 可选字段 | 含义 |
+| --- | --- | --- | --- | --- |
+| `runtime.progress.narration` | runtime event | `requestId`, `sessionId`, `agentId`, `message`, `provider`, `sourceEventTypes` | `sourceEventIds`, `model`, `style` | 基于 runtime facts 和 agent signals 生成的人类可读进度说明。 |
+
+约束：
+
+- narrator 只消费事件，不修改 execution、runtime state、tool result、approval 或 memory decision。
+- narrator 输出必须能追溯到 source events。
+- narrator provider 是可插拔 runtime view provider，支持同步或异步实现；内置 `template` provider。
+- 可通过 `createStableHarnessRuntime({ progressNarration })` 或 workspace `runtime.progress.narration.enabled` 启用。
+- CLI 展示策略是独立 runtime 设置：`runtime.cli.events`。它只控制 CLI 显示，不控制 runtime 是否产生事件。
+- CLI 默认只显示 `runtime.progress.narration`；可用 `include: ["*"]` 打开全部事件。
+
+Workspace YAML:
+
+```yaml
+spec:
+  progress:
+    narration:
+      enabled: true
+      style: concise
+  cli:
+    events:
+      include:
+        - runtime.progress.narration
+        - runtime.tool.direct.*
+```

package/docs/architecture/system-architecture.zh.md

@@ -0,0 +1,435 @@
+# stable-harness 系统架构
+
+`stable-harness` 是 agent 应用的产品运行时和 operator control plane。它不重新发明 agent 执行框架，而是把 YAML workspace 装配成可运行应用，将执行交给 DeepAgents、LangGraph、OpenAI Agents SDK、Gemini SDK 或客户自有框架等上游后端，并在执行外围提供稳定的请求生命周期、事件、审批、治理、记忆、工具网关、协议入口和运维检查能力。
+
+## 设计边界
+
+核心原则：
+
+- 上游框架拥有 agent 执行语义，例如模型调用、subagent 行为、任务工具、workflow engine、backend-native memory 和 sandbox primitive。
+- `stable-harness` 拥有运行时和控制面语义，例如 workspace 装配、request/session/run、event trace、approval、policy、tool gateway、memory lifecycle、artifact、recovery、replay 和 protocol access。
+- 下游 workspace 拥有业务逻辑，例如金融、新闻、Kubernetes、QA、秘书、发布流程等应用域能力。
+- compat 代码只用于迁移，不能成为 native runtime 的设计目标。
+
+任何 native 能力都必须来自 typed config、metadata、runtime state、events、policy 或 adapter contract，不能来自 prompt 文本、关键词、测试 fixture 或某个下游 workspace 的失败样例。
+
+## 总体构造图
+
+```mermaid
+flowchart TB
+  subgraph Clients["Client and Operator Surfaces"]
+    CLI["CLI: stable-harness start/run"]
+    SDK["In-process SDK"]
+    HTTP["HTTP Runtime API"]
+    OAI["OpenAI-compatible /v1 facade"]
+    Future["Future protocols: MCP, ACP, A2A, AG-UI"]
+    Operator["Operator Console / Admin API"]
+  end
+
+  subgraph Runtime["Stable Runtime Core"]
+    Factory["Runtime Factory"]
+    Workspace["Compiled Workspace Inventory"]
+    Request["Request / Session / Run Lifecycle"]
+    Events["Normalized Event Stream"]
+    Store["Runtime Store"]
+    Inspector["Inspection APIs"]
+    Governance["Governance Policy and Approvals"]
+    Memory["Memory Lifecycle"]
+    Gateway["Tool Gateway"]
+    Artifacts["Artifact Store"]
+    Recovery["Recovery / Retry / Replay Hooks"]
+  end
+
+  subgraph Adapters["Pluggable Backend Adapters"]
+    DeepAgents["DeepAgents Adapter"]
+    LangGraph["LangGraph Agent/Graph Adapter"]
+    OpenAI["OpenAI Agents SDK Adapter"]
+    Gemini["Gemini SDK Adapter"]
+    Custom["Customer-owned Adapter"]
+  end
+
+  subgraph WorkspaceFiles["Workspace Files"]
+    RuntimeYaml["config/runtime/workspace.yaml"]
+    AgentsYaml["config/agents/*.yaml including optional edges"]
+    ModelsYaml["config/catalogs/models.yaml"]
+    ToolsYaml["config/catalogs/tools.yaml"]
+    WorkflowsYaml["config/workflows/*.yaml for explicit control-plane graphs"]
+    Resources["resources/tools, skills, files"]
+  end
+
+  CLI --> Factory
+  SDK --> Factory
+  HTTP --> Request
+  OAI --> Request
+  Future --> Request
+  Operator --> Inspector
+
+  Factory --> Workspace
+  WorkspaceFiles --> Factory
+  Request --> Store
+  Request --> Events
+  Request --> Governance
+  Request --> Memory
+  Request --> Gateway
+  Request --> Recovery
+  Request --> Adapters
+  Adapters --> Events
+  Adapters --> Artifacts
+  Gateway --> Resources
+  Inspector --> Store
+  Inspector --> Events
+  Inspector --> Governance
+  Inspector --> Memory
+```
+
+## Workspace 装配
+
+Workspace 是产品的主要配置面。应用通过 Kubernetes-style YAML 定义 agent、model、tool、skill、memory、adapter、protocol 和 policy。对 LangGraph 这类图后端，用户仍然定义 `Agent`，只在现有 inventory 上追加 `edges`。显式 Workflow 文档保留为控制面图 inventory、检查和迁移入口，不是默认产品概念。运行时启动时只做装配和校验，不把业务意图写进核心代码。
+
+```mermaid
+flowchart LR
+  Files["Workspace YAML and resources"] --> Loader["workspace-yaml loader"]
+  Loader --> Inventory["CompiledWorkspace"]
+  Inventory --> Factory["createStableHarnessRuntime(workspaceRoot)"]
+  Factory --> ToolGateway["Module Tool Gateway"]
+  Factory --> AdapterPolicy["Runtime.spec.adapters"]
+  AdapterPolicy --> AdapterFactory["Adapter factories"]
+  AdapterFactory --> Runtime["StableHarnessRuntime"]
+  ToolGateway --> Runtime
+  Inventory --> Runtime
+```
+
+装配职责：
+
+- `workspace-yaml` 读取 YAML，编译成 `CompiledWorkspace`。
+- root runtime factory 根据 `Runtime.spec.adapters` 或 agent backend 自动选择 adapter。
+- tool gateway 从 workspace tools/resources 中装载工具。
+- protocol 配置保持在 runtime YAML 中，例如 OpenAI-compatible bearer token。
+- unknown adapter 通过显式 factory 注入，避免把客户后端硬编码进核心。
+
+## 运行时核心模块
+
+```mermaid
+flowchart TB
+  Runtime["StableHarnessRuntime"]
+  Runtime --> Client["RuntimeClient.request"]
+  Runtime --> EventSource["RuntimeEventSource.subscribe"]
+  Runtime --> Inspector["RuntimeInspector"]
+  Runtime --> Lifecycle["RuntimeLifecycle.cancel/stop"]
+
+  Client --> RunRecord["RuntimeRunRecord"]
+  RunRecord --> States["queued/running/completed/failed/cancelled"]
+  RunRecord --> EventList["RuntimeEvent[]"]
+  RunRecord --> Output["RuntimeOutput"]
+  RunRecord --> ArtifactRecords["RuntimeArtifact[]"]
+
+  Inspector --> ListRequests["listRequests"]
+  Inspector --> ListSessions["listSessions"]
+  Inspector --> InspectRequest["inspectRequest"]
+  Inspector --> GetRun["getRun"]
+```
+
+核心运行时只稳定这些产品概念：
+
+- request：一次用户或协议入口提交的工作。
+- session：跨 request 的会话边界。
+- run：请求执行记录，包含状态、输出、错误、事件和 artifact。
+- event：可订阅、可存储、可检查的运行时事件。
+- artifact：运行中产生的稳定产物记录。
+- policy：审批、恢复、重试、记忆、协议等运行时策略。
+
+## 请求执行流程
+
+```mermaid
+flowchart TD
+  Start["runtime.request(input)"] --> Resolve["Resolve agent and backend adapter"]
+  Resolve --> CreateRun["Create RuntimeRunRecord"]
+  CreateRun --> EmitStart["Emit runtime.request.started"]
+  EmitStart --> Kind{"Request kind"}
+
+  Kind -->|"explicit workflow request"| Workflow["Dispatch to workflow adapter"]
+  Kind -->|"direct toolCall"| ToolCall["Invoke tool gateway"]
+  Kind -->|"agent request"| MemoryRecall["Run memory recall"]
+
+  MemoryRecall --> AdapterRun["Call backend adapter"]
+  AdapterRun --> Recoverable{"Recoverable adapter error?"}
+  Recoverable -->|"yes"| RecoveryPrompt["Build typed recovery request"]
+  RecoveryPrompt --> AdapterRun
+  Recoverable -->|"no"| ResultCheck["Check result recovery policy"]
+  ResultCheck --> NeedsFollowup{"Need follow-up recovery?"}
+  NeedsFollowup -->|"yes"| Followup["Call adapter with recovery request"]
+  NeedsFollowup -->|"no"| MemoryFinalize["Memory candidate approval / plugin lifecycle"]
+  Followup --> MemoryFinalize
+
+  Workflow --> Complete["Complete run"]
+  ToolCall --> Complete
+  MemoryFinalize --> Contract["Assert execution contract"]
+  Contract --> Complete
+  Complete --> EmitComplete["Emit runtime.request.completed"]
+  EmitComplete --> Response["Return RuntimeResponse"]
+
+  AdapterRun --> Failure["Non-recoverable failure"]
+  Failure --> EmitFailure["Emit runtime.request.failed"]
+```
+
+这个流程的关键限制是：runtime 可以做生命周期、可观测性、恢复策略和最终 contract 检查，但不能用自然语言关键词决定工具、agent 或业务路由。
+
+## 请求 Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant Client
+  participant Runtime as StableHarnessRuntime
+  participant Store as RuntimeStore
+  participant Memory as Memory Providers
+  participant Adapter as Backend Adapter
+  participant Gateway as Tool Gateway
+  participant Upstream as Upstream Framework
+
+  Client->>Runtime: request(input, agentId?, sessionId?)
+  Runtime->>Store: createRun(requestId, sessionId, agentId)
+  Runtime-->>Client: runtime.request.started event via subscription
+  Runtime->>Memory: recall(request, agent, workspace)
+  Memory-->>Runtime: runtime memory context
+  Runtime->>Adapter: run(workspace, agent, request, memory, toolGateway, emit)
+  Adapter->>Upstream: invoke upstream-native agent/workflow
+  Upstream->>Gateway: tool call through adapter-provided gateway
+  Gateway-->>Runtime: runtime.tool.direct.started / runtime.tool.direct.completed events
+  Upstream-->>Adapter: backend result
+  Adapter-->>Runtime: RuntimeOutput
+  Runtime->>Memory: submit candidates / run lifecycle hooks
+  Runtime->>Store: updateRun(completed, output, artifacts)
+  Runtime-->>Client: RuntimeResponse
+```
+
+## Tool Gateway 和治理流程
+
+Tool gateway 是稳定运行时的工具执行边界。它负责工具 inventory、参数防护、执行上下文、事件和可插拔实现，但不负责业务路由。
+
+```mermaid
+flowchart TD
+  Adapter["Backend adapter selected a tool"] --> Gateway["RuntimeToolGateway.invoke"]
+  Gateway --> Guard["Argument guard / schema check"]
+  Guard --> Policy["Governance policy"]
+  Policy --> Approval{"Approval required?"}
+  Approval -->|"yes"| Queue["ApprovalQueue"]
+  Queue --> Decision{"approve or deny"}
+  Decision -->|"deny"| Denied["Emit tool.denied"]
+  Decision -->|"approve"| Execute["Execute module/MCP/remote tool"]
+  Approval -->|"no"| Execute
+  Execute --> Result["ToolGatewayInvokeResult"]
+  Result --> Event["Emit runtime.tool.direct.completed or runtime.request.failed"]
+```
+
+治理输入只能来自 typed policy、tool metadata、runtime context、approval state 和 request metadata。不能用工具名所属业务域、prompt 关键词或测试期望来改变 native runtime 行为。
+
+## Protocol Surfaces
+
+协议层是 runtime contract 的外壳，不是 backend adapter。
+
+```mermaid
+flowchart LR
+  OpenAIClient["OpenAI-compatible client"] --> V1["/v1/models, /v1/capabilities, /v1/chat/completions"]
+  V1 --> Map["Map model to workspace agentId"]
+  Map --> RuntimeReq["runtime.request(metadata.protocol=openai-compatible)"]
+  RuntimeReq --> Runtime["Stable Runtime"]
+
+  OperatorClient["Operator client"] --> OperatorAPI["Operator API"]
+  OperatorAPI --> Inspect["listRequests/listSessions/inspectRequest/getRun"]
+  OperatorAPI --> Control["cancel/retry/approve/deny/maintenance"]
+  Inspect --> Runtime
+  Control --> Runtime
+```
+
+OpenAI-compatible `/v1` facade 面向客户端兼容，只暴露小而稳定的 chat-completions 子集。request/session/cancel/approval/run inspection 属于 operator control plane，不应该塞进 `/v1` 兼容协议里。
+
+## OpenAI-Compatible Chat Sequence
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant App as OpenAI-compatible Client
+  participant Facade as /v1 Facade
+  participant Runtime as Stable Runtime
+  participant Adapter as Backend Adapter
+  participant ClientStream as SSE Stream
+
+  App->>Facade: POST /v1/chat/completions
+  Facade->>Facade: validate messages and model
+  Facade->>Runtime: request(input transcript, agentId=model)
+  Runtime->>Adapter: run selected workspace agent
+  Adapter-->>Runtime: runtime events and final output
+  Runtime-->>Facade: RuntimeResponse
+  Facade-->>ClientStream: chat.completion.chunk
+  Facade-->>ClientStream: stable_harness.tool.progress events
+  Facade-->>ClientStream: data: [DONE]
+```
+
+客户端传入的 `tools` 和 `tool_choice` 不应绕过 workspace inventory、governance policy 或 tool gateway。runtime 工具仍由 workspace 和后端 adapter 共同约束。
+
+## Adapter 分层
+
+```mermaid
+flowchart TB
+  StableRequest["Stable RuntimeRequest"] --> Adapter["RuntimeAdapter.run"]
+  Adapter --> Translate["Translate to upstream call"]
+  Translate --> UpstreamConfig["Pass through backend-native config"]
+  UpstreamConfig --> Framework["Upstream framework"]
+  Framework --> BackendEvents["Backend progress"]
+  BackendEvents --> Normalize["Normalize into RuntimeEvent"]
+  Framework --> BackendOutput["Backend output"]
+  BackendOutput --> StableOutput["RuntimeOutput"]
+```
+
+adapter 可以做：
+
+- 将稳定 request 转成上游调用。
+- 传递 upstream-native config。
+- 把上游进度投影成 runtime events。
+- 返回稳定的 `RuntimeOutput` 和 artifacts。
+
+adapter 不能做：
+
+- 用自然语言关键词路由。
+- 为单个下游应用硬编码工具、领域或 agent。
+- 重新实现上游已有的 planning、delegation、memory、sandbox、workflow engine。
+- 解析 TODO 文本并制造工具调用。
+- 本地 replay upstream custom tool calls。
+
+## Agent Graph and Workflow Adapter
+
+Agent 是默认用户定义面。DeepAgents Agent 的字段保持不变；LangGraph Agent 只在现有 tools、skills、subagents inventory 上追加 `edges`，由 LangGraph adapter 编译到上游 `StateGraph`。
+
+Workflow 是显式控制面 graph inventory，用于检查、迁移或协议需要直接指定 graph 的场景。它引用已有 workspace inventory，不重新定义 agent、tool 或 skill，也不是新的主用户概念。
+
+```mermaid
+flowchart TD
+  Agent["Agent backend: langgraph + edges"] --> RuntimeAdapter["LangGraph RuntimeAdapter"]
+  Request["Explicit RuntimeRequest.workflow"] --> Resolve["Resolve workflowId or typed routeId"]
+  Resolve --> Validate["Validate workflow exists in inventory"]
+  Validate --> WorkflowAdapter["RuntimeWorkflowAdapter"]
+  RuntimeAdapter --> Compile["Compile inventory nodes + edges"]
+  WorkflowAdapter --> Compile
+  Compile --> LangGraph["LangGraph StateGraph or future backend"]
+  LangGraph --> NodeHandler["Injected node handlers/resolvers"]
+  NodeHandler --> Result["RuntimeOutput"]
+```
+
+Core runtime 只负责 Agent/Workflow inventory、显式 route 表、request lifecycle 和 events。具体 graph 执行语义属于 LangGraph、Microsoft Agent Framework 或其他 workflow backend。
+
+## Memory Lifecycle
+
+```mermaid
+flowchart LR
+  Request["Runtime request"] --> RecallPolicy["Memory recall policy"]
+  RecallPolicy --> Provider["Memory provider"]
+  Provider --> Context["RuntimeMemoryContext"]
+  Context --> Adapter["Backend adapter"]
+  Adapter --> Output["RuntimeOutput"]
+  Output --> Candidates["Memory candidates"]
+  Candidates --> Approval["Governance approval"]
+  Approval --> Persist["Memory store / LangMem service"]
+  Persist --> Maintenance["Maintenance: compact, backup, export"]
+```
+
+`stable-harness` owns memory namespace、persistence policy、recall coordination、approval、maintenance 和 observability。DeepAgents-native memory 或其他 backend-native memory 应通过 adapter passthrough 使用，不在 core 中导出 backend 命名的语义。
+
+## Operator Control Plane
+
+```mermaid
+flowchart TB
+  Operator["Operator"] --> Dashboard["Control Plane Surface"]
+  Dashboard --> Requests["Requests and runs"]
+  Dashboard --> Sessions["Sessions"]
+  Dashboard --> Events["Events and traces"]
+  Dashboard --> Approvals["Approval queue"]
+  Dashboard --> Memory["Memory records"]
+  Dashboard --> Artifacts["Artifacts"]
+  Dashboard --> Health["Backend and workspace health"]
+  Dashboard --> Maintenance["Maintenance jobs"]
+
+  Requests --> Actions["cancel / retry / inspect"]
+  Approvals --> Review["approve / deny"]
+  Maintenance --> Jobs["compact / replay / export / cleanup"]
+```
+
+Operator control plane 的目标是让运维视角看到稳定的产品对象：request、session、run、event、approval、artifact、memory 和 health，而不是直接暴露上游 checkpoint 内部结构。
+
+## Deployment Shapes
+
+```mermaid
+flowchart LR
+  subgraph Embedded["Embedded application"]
+    App["Customer app"] --> SDK["createStableHarnessRuntime(workspaceRoot)"]
+    SDK --> RuntimeA["In-process runtime"]
+  end
+
+  subgraph Service["Standalone service"]
+    CLI["stable-harness start -w workspace --port 8642"] --> Server["HTTP / OpenAI-compatible server"]
+    Server --> RuntimeB["Runtime instance"]
+  end
+
+  subgraph Future["Managed surfaces"]
+    MCP["MCP server"]
+    ACP["ACP/A2A"]
+    AGUI["AG-UI"]
+    MCP --> RuntimeC["Runtime instance"]
+    ACP --> RuntimeC
+    AGUI --> RuntimeC
+  end
+```
+
+推荐启动路径：
+
+- 嵌入式应用：`createStableHarnessRuntime(workspaceRoot)`，由 workspace YAML 决定 adapter、protocol 和 policy 默认值。
+- 本地或服务化入口：`stable-harness start -w "$PWD" --port 8642 --api-key ...`。
+- OpenAI-compatible 客户端：连接 `http://host:port/v1`，把 `model` 映射为 workspace agent id。
+
+## 扩展点
+
+| 扩展点 | Owner | 说明 |
+| --- | --- | --- |
+| Runtime adapter | Backend adapter | 接入 DeepAgents、OpenAI Agents SDK、Gemini SDK 或客户框架 |
+| Graph/workflow adapter | Backend adapter | 让 `backend: langgraph` Agent 的 edges 或显式 Workflow 编译到上游图后端 |
+| Tool gateway | Runtime capability | 替换本地 module tool、MCP、remote tool 或参数防护实现 |
+| Memory provider | Runtime capability | 替换 LangMem service、嵌入式 store 或企业记忆服务 |
+| Approval queue | Governance capability | 接入人工审批、企业工单或策略引擎 |
+| Event sink | Runtime capability | 接入日志、trace、SIEM、dashboard |
+| Protocol adapter | Protocol surface | 暴露 CLI、SDK、HTTP、OpenAI-compatible、MCP、ACP/A2A/AG-UI |
+| Artifact store | Runtime capability | 接入本地文件、对象存储、数据库或审计仓库 |
+
+## 典型端到端路径
+
+```mermaid
+flowchart TD
+  User["User or client"] --> Protocol["Protocol surface"]
+  Protocol --> Runtime["Stable runtime"]
+  Runtime --> Workspace["Workspace inventory"]
+  Workspace --> Agent["Selected agent"]
+  Agent --> Adapter["Backend adapter"]
+  Adapter --> Upstream["Upstream agent framework"]
+  Upstream --> ToolNeed{"Tool needed?"}
+  ToolNeed -->|"yes"| Gateway["Tool gateway + governance"]
+  Gateway --> Tool["Workspace tool / MCP / remote tool"]
+  Tool --> Upstream
+  ToolNeed -->|"no"| Final["Final backend output"]
+  Upstream --> Final
+  Final --> Runtime
+  Runtime --> Store["Persist run, events, artifacts, memory hooks"]
+  Store --> Protocol
+  Protocol --> User
+```
+
+## 架构守则
+
+实现新能力前先分类：
+
+- 上游执行语义：adapter passthrough。
+- 产品运行时语义：typed stable capability。
+- 协议兼容需求：protocol adapter。
+- 运营治理需求：governance/control-plane capability。
+- 下游业务逻辑：workspace config、prompt、tool 或 app test。
+- 历史迁移行为：compat，且必须有删除或上移路径。
+
+如果一个行为只能解释为“某个 prompt、某个模型、某个业务域、某个测试用例需要”，它不应该进入 native runtime。