@botbotgo/agent-harness 0.0.298 → 0.0.299

package/README.md

@@ -74,13 +74,17 @@ rewrite of the execution stack behind them.
 The repository default also ships a starter runtime, not an empty shell:
 
 - one default host agent: `orchestra`
-- five built-in behavior skills: `workspace-inspection`, `safe-editing`, `delegation-discipline`, `approval-execution-policy`, and `completion-discipline`
-- a builtin tool surface for file inspection, safe editing, approvals, and DeepAgents compatibility helpers
+- a workspace-local `resources/tools/` path for runtime-owned tools such as file inspection, runtime inspection, approvals, and schedules
+- no preloaded bootstrap memory or behavior skills on the default host, so first-run local chat stays responsive; add `memory:` files and `skills:` refs when your runtime really needs them
 
 If you want the fastest first-run demo, start the chat shell and try one of these:
 
 ```bash
-agent-harness chat --workspace .
+botbotgo
+# or
+botbotgo "Inspect this workspace and explain the main entry points."
+# or
+agent-harness "Inspect this workspace and explain the main entry points."
 ```
 
 - `Inspect this workspace and explain the main entry points.`
@@ -88,6 +92,11 @@ agent-harness chat --workspace .
 - `Update README.md to make the setup steps clearer.`
 - `Find the likeliest config issue in this workspace and propose the smallest fix.`
 
+When the runtime emits request-scoped `plan-state` updates and safe `progress.commentary` deltas, the chat shell now renders live todo-board and progress status updates directly in the terminal, so you can watch planning and execution status change during the run instead of waiting for the final response.
+Those progress callouts now stay tied to stable runtime surfaces such as plan-state, tool start/completion, memory recall, and agent delegation, so the operator sees Codex-style intermediate status without exposing private model reasoning.
+The repository default `orchestra` host is also instructed to start real multi-step execution from the task you already gave it, call `write_todos` before non-trivial tool work, and keep that todo board updated while it runs.
+Durable-memory writes now also retrieve related existing records through the configured vector store before model reconciliation, then merge those semantic hits with deterministic matching so updates and deletes can target the right knowledge identity instead of creating nearby duplicate facts.
+
 <a id="readme-en-docs-path"></a>
 
 ## Documentation Paths
@@ -150,8 +159,8 @@ Additional docs:
 **At a glance:** onboarding stays thin, the runtime ships as a full layer, and day-to-day work lives in **YAML** plus **extensions** (local tools, SKILL packages, MCP)—not bespoke runtime plumbing.
 
 - **Easy to start:** `createAgentHarness` → `request` → `stop`, plus inspection helpers such as `subscribe`, `listSessions`, `listApprovals`, and `resolveApproval`.
