@botbotgo/agent-harness 0.0.200 → 0.0.202

package/README.md

@@ -192,6 +192,7 @@ Start with these user-facing docs:
 
 - `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`

package/README.zh.md

@@ -79,14 +79,14 @@
 
 ## 当前公开能力面
 
-这个仓库现在公开交付的已经不只是一个很薄的 runtime bootstrap。对外能力已经足够大，首页和文档也应该把它描述成一个带外部协议边界的产品级 runtime，而不只是 “YAML + tools”。
+如果你想先知道今天能直接用什么，可以先看这一节。`agent-harness` 已经提供完整的运行时能力，而不只是一个启动脚手架。
 
 - **核心 runtime API：** `createAgentHarness`、`request`、`subscribe`、`resolveApproval`、各类 inspection helper，以及稳定持久化的 `requests`、`sessions`、`approvals`、`events` 和 artifacts 记录。
 - **运行时 memory 与证据能力：** `memorize`、`recall`、`listMemories`、memory policy hooks、`listArtifacts`、`getArtifact`、`exportEvaluationBundle`、`replayEvaluationBundle`，以及 request / session 级证据导出 helper。
 - **协议与传输接面：** `createAcpServer`、`serveAcpStdio`、`serveAcpHttp`、`serveA2aHttp`、`serveAgUiHttp`、以及 `createRuntimeMcpServer` / `serveRuntimeMcpOverStdio`。
 - **受治理的工作区运行时：** 由 YAML 持有的路由、并发、维护、MCP 策略、runtime governance bundles，以及针对敏感 memory 或写类 MCP 副作用的默认审批门槛。
 
-`deepagents-acp` 已不应该只藏在规划文档里。它已经是当前公开产品叙事的一部分：`agent-harness` 正在朝一个可被外部客户端直接接入的标准 runtime boundary 演进，同时继续把持久化、恢复、审批和 operator control 保持为 harness 自有职责。
+如果你的产品需要对接外部客户端，也可以从这里理解边界：`deepagents-acp` 是主要的外部协议方向，而持久化、恢复、审批和运行控制仍由 `agent-harness` 负责。
 
 ## 我们解决什么问题
 
@@ -190,6 +190,7 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 
 - `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`
@@ -198,7 +199,7 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 - `docs/long-term-memory.md`
 - `docs/memory-policy-reference.md`
 
-维护者笔记和产品边界讨论仍然保留在仓库里，但不会再作为公开阅读路径的一部分放在主要入口里。
+仓库里仍然保留了部分设计说明和边界讨论，但日常使用时不需要先读这些内容。
 
 当外部工具需要标准运行时边界时，`deepagents-acp` 是必须遵循的外部协议方向。`agent-harness` 应在该边界上严格契合 `deepagents-acp` 语义，同时继续把运行时生命周期、持久化、恢复与治理保留在 harness 内部。
 
@@ -233,13 +234,13 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 
 ## 先卖哪三类场景
 
-产品叙事应该保持场景化，不要再漂回“通用 multi-agent runtime”。
+如果你在评估落地场景，可以先从下面三类最直接的用法理解它。
 
 - 企业内部 agent 运行时：审批、重启恢复、operator 证据链，以及由策略持有的 MCP 访问控制。
 - 代码现代化运行时：长链路 coding flow、审批检查点、可恢复 runs，以及可导出的运行证据包。
 - 协议桥接运行时：ACP、A2A、AG-UI 与 runtime MCP 共用一套稳定控制面，而不是每个对外接面各写一层胶水。
 
-现在推荐的 runtime 治理默认值大致是：
+一套常见的 runtime 治理默认值大致如下：
 
 ```yaml
 governance:
@@ -259,7 +260,7 @@ governance:
 - 你希望用一个 workspace 形态的装配模型取代每个应用各写一套启动和运行时胶水
 - 你想把 backend 的执行语义留在上游，同时把产品契约稳定下来
 
-下面这些场景就不应该优先用它：
+下面这些场景通常不需要优先选择它：
 
 - 你只需要一次短生命周期的 agent 调用，不需要审批、持久化或运维控制面
 - 你要的是工作流搭建器或低代码自动化画布
@@ -434,7 +435,7 @@ const result = await request(runtime, {
 - `invocation.inputs`：结构化运行时输入
 - `invocation.attachments`：当前后端可解释的类附件负载
 
-可选地，runtime memory 还可以在 SQLite canonical durable memory 之上叠加 `mem0` 语义召回增强，用于更强的长期知识命中，而不改变正式知识记录的 contract。
+可选地，runtime memory 还可以在 SQLite 持久化记忆之上叠加 `mem0` 语义召回增强，用于提升长期知识命中能力，同时不改变正式知识记录的接口。
 
 ### 写入与召回 durable runtime memory
 
@@ -882,7 +883,7 @@ spec:
     middleware: []
 ```
 
