@botbotgo/agent-harness 0.0.211 → 0.0.213

package/README.md

@@ -39,7 +39,7 @@
 
 <p align="center">
   <em
-    >We specialize in AI solutions. If you have a product idea you want to ship,
+    >For AI solutions and help shipping a product idea, contact
     <a href="mailto:info@easynet.world">info@easynet.world</a>.</em
   >
 </p>
@@ -71,11 +71,11 @@ them without forcing a rewrite.
 
 ## Documentation Paths
 
-Read the repository in this order:
+Choose an entry point that matches what you need:
 
 - **Technology:** capability comparison, runtime model, protocol surfaces, API, recovery, approvals, and operator control
 - **Product:** what the stable runtime surface already is, which product scenarios it fits, and why it is not another agent framework
-- **Commercial:** deployment support, launch help, hardening, and handoff once the technical fit and product scope are clear
+- **Commercial:** pricing, engagement process, and scoped services for deployment help, launch hardening, and team handoff
 
 Recommended entry points:
 
@@ -87,7 +87,7 @@ Recommended entry points:
 
 ## License & Commercial Support
 
-This repository is licensed under **Apache License 2.0**.
+This project is licensed under **Apache License 2.0**.
 [LICENSE](./LICENSE)
 
 Core runtime is open source: inspect and run it freely.
@@ -120,18 +120,18 @@ Additional docs:
 - **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; LangChain v1 and DeepAgents adapters—so you do not rebuild that layer per app.
 
-## Current Public Surface
+## Runtime capabilities at a glance
 
-The package is more than a thin bootstrap: the public surface is broad enough to describe as a full product runtime with external protocol boundaries—not just YAML plus tools.
+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`, inspection helpers, and stable persisted runtime records for `requests`, `sessions`, `approvals`, `events`, and artifacts.
 - **Runtime memory and evidence:** `memorize`, `recall`, `listMemories`, memory policy hooks, `listArtifacts`, `getArtifact`, `exportEvaluationBundle`, `replayEvaluationBundle`, and request/session evidence export helpers.
 - **Protocol and transport surfaces:** `createAcpServer`, `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.
 
-`deepagents-acp` is part of the current public story, not only a direction hidden in planning notes: `agent-harness` is moving toward a standard runtime boundary that external clients can talk to directly while the harness keeps persistence, recovery, approvals, and operator control runtime-owned.
+If you integrate external clients, treat `deepagents-acp` as the primary protocol direction: clients connect through that surface while `agent-harness` keeps persistence, recovery, approvals, and operator control on the runtime side.
 
-## What Problem We Solve
+## The problem this solves
 
 In one line: `agent-harness` productizes the runtime work that usually appears after the demo.
 
@@ -222,7 +222,7 @@ In practice, the harness exists for the parts that are expensive and repetitive
 - queueing, concurrency, maintenance, and operational policy
 - stable runtime records that stay usable even if the backend changes
 
-The repository-owned default config layer is intentionally full-shaped. The shipped YAML keeps explicit defaults for the important runtime and agent knobs so teams can start from concrete configuration instead of reverse-engineering adapter behavior from source.
+The default workspace configuration shipped with the package is deliberately full-shaped. The bundled YAML keeps explicit defaults for important runtime and agent knobs so teams can start from concrete configuration instead of reverse-engineering adapter behavior from source.
 
 The default rule is:
 
@@ -242,7 +242,7 @@ Start with these user-facing docs:
 - `docs/long-term-memory.md`
 - `docs/memory-policy-reference.md`
 
-Additional contributor-oriented design notes live in the repository; you do not need them for everyday integration and operations.
+Deeper design notes and boundary discussions ship alongside the package for advanced readers; everyday integration and operations rely on the README, developer docs, and topical references above.
 
 `deepagents-acp` is the required external protocol direction when external tools need a standard runtime boundary. The harness should conform to `deepagents-acp` semantics at that boundary while keeping runtime lifecycle, persistence, recovery, and governance harness-owned.
 