-- **Reusable client surface:** `createAgentHarnessClient` / `createInProcessHarnessClient` bind the same runtime-owned request, session, approval, and stream APIs into one frontend-facing client contract that terminal shells, desktop apps, and other embedded UIs can share.
-- **ACP client path for out-of-process UIs:** `createAcpHarnessClient`, `createAcpStdioHarnessClient`, and `createAcpHttpHarnessClient` let a UI consume the same `HarnessClient` contract over ACP when the UI and runtime live in different processes, including request-scoped `streamRequest(...)` flows that preserve richer stream items such as `content-blocks`, `tool-result`, and `upstream-event`.
+- **Reusable client surface:** `createAgentHarnessClient` / `createInProcessHarnessClient` bind the same runtime-owned request, session, approval, and event APIs into one frontend-facing client contract that terminal shells, desktop apps, and other embedded UIs can share.
+- **ACP client path for out-of-process UIs:** `createAcpHarnessClient`, `createAcpStdioHarnessClient`, and `createAcpHttpHarnessClient` let a UI consume the same `HarnessClient` contract over ACP when the UI and runtime live in different processes, while keeping `request(...)` as the one request entrypoint for streamed state snapshots plus delta data.
 - **Configure:** routing, models, tools, stores, backends, MCP, recovery, and maintenance in declarative workspace YAML (see [Quick Start](#readme-en-quickstart) and [How To Configure](#readme-en-config)).
 - **Extend:** drop `tool({...})` modules and SKILL trees under `resources/`, wire shared tools and MCP in catalogs, and let agents whitelist what they use.
 - **Built into the runtime:** persisted `requests`, `sessions`, `approvals`, and `events`; recovery and queueing; streaming listeners; MCP in/out; and backend adapters—so you do not rebuild that layer per app.
@@ -163,7 +172,7 @@ Additional docs:
 The public API spans a full product runtime—persistent records, memory and evidence, protocol surfaces, and governance—not only a thin bootstrap around YAML and tools.
 
 - **Core runtime API:** `createAgentHarness`, `request`, `subscribe`, `resolveApproval`, `recordArtifact`, inspection helpers, and stable persisted runtime records for `requests`, `sessions`, `approvals`, `events`, and artifacts.
-- **Frontend/client entrypoints:** `createAgentHarnessClient`, `createInProcessHarnessClient`, `createAcpHarnessClient`, `createAcpStdioHarnessClient`, `createAcpHttpHarnessClient`, `HarnessClient`, and `streamRequest(...)`-style client flows let product shells consume the runtime through one reusable client layer instead of re-binding runtime calls per UI.
+- **Frontend/client entrypoints:** `createAgentHarnessClient`, `createInProcessHarnessClient`, `createAcpHarnessClient`, `createAcpStdioHarnessClient`, `createAcpHttpHarnessClient`, and `HarnessClient` let product shells consume the runtime through one reusable client layer instead of re-binding runtime calls per UI. `request(...)` is the streamed request entrypoint; `subscribe(...)` is the runtime lifecycle observer surface.
 - **Runtime memory and evidence:** `memorize`, `recall`, `listMemories`, memory policy hooks, `recordArtifact`, `listArtifacts`, `getArtifact`, `exportEvaluationBundle`, `replayEvaluationBundle`, and request/session evidence export helpers.
 - **Protocol and transport surfaces:** `createAcpServer`, `createAcpStdioClient`, `serveAcpStdio`, `serveAcpHttp`, `serveA2aHttp`, `serveAgUiHttp`, and `createRuntimeMcpServer` / `serveRuntimeMcpOverStdio`.
 - **Governed workspace runtime:** YAML-owned routing, concurrency, maintenance, MCP policy, runtime governance bundles, and approval defaults for sensitive memory or write-like MCP side effects.
@@ -351,17 +360,31 @@ Install:
 npm install @botbotgo/agent-harness
 ```
 
+If you want the CLI on your `PATH`, install it globally and run it from your own workspace root:
+
+```bash
+npm install -g @botbotgo/agent-harness
+cd /path/to/your-workspace
+botbotgo
+botbotgo "Inspect this workspace and explain the main entry points."
+botbotgo -w /path/to/another-workspace "Summarize this project."
+```
+
+`botbotgo` treats the current directory as the workspace root. You can now run it from any folder: if `./config/` is absent, the CLI falls back to the bundled system defaults and bundled resources; if `./config/` or `./resources/` exists, the runtime overlays your workspace-defined config and resources on top of those defaults.
+
+Development tip: repository-owned Ollama workspaces now default to `http://127.0.0.1:11434` for release-friendly local behavior. During development, point them at a shared remote Ollama by exporting `AGENT_HARNESS_OLLAMA_BASE_URL=https://ollama-rtx-4070.easynet.world` or `AGENT_HARNESS_OPENAI_COMPATIBLE_BASE_URL=https://ollama-rtx-4070.easynet.world/v1` before starting the runtime.
+
 Workspace layout:
 
 ```text
 your-workspace/
   config/
+    models.yaml
     agent-context.md
     runtime/
       workspace.yaml
       runtime-memory.yaml
     catalogs/
-      models.yaml
       embedding-models.yaml
       vector-stores.yaml
       stores.yaml
@@ -589,27 +612,22 @@ const result = await request(runtime, {
 const result = await request(runtime, {
   agentId: "orchestra",
   input: "Inspect the workspace and explain the available tools.",
-  listeners: {
-    onChunk(chunk) {
-      process.stdout.write(chunk);
-    },
-    onContentBlocks(blocks) {
-      console.log(blocks);
-    },
-    onEvent(event) {
-      console.log(event.eventType, event.payload);
-    },
-    onUpstreamEvent(event) {
-      console.log("raw upstream event", event);
-    },
-    onTraceItem(item) {
-      console.log("upstream agent", item.agentId, item.event);
-    },
+  eventListener(snapshot) {
+    console.log(snapshot.state, snapshot.plan.items);
+  },
+  dataListener(event) {
+    if (event.type === "output.text.delta") {
+      process.stdout.write(event.text);
+    }
+    if (event.type === "tool.result") {
+      console.log(event.toolName, event.output);
+    }
   },
 });
 ```
 
-`onUpstreamEvent(...)` preserves the raw upstream event payload. `onTraceItem(...)` adds runtime correlation metadata such as `sessionId`, `requestId`, and the current `agentId`, which is useful for flow-graph capture and delegated sub-agent inspection.
+`eventListener(...)` receives the latest full request snapshot, including request state, the live todo board, approval state, and current output.
+`dataListener(...)` receives append-only deltas such as text output, progress commentary, content blocks, tool results, and upstream debug items.
 
 `subscribe(...)` is the read-only observer surface over stored lifecycle events.
 
@@ -702,11 +720,12 @@ Core workspace files:
 
 - `config/runtime/workspace.yaml`
 - `config/agent-context.md`
-- `config/catalogs/models.yaml`
+- `config/models.yaml`
 - `config/catalogs/embedding-models.yaml`
 - `config/catalogs/vector-stores.yaml`
 - `config/catalogs/stores.yaml`
 - `config/knowledge/knowledge-runtime.yaml`
+- `config/knowledge/procedural-memory-runtime.yaml`
 - `config/runtime/runtime-memory.yaml`
 - `config/catalogs/backends.yaml`
 - `config/catalogs/tools.yaml`
@@ -722,6 +741,8 @@ Discovery rules:
 - YAML object semantics come from `kind`, `metadata.name` or `id`, and object content rather than the file path
 - local tools are auto-discovered from `resources/tools/**/*.js|*.mjs|*.cjs` when they export `tool({...})`
 - skills are auto-discovered from `resources/skills/**/SKILL.md`
+- a minimal workspace can start with only `config/models.yaml`; the repository defaults provide the `Runtime`, the default `orchestra` host, and runtime-managed durable memory with `enabled: true`
+- when you do not override runtime placement, harness-owned generated state is written under `./.botbotgo/`
 
 Example workspaces:
 
@@ -736,12 +757,14 @@ Example workspaces:
 - `examples/07_multi-agent-research/` is the Multi-Agent Research Example: the most complete multi-agent research workspace with reusable backends, skills, and local tools
 - `examples/08_long-term-memory-learning/` is the Long-Term Memory Learning Example: repeated requests that store durable memory, inspect recall, and make later answers more context-aware
 - `examples/09_long-running-coding-harness/` is the Long-Running Coding Harness Example: a host agent plus app-owned planning/evaluation roles, Playwright MCP wiring, and evaluation-bundle export for long coding sessions
+- `examples/10_playwright-mcp-browser/` is the Playwright CLI Browser Example: the smallest browser-capable workspace that follows the official Playwright coding-agent recommendation with `playwright-cli` plus a local skill
 
 Workspace-local tool modules in `resources/tools/` should be exported with `tool({...})`.
 Any other local module shape is not supported, and unsupported shapes are rejected at load time.
 When a local function tool declares its schema in the module, runtime governance treats that module-defined schema as the source of truth; duplicating it into YAML `inputSchema.ref` is optional rather than required for schema-bound metadata.
 When local tools use Zod-authored schemas, keep the workspace or isolated `resources` package on `zod@^4` so raw-shape validators and runtime parsing stay on one supported major version.
-For DeepAgents-backed agents, the runtime also exposes a built-in compatibility layer for the upstream helper tools that DeepAgents expects during long multi-step execution. That compatibility set currently includes `write_todos`, `read_todos`, `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `task`, and `execute` when the selected backend implements sandbox command execution. Public-facing aliases such as `list_files`, `search_files`, `run_command`, and `delegate_task` are additive runtime surfaces; they do not replace the upstream DeepAgents helper names.
+If you want runtime-owned product tools such as `list_files`, `search_files`, `run_command`, `schedule_task`, request inspection, or artifact inspection, author them as normal `resources/tools/*.mjs` modules and whitelist them from agent YAML like any other workspace tool.
+For DeepAgents-backed agents, the runtime still keeps an internal compatibility layer for the upstream helper tools that DeepAgents expects during long multi-step execution. That compatibility set currently includes `write_todos`, `read_todos`, `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `task`, and `execute` when the selected backend implements sandbox command execution. Treat those helper names as adapter-internal execution compatibility, not as the primary product-facing workspace tool surface.
 
 Default wiring guidance:
 
@@ -818,7 +841,7 @@ kind: Runtime
 metadata:
   name: default
 spec:
-  runtimeRoot: ./.agent
+  dataRoot: ./.botbotgo
   toolModuleDiscovery:
     scope: top-level
   concurrency:
@@ -858,7 +881,7 @@ spec:
 
 These load as `model/default`.
 
-You can place `kind: Models` catalogs anywhere under `config/`; `config/catalogs/models.yaml` is only the recommended layout.
+You can place `kind: Models` catalogs anywhere under `config/`; the repository default now keeps `models.yaml` at the `config/` root, and file paths remain organizational only.
 
 ### Embedding Model Catalogs In `config/**`
 
@@ -902,7 +925,24 @@ Keep bootstrap context in `config/agent-context.md`. Keep resumable execution st
 
 Use this singleton when the same durable-memory policy should also run outside `AgentHarnessRuntime`, such as a standalone knowledge worker or knowledge server.
 
-`KnowledgeRuntime` mirrors the durable policy shape on purpose. Keep `RuntimeMemory` for runtime-owned defaults, and keep `KnowledgeRuntime` as the externalizable mirror when a separate knowledge service needs the same memorize/recall policy.
+`KnowledgeRuntime` mirrors the durable policy shape on purpose. Keep `RuntimeMemory` for runtime-owned defaults, and keep `KnowledgeRuntime` as the externalizable mirror when a separate knowledge service needs the same memorize/recall policy. Use it for fast explicit writes plus background durable-knowledge formation and maintenance.
+
+### `config/knowledge/procedural-memory-runtime.yaml`
+
+Use this singleton when the workspace wants a separate background experience-memory layer, such as a ReMe-backed procedural memory pool.
+
+`ProceduralMemoryRuntime` is intentionally separate from `KnowledgeRuntime`:
+
+- keep `KnowledgeRuntime` for durable facts, preferences, rules, and confirmed decisions
+- keep `ProceduralMemoryRuntime` for workflows, debugging lessons, tactics, and reusable procedures
+- keep both stores under the same `knowledge/` directory, but do not force them into one logical store
+
+The default repository shape uses:
+
+- `KnowledgeRuntime`: hot path + background formation + long-term maintenance
+- `ProceduralMemoryRuntime`: background formation + scheduled or idle maintenance
+
+For DeepAgents-backed workspaces, keep upstream context compaction upstream-owned and use procedural memory only as a background learning layer.
 
 ### `config/catalogs/backends.yaml`
 
@@ -962,7 +1002,7 @@ Agent YAML can live anywhere under `config/`; `config/agents/*.yaml` is the reco
 
 Use two sections:
 
-- `spec.runtime` for harness-owned runtime placement such as `spec.runtime.runtimeRoot`
+- `spec.runtime` for agent-specific runtime placement overrides such as `spec.runtime.runtimeRoot`
 - top-level `spec` fields for upstream execution semantics and adapter-facing config
 
 Example direct host:
@@ -973,8 +1013,6 @@ kind: Agent
 metadata:
   name: direct
 spec:
-  runtime:
-    runtimeRoot: ./.agent
   backend: langchain-v1
   modelRef: model/default
   tools:
@@ -997,9 +1035,12 @@ spec:
         enabled: true
         rootDir: "{runtimeRoot}/sessions/{sessionId}/filesystem"
     middleware: []
-    systemPrompt: Answer simple requests directly.
+    systemPrompt:
+      path: ../prompts/direct-system.md
 ```
 
+Keep long prompts in checked-in prompt files such as `config/prompts/*.md` and point `systemPrompt` at them with a path relative to the agent YAML file. This keeps prompt text out of source code and makes prompt edits reviewable as normal content changes.
+
 When `config.filesystem.sessionStorage.enabled: true` is set for a LangChain binding, the runtime keeps one filesystem root per persisted session and reuses the same runnable cache entry for repeated work on that session instead of collapsing every request onto one shared workspace directory.
 
 Example orchestra host:
@@ -1010,8 +1051,6 @@ kind: Agent
 metadata:
   name: orchestra
 spec:
-  runtime:
-    runtimeRoot: ./.agent
   backend: deepagent
   modelRef: model/default
   memory:
@@ -1103,14 +1142,15 @@ ACP transport notes:
 - ACP transport validation now covers the reference-client core flow: capability discovery, request submit, session lookup, request lookup, invalid-JSON handling, notification calls without response ids, stdio JSON-RPC, and HTTP plus SSE runtime notifications.
 - Cross-protocol conformance now has an explicit regression gate as well: ACP submission, A2A task lookup and continuation, and runtime MCP inspection must all project the same persisted `sessionId` / `requestId` runtime records instead of drifting into surface-specific identifiers or side stores.
 - For the thinnest editor or CLI starter, begin with `agent-harness acp serve --workspace . --transport stdio` and mirror the `examples/03_protocol-surfaces/app/acp-stdio/main.mjs` wire shape. Applications that want an in-process reference client can use `createAcpStdioClient(...)` to issue JSON-RPC requests and route runtime notifications without hand-rolling line parsing.
-- `agent-harness chat --workspace .` now acts as a thin terminal shell over ACP: by default it spawns a subprocess ACP stdio server, and it can also target an already-running ACP HTTP endpoint through `--transport http --host <host> --port <port>`. One-shot use can pass `--message`, while interactive mode supports `/context`, `/new`, `/agent <agentId>`, `/sessions`, `/requests`, `/resume <sessionId>`, `/approvals`, `/approve`, `/reject`, `/cancel`, `/events`, `/trace`, `/health`, `/overview`, `/session`, `/request [requestId]`, and `/exit`. `/resume` now validates the target session, restores its latest request id, and rehydrates the active agent context; `/request <requestId>` can switch the active request context to a persisted request; `/new` clears the current session/request context without leaving the shell. When ACP streaming emits richer request-scoped items, the shell now surfaces tool results and text-oriented content blocks as well.
+- `botbotgo` is the shortest local terminal entrypoint for a published install. It defaults the workspace to the current directory, so teams can `cd` into their own runtime workspace and run `botbotgo` or `botbotgo "..."` directly. `agent-harness` keeps the same implicit-chat behavior, and `-w/--workspace` still lets one shell point at another workspace when needed.
+- `agent-harness chat --workspace .` still acts as a local terminal shell over the shared `HarnessClient` contract when you want the explicit subcommand form: the default `stdio` path runs directly in-process against the workspace runtime, while `--transport http --host <host> --port <port>` can still target an already-running ACP HTTP endpoint. One-shot use can pass `--message`, while interactive mode supports `/context`, `/new`, `/agent <agentId>`, `/sessions`, `/requests`, `/resume <sessionId>`, `/approvals`, `/approve`, `/reject`, `/cancel`, `/events`, `/trace`, `/health`, `/overview`, `/session`, `/request [requestId]`, and `/exit`. `/resume` now validates the target session, restores its latest request id, and rehydrates the active agent context; `/request <requestId>` can switch the active request context to a persisted request; `/new` clears the current session/request context without leaving the shell. Terminal chat now keeps one operator-facing flow: it streams tool and progress events as they happen and still prints the full final answer, instead of switching to a separate request-tree-only mode.
 - Local repo usage differs from the published binary on purpose. After cloning the repo, use `npm run chat -- --workspace ./config` or `npm run agent-harness -- chat --workspace ./config`. The extra `--` matters: without it, npm treats `--workspace` as npm's own workspace flag. The standalone `agent-harness ...` command only works after the package has been installed or linked so the `bin` entry is on your `PATH`.
 - Interactive chat now opens with a large ASCII startup banner that prints the active workspace, transport, and current override context before the command help so the shell feels like a dedicated runtime console instead of a raw REPL.
 - When the workspace model/provider cannot be reached, chat now expands generic failures such as `runtime_error=fetch failed` into operator-facing diagnostics that include the configured provider, model, endpoint, and a concrete recovery hint, instead of leaving the shell at an opaque transport error.
 - Chat startup now also performs a lightweight workspace-model preflight for the local Ollama path. If the configured endpoint is unreachable or responds with `404 page not found`, the shell prints that warning before the first prompt so endpoint mismatches show up immediately instead of only after the first failed message.
 - The interactive prompt now carries the live `agent`, `session`, and short `request` identifier together, so after each reply and during shell-history navigation the user stays anchored to the current runtime turn instead of dropping back to a bare input prompt.
 - `serveA2aHttp(runtime)` exposes an A2A-compatible HTTP JSON-RPC bridge plus agent card discovery, mapping both existing methods such as `message/send` and A2A v1.0 PascalCase methods such as `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, `GetAgentCard`, `GetExtendedAgentCard`, and task push-notification config methods onto the existing session/request runtime surface. The bridge now advertises both `1.0` and `0.3` JSON-RPC interfaces, answers `HEAD` / `OPTIONS` discovery on the agent-card path, sets supported-version discovery headers, can optionally expose registry URLs plus detached signed-card metadata for surrounding discovery systems, validates `A2A-Version`, records `A2A-Extensions` into runtime invocation metadata, publishes `TASK_STATE_*` statuses plus the `{ task }` `SendMessage` wrapper, streams an initial `{ task }` snapshot plus later `{ statusUpdate }` payloads over SSE for v1 streaming methods, and can send best-effort webhook task snapshots for configured push notification receivers.
-- `serveAgUiHttp(runtime)` exposes an AG-UI-compatible HTTP SSE bridge that projects runtime lifecycle, text output, upstream thinking, step progress, and tool calls onto `RUN_*`, `TEXT_MESSAGE_*`, `THINKING_TEXT_MESSAGE_*`, `STEP_*`, and `TOOL_CALL_*` events for UI clients.
+- `serveAgUiHttp(runtime)` exposes an AG-UI-compatible HTTP SSE bridge that projects runtime lifecycle, safe progress commentary, text output, upstream thinking, step progress, and tool calls onto `RUN_*`, `STATUS_UPDATE`, `TEXT_MESSAGE_*`, `THINKING_TEXT_MESSAGE_*`, `STEP_*`, and `TOOL_CALL_*` events for UI clients.
 - `createRuntimeMcpServer(runtime)` and `serveRuntimeMcpOverStdio(runtime)` expose the persisted runtime control surface itself as MCP tools, including sessions, requests, approvals, artifacts, events, and package export helpers.
 - `listRequestEvents(...)`, `listRequestTraceItems(...)`, and `exportRequestPackage(...)` are the request-first inspection helpers.
 - `exportRequestPackage(...)` and `exportSessionPackage(...)` package stable runtime records, transcript, approvals, events, artifacts, and governance evidence for operator tooling without reaching into persistence internals.

package/README.zh.md

@@ -72,13 +72,17 @@ try {
 仓库默认工作区也不是空壳，而是一套可直接体验的 starter runtime：
 
 - 一个默认 host agent：`orchestra`
-- 五个默认行为 SKILL：`workspace-inspection`、`safe-editing`、`delegation-discipline`、`approval-execution-policy`、`completion-discipline`
-- 一组覆盖文件检查、安全编辑、审批控制和 DeepAgents compatibility helpers 的 builtin tools
+- 一条放在 `resources/tools/` 下的 runtime-owned 工具路径，适合承载文件检查、运行时检查、审批与 schedule 这类产品工具
+- 默认 host 不再预加载 bootstrap memory 或行为 SKILL，这样 first-run 本地 chat 会更轻、更快；当你的 runtime 真正需要时，再显式添加 `memory:` 文件与 `skills:` 引用
 
 如果你想最快感受 first-run 体验，直接启动 chat shell，然后试下面这些真实请求：
 
 ```bash
-agent-harness chat --workspace .
+botbotgo
+# 或
+botbotgo "Inspect this workspace and explain the main entry points."
+# 或
+agent-harness "Inspect this workspace and explain the main entry points."
 ```
 
 - `Inspect this workspace and explain the main entry points.`
@@ -86,6 +90,11 @@ agent-harness chat --workspace .
 - `Update README.md to make the setup steps clearer.`
 - `Find the likeliest config issue in this workspace and propose the smallest fix.`
 
+当 runtime 发出 request 级 `plan-state` 更新以及安全的 `progress.commentary` 增量时，chat shell 现在会直接在终端里渲染实时 todo board 和进度播报，因此你可以在执行过程中看到规划和状态变化，而不必等到最终回复。
+这些进度播报现在会继续绑定在稳定的 runtime surface 上，例如 plan-state、tool 开始/完成、memory recall 与 agent delegation，因此 operator 可以看到类似 Codex 的清晰中间状态，但不会暴露私有模型推理。
+仓库默认的 `orchestra` host 现在也会被明确要求：对已经给清楚的多步任务不要再反问，而是直接开始执行；在非平凡工具工作前先调用 `write_todos`，并在运行过程中持续维护这块 todo board。
+durable memory 的写入现在也会在模型做 mutation reconciliation 之前，先通过配置好的 vector store 检索相关旧知识，再和确定性匹配结果合并，因此 update / delete 更容易命中正确的 knowledge identity，而不是生成几条相近但彼此独立的 fact。
+
 <a id="readme-zh-docs-path"></a>
 
 ## 阅读路径
@@ -146,8 +155,8 @@ agent-harness chat --workspace .
 **一句话：** 对外接口保持精简、运行时能力一次备齐，日常工作落在 **YAML 配置** 与 **扩展**（本地工具、SKILL、MCP）上，而不是反复搭建运行时底座。
 
 - **容易上手：** `createAgentHarness` → `request` → `stop`，以及 `subscribe`、`listSessions`、`listApprovals`、`resolveApproval` 等查询与控制能力。
-- **可复用 client 接入层：** `createAgentHarnessClient` / `createInProcessHarnessClient` 会把同一套 runtime-owned request、session、approval 与 stream API 绑定成统一的前端 client 契约，terminal、桌面壳和其他嵌入式 UI 可以共用这一层。
-- **面向跨进程 UI 的 ACP client 路径：** `createAcpHarnessClient`、`createAcpStdioHarnessClient` 与 `createAcpHttpHarnessClient` 让 UI 与 runtime 不在同一进程时，仍然可以通过 ACP 复用同一份 `HarnessClient` 契约，并保留 request-scoped `streamRequest(...)` 流里的 richer stream item，例如 `content-blocks`、`tool-result` 与 `upstream-event`。
+- **可复用 client 接入层：** `createAgentHarnessClient` / `createInProcessHarnessClient` 会把同一套 runtime-owned request、session、approval 与事件 API 绑定成统一的前端 client 契约，terminal、桌面壳和其他嵌入式 UI 可以共用这一层。
+- **面向跨进程 UI 的 ACP client 路径：** `createAcpHarnessClient`、`createAcpStdioHarnessClient` 与 `createAcpHttpHarnessClient` 让 UI 与 runtime 不在同一进程时，仍然可以通过 ACP 复用同一份 `HarnessClient` 契约，并保持 `request(...)` 作为唯一的请求入口，向 UI 提供完整 request snapshot 与增量 data。
 - **配置：** 路由、模型、工具、存储、后端、MCP、恢复与维护写在声明式工作区 YAML 里（见[快速开始](#readme-zh-quickstart)与[如何配置](#readme-zh-config)）。
 - **扩展：** 在 `resources/` 下放置 `tool({...})` 模块与 SKILL 包；共享工具与 MCP 写在 `config/catalogs/` 等 YAML 目录里，各 agent 再按名称白名单引用。
 - **内建运行时：** 持久化 `requests`、`sessions`、`approvals` 与 `events`；恢复与排队；流式监听；MCP 接入与对外暴露；以及后端适配——避免每个应用重复造这一层。
@@ -159,7 +168,7 @@ agent-harness chat --workspace .
 若你想先看「今天能直接用到什么」，可从本节读起。`agent-harness` 提供完整的产品级运行时能力，而不只是「能启动」的脚手架。
 
 - **核心 runtime API：** `createAgentHarness`、`request`、`subscribe`、`resolveApproval`、`recordArtifact`、各类查询与检查辅助 API，以及稳定持久化的 `requests`、`sessions`、`approvals`、`events` 与 artifacts 记录。
-- **前端/client 入口：** `createAgentHarnessClient`、`createInProcessHarnessClient`、`createAcpHarnessClient`、`createAcpStdioHarnessClient`、`createAcpHttpHarnessClient`、`HarnessClient` 以及 `streamRequest(...)` 风格的 client 调用，让产品壳层可以复用同一套 runtime 接入层，而不是每个 UI 各自重新绑定运行时调用。
+- **前端/client 入口：** `createAgentHarnessClient`、`createInProcessHarnessClient`、`createAcpHarnessClient`、`createAcpStdioHarnessClient`、`createAcpHttpHarnessClient` 与 `HarnessClient` 让产品壳层可以复用同一套 runtime 接入层，而不是每个 UI 各自重新绑定运行时调用。`request(...)` 负责流式 request；`subscribe(...)` 负责 runtime 生命周期事件。
 - **运行时 memory 与证据能力：** `memorize`、`recall`、`listMemories`、memory policy hooks、`recordArtifact`、`listArtifacts`、`getArtifact`、`exportEvaluationBundle`、`replayEvaluationBundle`，以及 request / session 级证据导出辅助函数。
 - **协议与传输层：** `createAcpServer`、`createAcpStdioClient`、`serveAcpStdio`、`serveAcpHttp`、`serveA2aHttp`、`serveAgUiHttp`，以及 `createRuntimeMcpServer` / `serveRuntimeMcpOverStdio`。
 - **受治理的工作区运行时：** 由 YAML 持有的路由、并发、维护、MCP 策略、runtime governance bundles，以及针对敏感 memory 或写类 MCP 副作用的默认审批门槛。
@@ -347,17 +356,31 @@ governance:
 npm install @botbotgo/agent-harness
 ```
 
+如果你希望 CLI 直接出现在 `PATH` 里，可以全局安装，然后在你自己的 workspace 根目录里运行：
+
+```bash
+npm install -g @botbotgo/agent-harness
+cd /path/to/your-workspace
+botbotgo
+botbotgo "Inspect this workspace and explain the main entry points."
+botbotgo -w /path/to/another-workspace "Summarize this project."
+```
+
+`botbotgo` 会把当前目录当作 workspace root。现在你可以直接在任意目录运行它：如果 `./config/` 不存在，CLI 会回退到内置的系统默认配置和内置资源；如果工作区里存在 `./config/` 或 `./resources/`，runtime 就会在系统默认值之上叠加你自己的配置与资源定义。
+
+开发时如果要把仓库自带的 Ollama workspace 切到共享远端，只需要在启动前设置环境变量即可：发布默认仍会回到 `http://127.0.0.1:11434` 这种本地 endpoint，而开发阶段可以通过 `AGENT_HARNESS_OLLAMA_BASE_URL=https://ollama-rtx-4070.easynet.world` 或 `AGENT_HARNESS_OPENAI_COMPATIBLE_BASE_URL=https://ollama-rtx-4070.easynet.world/v1` 覆盖到远端。
+
 工作区布局：
 
 ```text
 your-workspace/
   config/
+    models.yaml
     agent-context.md
     runtime/
       workspace.yaml
       runtime-memory.yaml
     catalogs/
-      models.yaml
       embedding-models.yaml
       vector-stores.yaml
       stores.yaml
@@ -560,20 +583,23 @@ const result = await request(runtime, {
 const result = await request(runtime, {
   agentId: "orchestra",
   input: "Inspect the workspace and explain the available tools.",
-  listeners: {
-    onChunk(chunk) {
-      process.stdout.write(chunk);
-    },
-    onContentBlocks(blocks) {
-      console.log(blocks);
-    },
-    onEvent(event) {
-      console.log(event.eventType, event.payload);
-    },
+  eventListener(snapshot) {
+    console.log(snapshot.state, snapshot.plan.items);
+  },
+  dataListener(event) {
+    if (event.type === "output.text.delta") {
+      process.stdout.write(event.text);
+    }
+    if (event.type === "tool.result") {
+      console.log(event.toolName, event.output);
+    }
   },
 });
 ```
 
+`eventListener(...)` 会收到最新的完整 request snapshot，包括 request 状态、todo board、approval 状态与当前输出。
+`dataListener(...)` 会收到 append-only 的增量数据，例如文本输出、进度播报、content blocks、tool results 与 upstream debug items。
+
 `subscribe(...)` 是对已存储生命周期事件的只读观察者接口。
 
 运行时事件流包括：
@@ -665,11 +691,12 @@ await stop(runtime);
 
 - `config/runtime/workspace.yaml`
 - `config/agent-context.md`
-- `config/catalogs/models.yaml`
+- `config/models.yaml`
 - `config/catalogs/embedding-models.yaml`
 - `config/catalogs/vector-stores.yaml`
 - `config/catalogs/stores.yaml`
 - `config/knowledge/knowledge-runtime.yaml`
+- `config/knowledge/procedural-memory-runtime.yaml`
 - `config/runtime/runtime-memory.yaml`
 - `config/catalogs/backends.yaml`
 - `config/catalogs/tools.yaml`
@@ -685,6 +712,8 @@ await stop(runtime);
 - YAML 对象语义由 `kind`、`metadata.name` 或 `id` 以及对象内容决定，而不是由文件路径决定
 - 本地工具会从 `resources/tools/**/*.js|*.mjs|*.cjs` 中自动发现，前提是模块导出 `tool({...})`
 - skills 会从 `resources/skills/**/SKILL.md` 自动发现
+- 一个最小工作区只放 `config/models.yaml` 也可以启动；仓库默认值会补上 `Runtime`、默认 `orchestra` host，以及默认开启的 runtime-managed durable memory
+- 如果不显式覆盖 runtime 放置位置，harness 生成的数据默认写到 `./.botbotgo/`
 
 示例工作区：
 
@@ -699,12 +728,15 @@ await stop(runtime);
 - `examples/07_multi-agent-research/` 是 Multi-Agent Research Example：最完整的多 agent 研究工作区，包含可复用 backend、skill 和本地 tool
 - `examples/08_long-term-memory-learning/` 是 Long-Term Memory Learning Example：通过多次 request 写入 durable memory、检查 recall，并让后续回答更懂上下文
 - `examples/09_long-running-coding-harness/` 是 Long-Running Coding Harness Example：用 host agent 加 app-owned planning/evaluation 角色，结合 Playwright MCP 与 evaluation bundle 承载长时 coding 会话
+- `examples/10_playwright-mcp-browser/` 是 Playwright CLI Browser Example：最小的浏览器能力工作区，对齐 Playwright 面向 coding agent 的官方推荐方式：`playwright-cli` 加本地 skill
 
 `resources/tools/` 下的工作区本地工具模块应统一用 `tool({...})` 导出。
 不支持历史/兼容写法，任何不带该导出形式的工具模块都会在工作区加载时被拒绝。
 本地 function tool 如果在模块里声明了 schema，runtime governance 会直接把该模块 schema 视为事实来源；不需要为了 schema-bound 元数据再额外复制一份 YAML `inputSchema.ref`。
 若本地工具使用 Zod schema，请让工作区或隔离的 `resources` 包统一使用 `zod@^4`，避免 raw shape validator 与 runtime 解析落在不同 major 版本上。
-对于 `backend: deepagent` 的 agent，runtime 还会提供一层内建 compatibility tools，补齐上游 DeepAgents 在长链路执行时默认依赖的 helper tools。目前这组兼容工具包括 `write_todos`、`read_todos`、`ls`、`read_file`、`write_file`、`edit_file`、`glob`、`grep`、`task`，以及在所选 backend 支持 sandbox command execution 时才会出现的 `execute`。`list_files`、`search_files`、`run_command`、`delegate_task` 这类更面向 public runtime 的别名工具只是额外暴露的 surface，不会替代上游 DeepAgents 兼容名。
+如果你要提供 `list_files`、`search_files`、`run_command`、`schedule_task`、request/approval/artifact inspection 这类 runtime-owned 产品工具，请把它们当成普通工作区工具写进 `resources/tools/*.mjs`，再由 agent YAML 按名称白名单启用。
+对于 `backend: deepagent` 的 agent，runtime 仍会保留一层内部 compatibility tools，补齐上游 DeepAgents 在长链路执行时默认依赖的 helper tools。目前这组兼容工具包括 `write_todos`、`read_todos`、`ls`、`read_file`、`write_file`、`edit_file`、`glob`、`grep`、`task`，以及在所选 backend 支持 sandbox command execution 时才会出现的 `execute`。应当把这些 helper 名视为 adapter 内部执行兼容层，而不是主要的产品级工作区工具面。
+如果想准确理解这里的“TODO 支持”边界，请看 [`docs/todo-support-matrix.zh.md`](./docs/todo-support-matrix.zh.md)。当前契约是：对 DeepAgents todo helper flow 提供完整支持，并把结果投影成 request 级可持久化的 plan state；它不是一套 backend-neutral 的 TODO 产品本体。
 
 配置大致分这几层（由下至上叠加）：
 
@@ -776,7 +808,7 @@ kind: Runtime
 metadata:
   name: default
 spec:
-  runtimeRoot: ./.agent
+  dataRoot: ./.botbotgo
   toolModuleDiscovery:
     scope: top-level
   concurrency:
@@ -817,7 +849,7 @@ spec:
 
 加载为 `model/default`。
 
-`kind: Models` catalog 可以放在 `config/` 下任意位置；`config/catalogs/models.yaml` 只是推荐布局。
+`kind: Models` catalog 可以放在 `config/` 下任意位置；仓库默认值现在把 `models.yaml` 放在 `config/` 根目录，而文件路径本身只是一种组织方式。
 
 ### `config/**` 下的 Embedding Model Catalog
 
@@ -861,7 +893,24 @@ spec:
 
 当同一套 durable-memory policy 还需要运行在 `AgentHarnessRuntime` 之外，例如独立 knowledge worker 或 knowledge server 时，使用这个单例对象。
 
-`KnowledgeRuntime` 故意镜像 durable policy 的主形状。`RuntimeMemory` 继续承载 runtime 内部默认值；而当外部 knowledge service 也需要同一套 memorize/recall policy 时，再保留 `KnowledgeRuntime` 作为可外置的镜像对象。
+`KnowledgeRuntime` 故意镜像 durable policy 的主形状。`RuntimeMemory` 继续承载 runtime 内部默认值；而当外部 knowledge service 也需要同一套 memorize/recall policy 时，再保留 `KnowledgeRuntime` 作为可外置的镜像对象。它适合继续承担快速显式写入，以及 durable knowledge 的后台整理和长期养护。
+
+### `config/knowledge/procedural-memory-runtime.yaml`
+
+当工作区需要一层独立的后台经验记忆，例如 ReMe 驱动的 procedural memory 池时，使用这个单例对象。
+
+`ProceduralMemoryRuntime` 会刻意和 `KnowledgeRuntime` 分开：
+
+- `KnowledgeRuntime` 继续放 durable facts、preferences、rules 和 confirmed decisions
+- `ProceduralMemoryRuntime` 继续放 workflows、debugging lessons、tactics 和 reusable procedures
+- 两者都落在同一个 `knowledge/` 目录下，但不强行共用一个逻辑 store
+
+仓库默认建议是：
+
+- `KnowledgeRuntime`：hot path + 后台形成 + 长期养护
+- `ProceduralMemoryRuntime`：后台形成 + 定时或空闲整理
+
+对于 `backend: deepagent` 的工作区，应继续把 context compaction 留给上游 DeepAgents，只把 procedural memory 当作后台学习层使用。
 
 ### `config/catalogs/backends.yaml`
 
@@ -919,7 +968,7 @@ Agent YAML 可以放在 `config/` 下任意位置；`config/agents/*.yaml` 是
 
 两个区块：
 
-- `spec.runtime`：harness 侧运行时放置，例如 `spec.runtime.runtimeRoot`
+- `spec.runtime`：agent 级 runtime 放置覆盖，例如 `spec.runtime.runtimeRoot`
 - `spec` 顶层字段：上游执行语义与面向适配器的配置
 
 direct 主机示例：
@@ -930,8 +979,6 @@ kind: Agent
 metadata:
   name: direct
 spec:
-  runtime:
-    runtimeRoot: ./.agent
   backend: langchain-v1
   modelRef: model/default
   tools:
@@ -954,9 +1001,12 @@ spec:
         enabled: true
         rootDir: "{runtimeRoot}/sessions/{sessionId}/filesystem"
     middleware: []
-    systemPrompt: Answer simple requests directly.
+    systemPrompt:
+      path: ../prompts/direct-system.md
 ```
 
+较长的 prompt 建议放在受版本控制的文件里，例如 `config/prompts/*.md`，再通过相对于 agent YAML 的 `systemPrompt.path` 引用。这样 prompt 文本不会散落在 source code 里，评审时也能把它当作普通内容变更来检查。
+
 当 LangChain 绑定启用 `config.filesystem.sessionStorage.enabled: true` 时，runtime 会为每个持久化 session 维护独立的 filesystem 根目录，并按 session 复用 runnable cache，而不是把所有请求都压到同一个共享工作目录里。
 
 orchestra 主机示例：
@@ -967,8 +1017,6 @@ kind: Agent
 metadata:
   name: orchestra
 spec:
-  runtime:
-    runtimeRoot: ./.agent
   backend: deepagent
   modelRef: model/default
   memory:
@@ -1060,14 +1108,15 @@ ACP transport 说明：
 - ACP transport 现已覆盖核心参考客户端流程验证：capability discovery、request submit、session lookup、request lookup、invalid JSON 处理、无 id notification 不返回响应，以及 stdio JSON-RPC 与 HTTP + SSE runtime notifications。
 - 现在还额外有一条跨协议一致性回归门：ACP 发起的 request、A2A 读取或继续的 task，以及 runtime MCP 暴露的检查结果，必须始终指向同一组持久化 `sessionId` / `requestId` 运行时记录，不能漂移成各协议各自维护的标识体系。
 - 如果要从最薄的一层 editor / CLI starter 开始，优先用 `agent-harness acp serve --workspace . --transport stdio`，并直接参考 `examples/03_protocol-surfaces/app/acp-stdio/main.mjs` 的 wire shape。需要在应用内使用 reference client 时，可直接用 `createAcpStdioClient(...)` 发起 JSON-RPC 请求并分流 runtime notifications，避免每个 sidecar 自己重写 line parsing。
-- `agent-harness chat --workspace .` 现在提供了一层基于 ACP 的轻量终端壳：默认会拉起 subprocess ACP stdio server，也可以通过 `--transport http --host <host> --port <port>` 直连已运行的 ACP HTTP endpoint。因此 CLI UI 继续保持在 runtime 之外的独立进程，同时复用同一份 `HarnessClient` 契约。一次性调用可用 `--message`，交互模式则支持 `/context`、`/new`、`/agent <agentId>`、`/sessions`、`/requests`、`/resume <sessionId>`、`/approvals`、`/approve`、`/reject`、`/cancel`、`/events`、`/trace`、`/health`、`/overview`、`/session`、`/request [requestId]` 与 `/exit`。`/resume` 现在会先校验目标 session，恢复它的 latest request id，并同步 active agent context；`/request <requestId>` 可以把当前上下文切到某个已持久化 request；`/new` 则会在不退出 shell 的情况下清空当前 session/request context。当 ACP streaming 发出 richer request-scoped item 时，终端壳也会把 tool result 与文本型 content blocks 渲染出来。
+- 对发布后的安装包来说，`botbotgo` 是最短的本地终端入口。它会默认把当前目录当作 workspace，所以团队只需要 `cd` 到自己的 runtime workspace，然后直接运行 `botbotgo` 或 `botbotgo "..."`。`agent-harness` 也保留同样的隐式 chat 行为；如果要从同一个 shell 指向别的 workspace，继续用 `-w/--workspace` 即可。
+- `agent-harness chat --workspace .` 则继续保留为显式子命令形式的本地终端壳：默认 `stdio` 路径会直接在当前进程里连接 workspace runtime，而 `--transport http --host <host> --port <port>` 仍然可以直连已运行的 ACP HTTP endpoint。一次性调用可用 `--message`，交互模式则支持 `/context`、`/new`、`/agent <agentId>`、`/sessions`、`/requests`、`/resume <sessionId>`、`/approvals`、`/approve`、`/reject`、`/cancel`、`/events`、`/trace`、`/health`、`/overview`、`/session`、`/request [requestId]` 与 `/exit`。`/resume` 现在会先校验目标 session，恢复它的 latest request id，并同步 active agent context；`/request <requestId>` 可以把当前上下文切到某个已持久化 request；`/new` 则会在不退出 shell 的情况下清空当前 session/request context。终端 chat 现在统一走一条面向 operator 的输出路径：tool 和进度事件会实时打印，最终完整答复也会继续输出，而不再切到单独的 request-tree-only 模式。
 - 如果是在仓库源码目录里直接运行，请使用 `npm run chat -- --workspace ./config`，或者 `npm run agent-harness -- chat --workspace ./config`。这里额外的 `--` 不能省略，否则 npm 会把 `--workspace` 当成它自己的 workspace 参数。只有在包已经被安装或 `npm link` 到系统环境后，`agent-harness ...` 这个独立命令才会出现在 `PATH` 里。
 - 交互式 chat 现在还会先显示一块更大的 ASCII 启动画面，明确打印当前 workspace、transport 和上下文覆盖信息，再进入命令帮助，因此终端壳更像一个完整的 runtime console，而不只是裸 REPL。
 - 当 workspace 配置的模型/provider 无法连通时，chat 现在会把 `runtime_error=fetch failed` 这类泛化失败展开成可操作的诊断信息，明确打印当前 provider、model、endpoint 以及具体修复提示，而不再只留下一个不透明的传输层错误。
 - chat 启动时现在还会对本地 Ollama 路径做一次轻量 preflight。如果当前 endpoint 不可达，或者直接返回 `404 page not found`，shell 会在第一条 prompt 之前先打印这条告警，这样 endpoint 配错的问题会在启动时立即暴露，而不必等第一条消息失败后才知道。
 - 交互式 prompt 现在会同时显示当前 `agent`、`session` 和短 `request` 标识，因此每轮回复之后以及使用 shell 历史记录时，用户都还能清楚地看到自己正处在哪个 runtime turn 上，而不会掉回一个没有上下文的裸输入提示。
 - `serveA2aHttp(runtime)` 提供 A2A HTTP JSON-RPC bridge 与 agent card discovery，同时兼容 `message/send` 这类旧方法，以及 `SendMessage`、`SendStreamingMessage`、`GetTask`、`ListTasks`、`CancelTask`、`SubscribeToTask`、`GetAgentCard`、`GetExtendedAgentCard` 与 task push-notification config 这类 A2A v1.0 方法，并统一映射到现有 session/request 运行记录。bridge 现在会同时声明 `1.0` 与 `0.3` 两个 JSON-RPC interface、在 agent card 路径上响应 `HEAD` / `OPTIONS` discovery、写出支持版本的 discovery headers、可选暴露 registry URL 与 detached signed-card metadata 供外围发现系统使用、校验 `A2A-Version`、把 `A2A-Extensions` 记录进 runtime invocation metadata、发布 `TASK_STATE_*` 状态与 `SendMessage` 的 `{ task }` wrapper、在 v1 streaming 方法上先通过 SSE 输出 `{ task }` 初始快照，再输出 `{ statusUpdate }` 增量状态，并可向已配置的 webhook receiver 发送 best-effort task push notifications。
-- `serveAgUiHttp(runtime)` 提供 AG-UI HTTP SSE bridge，把 runtime 生命周期、文本输出、upstream thinking、step 进度与 tool call 投影成 `RUN_*`、`TEXT_MESSAGE_*`、`THINKING_TEXT_MESSAGE_*`、`STEP_*` 与 `TOOL_CALL_*` 事件，便于 UI 客户端直接接入。
+- `serveAgUiHttp(runtime)` 提供 AG-UI HTTP SSE bridge，把 runtime 生命周期、安全进度播报、文本输出、upstream thinking、step 进度与 tool call 投影成 `RUN_*`、`STATUS_UPDATE`、`TEXT_MESSAGE_*`、`THINKING_TEXT_MESSAGE_*`、`STEP_*` 与 `TOOL_CALL_*` 事件，便于 UI 客户端直接接入。
 - `createRuntimeMcpServer(runtime)` 与 `serveRuntimeMcpOverStdio(runtime)` 会把持久化 runtime 控制面本身暴露成 MCP tools，包括 sessions、requests、approvals、artifacts、events 与 package export helpers。
 - `listRequestEvents(...)`、`listRequestTraceItems(...)` 与 `exportRequestPackage(...)` 是 request-first 的检查 helper。
 - `exportRequestPackage(...)` 与 `exportSessionPackage(...)` 可把稳定 runtime 记录、transcript、approvals、events、artifacts 与 governance evidence 一起打包给管理工具，而不必直接访问 persistence 内部实现。

package/dist/acp.d.ts

@@ -46,6 +46,9 @@ export type AcpServerCapabilities = {
         submit: true;
         list: true;
         get: true;
+        plan: {
+            get: true;
+        };
         cancel: true;
         stream: true;
         trace: {

package/dist/acp.js

@@ -1,7 +1,7 @@
-import { cancelRequest, getApproval, getArtifact, getHealth, getOperatorOverview, getRequest, getSession, listApprovals, listRequestEvents, listRequestArtifacts, listRequestTraceItems, listRequests, listSessionSummaries, listSessions, request, resolveApproval, } from "./api.js";
+import { cancelRequest, getApproval, getArtifact, getHealth, getOperatorOverview, getRequestPlanState, getRequest, getSession, listApprovals, listRequestEvents, listRequestArtifacts, listRequestTraceItems, listRequests, listSessionSummaries, listSessions, request, resolveApproval, } from "./api.js";
 const CAPABILITIES = {
     sessions: { list: true, get: true, summaries: true },
-    requests: { submit: true, list: true, get: true, cancel: true, stream: true, trace: { list: true } },
+    requests: { submit: true, list: true, get: true, plan: { get: true }, cancel: true, stream: true, trace: { list: true } },
     approvals: { list: true, get: true, resolve: true },
     artifacts: { list: true, read: true },
     events: { subscribe: true, list: true },
@@ -140,6 +140,7 @@ export class AgentHarnessAcpServer {
             "requests.submit",
             "requests.list",
             "requests.get",
+            "requests.plan.get",
             "requests.cancel",
             "requests.stream",
             "requests.trace.list",
@@ -216,6 +217,13 @@ export class AgentHarnessAcpServer {
                 const payload = asObject(params, method);
                 return getRequest(this.runtime, readRequiredString(payload.requestId, "requestId", method));
             }
+            case "requests.plan.get": {
+                const payload = asObject(params, method);
+                return getRequestPlanState(this.runtime, {
+                    sessionId: readRequiredString(payload.sessionId, "sessionId", method),
+                    requestId: readRequiredString(payload.requestId, "requestId", method),
+                });
+            }
             case "requests.trace.list": {
                 const payload = asObject(params, method);
                 return listRequestTraceItems(this.runtime, {