-后端相关选项优先直接写在 `spec.config` 中沿用上游概念。公开能力边界以开发者文档与 API 参考为准，不依赖维护者内部对比笔记。
+后端相关选项优先直接写在 `spec.config` 中沿用上游概念。日常接入时，以开发者文档与 API 参考为准即可。
 
 ## 设计说明
 
@@ -948,13 +949,13 @@ Inspection 辅助工具：
 ACP transport 说明：
 
 - `serveAcpStdio(runtime)` 提供基于 stdio 的 newline-delimited JSON-RPC，适合本地 IDE、CLI 或子进程客户端。
-- `serveAcpHttp(runtime)` 提供基于 HTTP 的 JSON-RPC 与 SSE runtime events，适合远程 operator surface 或独立控制面接入。
-- `serveA2aHttp(runtime)` 提供 A2A HTTP JSON-RPC bridge 与 agent card discovery，同时兼容 `message/send` 这类旧方法，以及 `SendMessage`、`GetTask`、`ListTasks`、`CancelTask`、`SubscribeToTask` 这类更新的方法别名，并统一映射到现有 session/request runtime surface。
+- `serveAcpHttp(runtime)` 提供基于 HTTP 的 JSON-RPC 与 SSE runtime events，适合远程界面或独立控制面接入。
+- `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 打包给 operator tooling，而不必直接访问 persistence 内部实现。
+- `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 元数据，让治理快照能解释为什么某个远端工具被视为高风险。
-- `runtime/default.observability.tracing` 现在可描述 OTLP endpoint 和 propagation mode 这类 exporter 元数据，使冻结的 runtime snapshot 在保留 trace correlation 的同时，也能保留对 operator 有意义的导出上下文，而不暴露 backend 私有 span 细节。
-- `agent-harness runtime overview`、`agent-harness runtime health`、`agent-harness runtime approvals list|watch` 与 `agent-harness runtime runs list|tail` 提供了一层轻量 operator CLI，可直接查看 runtime health、queue pressure、governance risk、审批队列和运行状态。
+- `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/api.d.ts

@@ -182,7 +182,7 @@ export declare function cancelRun(runtime: AgentHarnessRuntime, options: CancelO
     requestId?: string;
 }): Promise<PublicRunResult>;
 export declare function stop(runtime: AgentHarnessRuntime): Promise<void>;
-export declare function createToolMcpServer(runtime: AgentHarnessRuntime, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
-export declare function serveToolsOverStdio(runtime: AgentHarnessRuntime, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
-export declare function createRuntimeMcpServer(runtime: AgentHarnessRuntime, options?: RuntimeMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
-export declare function serveRuntimeMcpOverStdio(runtime: AgentHarnessRuntime, options?: RuntimeMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
+export declare function createToolMcpServer(runtime: AgentHarnessRuntime, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp").McpServer>;
+export declare function serveToolsOverStdio(runtime: AgentHarnessRuntime, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp").McpServer>;
+export declare function createRuntimeMcpServer(runtime: AgentHarnessRuntime, options?: RuntimeMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp").McpServer>;
+export declare function serveRuntimeMcpOverStdio(runtime: AgentHarnessRuntime, options?: RuntimeMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp").McpServer>;

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.199";
+export declare const AGENT_HARNESS_VERSION = "0.0.201";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.199";
+export const AGENT_HARNESS_VERSION = "0.0.201";

package/dist/runtime/harness.d.ts

@@ -115,10 +115,10 @@ export declare class AgentHarnessRuntime {
     deleteSession(sessionId: string): Promise<boolean>;
     deleteThread(threadId: string): Promise<boolean>;
     deleteThreadLegacy(threadId: string): Promise<boolean>;
-    createToolMcpServer(options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
-    serveToolsOverStdio(options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
-    createRuntimeMcpServer(options?: RuntimeMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
-    serveRuntimeMcpOverStdio(options?: RuntimeMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
+    createToolMcpServer(options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp").McpServer>;
+    serveToolsOverStdio(options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp").McpServer>;
+    createRuntimeMcpServer(options?: RuntimeMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp").McpServer>;
+    serveRuntimeMcpOverStdio(options?: RuntimeMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp").McpServer>;
     routeAgent(input: MessageContent, options?: {
         threadId?: string;
     }): Promise<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.200",
+  "version": "0.0.202",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",
@@ -75,7 +75,7 @@
     "release:publish": "npm publish --access public --registry https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@types/node": "^24.6.0",
+    "@types/node": "^25.5.2",
     "typescript": "^5.9.3",
     "vite": "^7.3.2",
     "vitest": "^3.2.4"