@@ -252,20 +252,6 @@ Recommended orchestration shape for long-running flows:
 - use `backend: deepagent` when you want high-level execution semantics with minimal application wiring
 - keep `backend: langchain-v1` for lighter direct-response or explicitly chosen V1 agent shapes
 
-## Why This Exists
-
-Most agent tooling stops at execution. Production software does not.
-
-Real products need a runtime that can answer harder questions:
-
-- Where do requests live?
-- How are approvals resolved?
-- What survives process restart?
-- How do you inspect sessions and events without exposing raw backend state?
-- How do you swap backend implementations without rewriting the product model?
-
-`agent-harness` is the layer that answers those questions without turning your application API into a mirror of LangChain v1 or DeepAgents.
-
 ## What Makes It Different
 
 - It treats `requests`, `sessions`, `approvals`, `events`, and recovery as first-class product records
@@ -719,7 +705,7 @@ Current temporary limits on the `backend: langchain-v1` path are:
 
 - approval-gated side-effect tools are less reliable than the DeepAgents path under real remote models
 - long multi-agent or orchestration-heavy flows are not the recommended default path
-- the repository now treats DeepAgents as the default execution path for complex runtime coverage, and LangChain v1 should be selected explicitly when a workspace truly wants that behavior
+- the package now treats DeepAgents as the default execution path for complex runtime coverage, and LangChain v1 should be selected explicitly when a workspace truly wants that behavior
 
 Practical guidance:
 
@@ -1033,12 +1019,15 @@ ACP transport notes:
 
 - `serveAcpStdio(runtime)` exposes newline-delimited JSON-RPC over stdio for local IDE, CLI, or subprocess clients.
 - `serveAcpHttp(runtime)` exposes JSON-RPC over HTTP plus SSE runtime events so remote operator surfaces can connect without importing the runtime in-process.
+- 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.
+- For the thinnest editor or CLI starter, begin with `agent-harness acp serve --workspace . --transport stdio` and mirror the `examples/protocol-hello-world/app/acp-stdio-hello-world.mjs` wire shape.
 - `serveA2aHttp(runtime)` exposes an A2A-compatible HTTP JSON-RPC bridge plus agent card discovery, mapping both existing methods such as `message/send` and newer aliases such as `SendMessage`, `GetTask`, `ListTasks`, `CancelTask`, and `SubscribeToTask` onto the existing session/request runtime surface.
 - `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.
 - `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(...)` and `exportRequestPackage(...)` are the request-first inspection helpers.
 - `exportRequestPackage(...)` and `exportSessionPackage(...)` package stable runtime records, transcript, approvals, events, and artifacts for operator tooling without reaching into persistence internals.
 - `runtime/default.governance.remoteMcp` can now deny or allow specific MCP servers, raise approval requirements by transport, and stamp transport-based risk tiers into runtime governance bundles. MCP server catalogs can also declare trust tier, access mode, tenant scope, approval policy, prompt-injection risk, and OAuth scope metadata so governance bundles capture why one remote tool is treated as high-risk.
+- Protocol responsibilities stay split on purpose: ACP is the primary editor/client runtime boundary, A2A is the polling-first agent-platform bridge, AG-UI is the UI event surface, and runtime MCP is the operator-facing control plane exported as MCP tools.
 - `runtime/default.observability.tracing` can now describe exporter metadata such as OTLP endpoints and propagation mode, so frozen runtime snapshots keep trace-correlation plus operator-visible export context without exposing backend-private span internals.
 - `agent-harness runtime overview`, `agent-harness runtime health`, `agent-harness runtime approvals list|watch`, and `agent-harness runtime runs list|tail` provide a thin operator CLI over persisted runtime health, queue pressure, governance risk, approval queues, and active run state.
 - detailed A2A adapter guidance lives in [`docs/a2a-bridge.md`](docs/a2a-bridge.md)

package/README.zh.md

@@ -27,7 +27,7 @@
 </p>
 
 <p align="center">
-  <a href="https://botbotgo.github.io/agent-harness/development/">开发文档</a>
+  <a href="https://botbotgo.github.io/agent-harness/development/zh/">开发文档</a>
   （多页面静态文档位于 <code>docs/development/</code>，支持 English / 中文）
 </p>
 
@@ -39,7 +39,7 @@
 
 <p align="center">
   <em
-    >我们专注于 AI 解决方案。若有希望落地的产品想法，欢迎来信
+    >如需 AI 解决方案或产品落地支持，欢迎来信
     <a href="mailto:info@easynet.world">info@easynet.world</a>。</em
   >
 </p>
@@ -69,23 +69,23 @@ try {
 
 ## 阅读路径
 
-建议按这个顺序理解仓库：
+按你的目标选入口即可：
 
-- **技术：** 能力对比、运行模型、协议接入、API、恢复、审批与运维控制
-- **产品：** 稳定的公开运行时能力、适用场景，以及它为何不是又一个 agent 框架
-- **商业：** 在技术与产品范围理清之后，再谈部署支持、上线协助、加固与交接
+- **想尽快接入：** 从[开发文档](./docs/development/zh/index.html)起步，再按需打开 API、协议与 Cookbook。
+- **想弄清边界：** 读[并列对比](./docs/development/zh/comparison.html)，区分运行时产品与上游执行框架。
+- **需要部署、加固或交接支持：** 查看[商业服务](./docs/commercial-pricing.md)与[合作流程](./docs/enterprise-process.md)。
 
 推荐入口：
 
-- [开发文档入口](./docs/development/index.html)
-- [并列对比页](./docs/development/comparison.html)
-- [API 参考](./docs/development/api-reference.html)
-- [协议接入说明](./docs/development/protocol-surfaces.html)
+- [开发文档入口](./docs/development/zh/index.html)
+- [并列对比页](./docs/development/zh/comparison.html)
+- [API 参考](./docs/development/zh/api-reference.html)
+- [协议接入说明](./docs/development/zh/protocol-surfaces.html)
 - [商业服务价格说明](./docs/commercial-pricing.md)
 
 ## 许可证与商业支持
 
-本仓库采用 **Apache License 2.0** 开源许可。[查看 LICENSE](./LICENSE)
+本项目采用 **Apache License 2.0** 开源许可。[查看 LICENSE](./LICENSE)
 
 核心运行时开源，可自由查看与试用。
 商业支持侧重帮助团队完成生产落地与交接，例如：
@@ -116,18 +116,18 @@ try {
 - **扩展：** 在 `resources/` 下放置 `tool({...})` 模块与 SKILL 目录，在目录里声明共享工具与 MCP，再由各 agent 按名字白名单启用。
 - **内建运行时：** 持久化 `requests`、`sessions`、`approvals` 与 `events`；恢复与排队；流式监听；MCP 接入与对外暴露；LangChain v1 与 DeepAgents 适配——避免每个应用重复造这一层。
 
-## 当前公开能力面
+## 运行时能力速览
 
-想先了解「今天能直接用什么」，可从本节读起。`agent-harness` 提供完整运行时能力，而不只是启动脚手架。
+若你想先看「今天能直接用到什么」，可从本节读起。`agent-harness` 提供完整的产品级运行时能力，而不只是「能启动」的脚手架。
 
 - **核心 runtime API：** `createAgentHarness`、`request`、`subscribe`、`resolveApproval`、各类查询与检查辅助 API，以及稳定持久化的 `requests`、`sessions`、`approvals`、`events` 与 artifacts 记录。
 - **运行时 memory 与证据能力：** `memorize`、`recall`、`listMemories`、memory policy hooks、`listArtifacts`、`getArtifact`、`exportEvaluationBundle`、`replayEvaluationBundle`，以及 request / session 级证据导出辅助函数。
 - **协议与传输层：** `createAcpServer`、`serveAcpStdio`、`serveAcpHttp`、`serveA2aHttp`、`serveAgUiHttp`，以及 `createRuntimeMcpServer` / `serveRuntimeMcpOverStdio`。
 - **受治理的工作区运行时：** 由 YAML 持有的路由、并发、维护、MCP 策略、runtime governance bundles，以及针对敏感 memory 或写类 MCP 副作用的默认审批门槛。
 
-如果你的产品需要对接外部客户端，也可以从这里理解边界：`deepagents-acp` 是主要的外部协议方向，而持久化、恢复、审批和运行控制仍由 `agent-harness` 负责。
+若你的产品需要对接外部客户端，可从本节理解边界：`deepagents-acp` 是主要的外部协议接入方向；持久化、恢复、审批与运行控制仍由 `agent-harness` 在运行时侧承担。
 
-## 我们解决什么问题
+## 这能解决什么问题
 
 一句话概括：`agent-harness` 把通常在 demo 之后才不得不补上的运行时工作，提前做成产品运行时的一部分。
 
@@ -218,27 +218,27 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 - 队列、并发、维护与运维策略
 - 即使后端变更也保持稳定的运行时记录模型
 
-仓库自带的默认配置刻意做成「形状完整」。随仓库提供的 YAML 对关键运行时与 agent 开关给出显式默认值，便于从具体配置起步，而不必从源码反推适配器行为。
+本包附带的默认工作区配置刻意做成「形状完整」。随发行版提供的 YAML 对关键运行时与 agent 开关给出显式默认值，便于从具体配置起步，而不必从源码反推适配器行为。
 
 默认原则是：
 
 - 若 LangChain v1 或 DeepAgents 已有能力，则在 YAML 中映射并在内部适配
 - 除非问题确实属于运行时职责，否则不增加新的公共运行时 API
 
-建议从这些面向用户的文档开始：
+建议从这些面向用户的文档开始（中文多页面在 `docs/development/zh/`）：
 
-- `docs/development/index.html`
-- `docs/development/getting-started.html`
-- `docs/development/comparison.html`
-- `docs/development/api-reference.html`
-- `docs/development/protocol-surfaces.html`
-- `docs/development/cookbook.html`
+- `docs/development/zh/index.html`
+- `docs/development/zh/getting-started.html`
+- `docs/development/zh/comparison.html`
+- `docs/development/zh/api-reference.html`
+- `docs/development/zh/protocol-surfaces.html`
+- `docs/development/zh/cookbook.html`
 - `docs/runtime-inspection-contract.md`
 - `docs/tool-execution-policy.md`
 - `docs/long-term-memory.md`
 - `docs/memory-policy-reference.md`
 
-仓库中也包含面向贡献者的设计说明与边界讨论；日常接入与运维不必先读这些内容。
+项目内还包含面向进阶读者与贡献者的设计说明与边界讨论；日常接入与运维以 README、开发文档与上文专题为准即可。
 
 当外部工具需要标准运行时边界时，`deepagents-acp` 是必须遵循的外部协议方向。`agent-harness` 应在该边界上严格契合 `deepagents-acp` 语义，同时继续把运行时生命周期、持久化、恢复与治理保留在 harness 内部。
 
@@ -248,20 +248,6 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 - 想用高层执行语义、少写应用编排时，优先选择 `backend: deepagent`
 - 轻量 direct-response 或明确需要 V1 agent 语义时，使用 `backend: langchain-v1`
 
-## 为何需要它
-
-多数 agent 工具停在「能跑」，但生产软件不能只停在这里。
-
-真实产品需要能回答更难问题的运行时：
-
-- 请求（requests）存在哪里？
-- 审批如何闭环？
-- 进程重启后什么还在？
-- 如何在不暴露原始后端状态的前提下检查会话与事件？
-- 如何在不大改产品模型的前提下替换后端实现？
-
-`agent-harness` 在不把应用 API 做成 LangChain v1 / DeepAgents 翻版的前提下，回答这些问题。
-
 ## 有何不同
 
 - 将 `requests`、`sessions`、`approvals`、`events` 与恢复视为核心产品数据（长期可查、可治理）
@@ -676,7 +662,7 @@ await stop(runtime);
 
 - 在真实远端模型下，带 approval 的副作用工具调用稳定性弱于 DeepAgents 路径
 - 不建议把它作为长链路、多 agent、重 orchestration 流程的默认执行路径
-- 仓库当前已把 DeepAgents 作为复杂运行时覆盖的默认主路径；只有在工作区明确需要 V1 行为时，才应显式选择 LangChain v1
+- 本包当前已把 DeepAgents 作为复杂运行时覆盖的默认主路径；只有在工作区明确需要 V1 行为时，才应显式选择 LangChain v1
 
 实际建议：
 
@@ -991,12 +977,15 @@ ACP transport 说明：
 
 - `serveAcpStdio(runtime)` 提供基于 stdio 的 newline-delimited JSON-RPC，适合本地 IDE、CLI 或子进程客户端。
 - `serveAcpHttp(runtime)` 提供基于 HTTP 的 JSON-RPC 与 SSE runtime events，适合远程界面或独立控制面接入。
+- ACP transport 现已覆盖核心参考客户端流程验证：capability discovery、request submit、session lookup、request lookup、invalid JSON 处理、无 id notification 不返回响应，以及 stdio JSON-RPC 与 HTTP + SSE runtime notifications。
+- 如果要从最薄的一层 editor / CLI starter 开始，优先用 `agent-harness acp serve --workspace . --transport stdio`，并直接参考 `examples/protocol-hello-world/app/acp-stdio-hello-world.mjs` 的 wire shape。
 - `serveA2aHttp(runtime)` 提供 A2A HTTP JSON-RPC bridge 与 agent card discovery，同时兼容 `message/send` 这类旧方法，以及 `SendMessage`、`GetTask`、`ListTasks`、`CancelTask`、`SubscribeToTask` 这类更新的方法别名，并统一映射到现有 session/request 运行记录。
 - `serveAgUiHttp(runtime)` 提供 AG-UI HTTP SSE bridge，把 runtime 生命周期、文本输出、upstream thinking、step 进度与 tool call 投影成 `RUN_*`、`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(...)` 与 `exportRequestPackage(...)` 是 request-first 的检查 helper。
 - `exportRequestPackage(...)` 与 `exportSessionPackage(...)` 可把稳定 runtime 记录、transcript、approvals、events 和 artifacts 打包给管理工具，而不必直接访问 persistence 内部实现。
 - `runtime/default.governance.remoteMcp` 现在可以按 MCP server 或 transport 做 allow/deny、审批升级，并把 transport 风险等级写进 runtime governance bundles。MCP server catalog 也可以声明 trust tier、access mode、tenant scope、approval policy、prompt-injection risk 与 OAuth scope 元数据，让治理快照能解释为什么某个远端工具被视为高风险。
+- 协议分工要继续保持清晰：ACP 是 editor / client 的主运行时边界，A2A 是轮询优先的 agent-platform bridge，AG-UI 是 UI 事件面，runtime MCP 是以 MCP tools 暴露的 operator control plane。
 - `runtime/default.observability.tracing` 现在可描述 OTLP endpoint 和 propagation mode 这类 exporter 元数据，使冻结的 runtime snapshot 在保留 trace correlation 的同时，也能保留有用的导出上下文，而不暴露 backend 私有 span 细节。
 - `agent-harness runtime overview`、`agent-harness runtime health`、`agent-harness runtime approvals list|watch` 与 `agent-harness runtime runs list|tail` 提供了一层轻量 CLI，可直接查看 runtime health、queue pressure、governance risk、审批队列和运行状态。
 - 更详细的 A2A 适配层开发说明见 [`docs/a2a-bridge.md`](docs/a2a-bridge.md)

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.210";
+export declare const AGENT_HARNESS_VERSION = "0.0.212";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.210";
+export const AGENT_HARNESS_VERSION = "0.0.212";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.211",
+  "version": "0.0.213",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",
@@ -70,6 +70,7 @@
     "test:real-providers": "vitest run test/providers/real-provider-harness.test.ts",
     "security:ci": "npm audit --omit=dev --audit-level=high",
     "security:report": "npm audit --omit=dev --json > security-audit-report.json || true",
+    "docs:sync-dev-nav": "node ./scripts/sync-developer-docs-nav.mjs",
     "release:prepare": "npm version patch --no-git-tag-version && node ./scripts/sync-example-version.mjs",
     "release:pack": "npm pack --dry-run",
     "release:publish": "npm publish --access public --registry https://registry.npmjs.org/"