@botbotgo/agent-harness 0.0.134 → 0.0.135

package/README.md

@@ -17,6 +17,10 @@
   <strong>The application runtime for multi-agent products with approvals, recovery, and operator control built in.</strong>
 </p>
 
+<p align="center">
+  <strong>Turn one agent workspace into one operable product runtime.</strong>
+</p>
+
 <p align="center">
   <a href="https://botbotgo.github.io/agent-harness/">Product website</a>
   (static page in <code>docs/</code>, publish with GitHub Pages; EN / 中文 toggle)
@@ -31,6 +35,17 @@
 
 ## What Problem We Solve
 
+In one line: `agent-harness` takes the runtime work that appears after the demo and makes it part of the product runtime from day one.
+
+If your team already has agents, prompts, tools, and workflows, the missing layer is usually not more execution. It is the runtime that makes those pieces operable as software.
+
+What you get on day one:
+
+- a runtime that keeps `runs`, `threads`, `approvals`, and `events` as inspectable product records
+- a recovery path that survives interruption, restart, and operator decisions
+- one workspace-shaped assembly model instead of app-specific runtime glue
+- one stable runtime contract even when execution backends change underneath
+
 AI makes it much easier to generate agent logic, tool calls, and workflow code. The hard part moves to operations.
 
 Once the demo works, the real software problem changes shape:
@@ -50,6 +65,12 @@ Teams still need answers to the runtime questions that appear after that shift:
 
 `agent-harness` solves that layer. It keeps agent execution upstream while making the application runtime operable, recoverable, and governable.
 
+That means the product story becomes easier to explain:
+
+- you bring the workspace, agents, tools, and prompts
+- `agent-harness` brings persisted `runs`, `threads`, `approvals`, `events`, recovery, and operator visibility
+- your application gets one stable runtime contract instead of backend-specific runtime plumbing
+
 Concretely, that means:
 
 - a product-facing approval and operator surface instead of backend-specific middleware state
@@ -152,6 +173,21 @@ Real products need a runtime that can answer harder questions:
 - It lets YAML own assembly and operating policy while code keeps a tiny surface
 - It goes deep on runtime concerns that upstream libraries do not fully productize
 
+## When To Use It
+
+Use `agent-harness` when:
+
+- you already know your product needs agents, tools, prompts, or MCP access, but the missing layer is runtime operations
+- you need approvals, restart recovery, queueing, or inspectable run records as part of the shipped product
+- you want one workspace-shaped assembly model instead of hand-written runtime bootstrapping in every app
+- you want to keep backend execution semantics upstream while holding the product contract stable
+
+Do not reach for it when:
+
+- you only need a single short-lived agent call with no approvals, no persistence, and no operational control surface
+- you are looking for a workflow builder or low-code automation canvas
+- you want to replace LangChain v1 or DeepAgents execution semantics rather than operate around them
+
 ## Quick Start
 
 Install:
@@ -205,6 +241,17 @@ try {
 }
 ```
 
+Three-minute mental model:
+
+1. Point `createAgentHarness(...)` at a workspace root.
+2. Call `run(runtime, { ... })` to execute one request.
+3. Inspect persisted runtime records instead of treating the final answer as the only product artifact.
+
+This is the shortest product pitch:
+
+- your team builds the agent app
+- `agent-harness` makes that app operable
+
 If you want the shortest possible mental model:
 
 - one workspace becomes one runtime
@@ -429,6 +476,13 @@ Core workspace files:
 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.
 
+Default wiring guidance:
+
+- prefer agent-local wiring for workspace-owned function tools
+- keep `config/catalogs/tools.yaml` for reusable shared tools
+- keep `config/catalogs/mcp.yaml` for shared MCP server definitions
+- let agents select MCP tools and apply per-usage MCP overrides where needed
+
 There are three main configuration layers:
 
 - runtime policy in `config/runtime/workspace.yaml`
@@ -581,10 +635,14 @@ Use this file for reusable tool objects.
 
 Built-in tool families include function tools, backend tools, MCP tools, bundles, and provider-native tools. Provider-native tools are declared in YAML and resolved directly to upstream factories.
 
+For workspace-owned function tools, prefer agent-side wiring first. Keep `config/catalogs/tools.yaml` for reusable shared tool objects rather than making it the default path for every local tool.
+
 ### `config/catalogs/mcp.yaml`
 
 Use this file for named MCP server presets.
 
+MCP servers are usually heavier shared resources than local function tools. Keep shared MCP connection details here, then let each agent choose the remote tools it wants and apply per-usage overrides at the agent usage point.
+
 Example:
 
 ```yaml

package/README.zh.md

@@ -17,6 +17,10 @@
   <strong>面向多 agent 产品的应用运行时：内建审批、恢复与运维控制，而不只是执行。</strong>
 </p>
 
+<p align="center">
+  <strong>把一个 agent 工作区直接变成一套可运行的产品级 runtime。</strong>
+</p>
+
 <p align="center">
   <a href="https://botbotgo.github.io/agent-harness/">产品网站</a>
   （<code>docs/</code> 中的静态页，通过 GitHub Pages 发布；支持中英文切换）
@@ -31,6 +35,17 @@
 
 ## 我们解决什么问题
 
+一句话概括：`agent-harness` 把 demo 之后才暴露出来的运行时问题，提前收进产品 runtime 本身。
+
+如果团队已经有 agents、prompts、tools 和 workflows，真正缺的通常不是再来一层执行，而是把这些东西变成“可运维的软件”的运行时层。
+
+第一天就能直接拿到的东西：
+
+- 把 `runs`、`threads`、`approvals`、`events` 作为可查询产品记录保存下来的 runtime
+- 能跨中断、重启和人工决策继续推进的恢复路径
+- 一个工作区形态的装配模型，而不是每个应用各写一套运行时胶水
+- 即使底层 execution backend 变化，也尽量保持稳定的 runtime 契约
+
 AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正变难的是运行时运维。
 
 当 demo 跑起来之后，真正的软件问题会换一种形状出现：
@@ -50,6 +65,12 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正变
 
 `agent-harness` 解决的就是这一层。它把 agent 执行留在上游，同时把应用运行时做成可运维、可恢复、可治理的系统。
 
+换成更直接的产品语言，就是：
+
+- 你负责工作区、agents、tools 和 prompts
+- `agent-harness` 负责持久化 `runs`、`threads`、`approvals`、`events`、恢复能力与运维可见性
+- 你的应用拿到的是一个稳定的 runtime 契约，而不是一堆 backend 专属的运行时胶水代码
+
 具体来说，就是把这些能力沉到运行时里：
 
 - 面向产品的审批与运维控制面，而不是 backend 专属的中间件状态
@@ -152,6 +173,21 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正变
 - 复杂装配与运行策略交给 YAML，代码面保持极小
 - 在上游库未充分产品化的运行时问题上做深做透
 
+## 什么时候该用
+
+下面这些场景适合用 `agent-harness`：
+
+- 你已经确定产品需要 agents、tools、prompts 或 MCP，但真正缺的是运行时运维层
+- 你需要把审批、重启恢复、排队调度或可查询运行记录一起作为产品能力交付出去
+- 你希望用一个 workspace 形态的装配模型取代每个应用各写一套启动和运行时胶水
+- 你想把 backend 的执行语义留在上游，同时把产品契约稳定下来
+
+下面这些场景就不应该优先用它：
+
+- 你只需要一次短生命周期的 agent 调用，不需要审批、持久化或运维控制面
+- 你要的是工作流搭建器或低代码自动化画布
+- 你想替代 LangChain v1 或 DeepAgents 的执行语义，而不是围绕它们做运行时
+
 ## 快速开始
 
 安装：
@@ -205,6 +241,17 @@ try {
 }
 ```
 
+三分钟心智模型：
+
+1. 用 `createAgentHarness(...)` 指向一个 workspace root。
+2. 用 `run(runtime, { ... })` 执行一次请求。
+3. 把持久化的运行时记录当成产品资产，而不是只盯着最终回答。
+
+如果再压缩成最短产品表述，就是：
+
+- 你的团队负责构建 agent app
+- `agent-harness` 负责让这个 app 可运维
+
 最短心智模型：
 
 - 一个工作区对应一个运行时

package/dist/contracts/workspace.d.ts

@@ -8,6 +8,8 @@ export type ParsedAgentObject = {
     modelRef: string;
     runRoot?: string;
     toolRefs: string[];
+    toolBindings?: ParsedAgentToolBinding[];
+    inlineTools?: ParsedToolObject[];
     mcpServers?: Array<Record<string, unknown>>;
     skillPathRefs: string[];
     memorySources: string[];
@@ -17,6 +19,10 @@ export type ParsedAgentObject = {
     deepAgentConfig?: Record<string, unknown>;
     sourcePath: string;
 };
+export type ParsedAgentToolBinding = {
+    ref: string;
+    overrides?: Record<string, unknown>;
+};
 export type WorkspaceObject = {
     id: string;
     kind: string;
@@ -72,7 +78,9 @@ export type ParsedToolObject = {
     description: string;
     implementationName?: string;
     config?: Record<string, unknown>;
+    subprocess?: boolean;
     inputSchemaRef?: string;
+    embeddingModelRef?: string;
     backendOperation?: string;
     mcpRef?: string;
     bundleRefs: string[];
@@ -116,7 +124,9 @@ export type CompiledTool = {
     name: string;
     description: string;
     config?: Record<string, unknown>;
+    subprocess?: boolean;
     inputSchemaRef?: string;
+    embeddingModelRef?: string;
     backendOperation?: string;
     mcpRef?: string;
     bundleRefs: string[];

package/dist/extensions.js

@@ -118,7 +118,9 @@ registerToolKind({
                 name: tool.name,
                 description: tool.description,
                 config: tool.config,
+                subprocess: tool.subprocess,
                 inputSchemaRef: tool.inputSchemaRef,
+                embeddingModelRef: tool.embeddingModelRef,
                 bundleRefs: [],
                 hitl: tool.hitl
                     ? {
@@ -150,7 +152,9 @@ registerToolKind({
                 name: tool.name,
                 description: tool.description,
                 config: tool.config,
+                subprocess: tool.subprocess,
                 inputSchemaRef: tool.inputSchemaRef,
+                embeddingModelRef: tool.embeddingModelRef,
                 backendOperation: tool.backendOperation,
                 bundleRefs: [],
                 hitl: tool.hitl
@@ -183,7 +187,9 @@ registerToolKind({
                 name: tool.name,
                 description: tool.description,
                 config: tool.config,
+                subprocess: tool.subprocess,
                 inputSchemaRef: tool.inputSchemaRef,
+                embeddingModelRef: tool.embeddingModelRef,
                 mcpRef: tool.mcpRef,
                 bundleRefs: [],
                 hitl: tool.hitl
@@ -222,7 +228,9 @@ registerToolKind({
                 name: tool.name,
                 description: tool.description,
                 config: tool.config,
+                subprocess: tool.subprocess,
                 inputSchemaRef: tool.inputSchemaRef,
+                embeddingModelRef: tool.embeddingModelRef,
                 bundleRefs: [],
                 hitl: tool.hitl
                     ? {

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.133";
+export declare const AGENT_HARNESS_VERSION = "0.0.134";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.133";
+export const AGENT_HARNESS_VERSION = "0.0.134";

package/dist/resource/mcp-tool-support.d.ts

@@ -17,5 +17,9 @@ export type McpToolDescriptor = {
 };
 export declare function readMcpServerConfig(workspace: WorkspaceBundle, tool: WorkspaceBundle["tools"] extends Map<any, infer T> ? T : never): McpServerConfig | null;
 export declare function getOrCreateMcpClient(config: McpServerConfig): Promise<Client>;
+export declare function closeMcpClientsForWorkspace(workspace: WorkspaceBundle): Promise<void>;
+export declare function __resetMcpClientCacheForTests(): void;
+export declare function __setMcpClientCacheEntryForTests(config: McpServerConfig, clientPromise: Promise<Client>): void;
+export declare function __setMcpClientLoaderForTests(loader: (config: McpServerConfig) => Promise<Client>): void;
 export declare function listRemoteMcpTools(config: McpServerConfig): Promise<McpToolDescriptor[]>;
 export declare function createMcpToolResolver(workspace: WorkspaceBundle): NonNullable<RuntimeAdapterOptions["toolResolver"]>;

package/dist/resource/mcp-tool-support.js

@@ -6,6 +6,7 @@ import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/webso
 import { AGENT_HARNESS_VERSION } from "../package-version.js";
 import { createRuntimeEnv } from "../runtime/support/runtime-env.js";
 const mcpClientCache = new Map();
+let mcpClientLoader = createConnectedMcpClient;
 function readStringRecord(value) {
     if (typeof value !== "object" || !value) {
         return undefined;
@@ -73,46 +74,124 @@ function createMcpCacheKey(config) {
         headers: config.headers ?? {},
     });
 }
+async function createConnectedMcpClient(config) {
+    const client = new Client({
+        name: "agent-harness",
+        version: AGENT_HARNESS_VERSION,
+    });
+    const headers = {
+        ...(config.headers ?? {}),
+        ...(config.token ? { Authorization: `Bearer ${config.token}` } : {}),
+    };
+    const transport = config.transport === "http"
+        ? new StreamableHTTPClientTransport(new URL(config.url ?? ""), {
+            requestInit: Object.keys(headers).length > 0 ? { headers } : undefined,
+        })
+        : config.transport === "sse"
+            ? new SSEClientTransport(new URL(config.url ?? ""), {
+                requestInit: Object.keys(headers).length > 0 ? { headers } : undefined,
+            })
+            : config.transport === "websocket"
+                ? new WebSocketClientTransport(new URL(config.url ?? ""))
+                : new StdioClientTransport({
+                    command: config.command ?? "",
+                    args: config.args,
+                    env: createRuntimeEnv(config.env),
+                    cwd: config.cwd,
+                });
+    await client.connect(transport);
+    return client;
+}
+function isRecoverableMcpError(error) {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+    const message = typeof error.message === "string"
+        ? (error.message).toLowerCase()
+        : "";
+    const code = typeof error.code === "string"
+        ? (error.code).toLowerCase()
+        : "";
+    return [
+        "connection closed",
+        "transport closed",
+        "socket closed",
+        "stream closed",
+        "network socket disconnected",
+    ].some((pattern) => message.includes(pattern))
+        || ["econnreset", "epipe", "ehostunreach", "ecancelled"].includes(code);
+}
+async function closeCachedMcpClient(cacheKey) {
+    const cached = mcpClientCache.get(cacheKey);
+    mcpClientCache.delete(cacheKey);
+    if (!cached) {
+        return;
+    }
+    try {
+        const client = await cached;
+        await client.close();
+    }
+    catch {
+        // Ignore teardown failures for clients that never connected successfully.
+    }
+}
+async function invalidateMcpClient(config) {
+    await closeCachedMcpClient(createMcpCacheKey(config));
+}
+async function withRecoveredMcpClient(config, operation) {
+    const client = await getOrCreateMcpClient(config);
+    try {
+        return await operation(client);
+    }
+    catch (error) {
+        if (!isRecoverableMcpError(error)) {
+            throw error;
+        }
+        await invalidateMcpClient(config);
+        return operation(await getOrCreateMcpClient(config));
+    }
+}
 export async function getOrCreateMcpClient(config) {
     const cacheKey = createMcpCacheKey(config);
     const cached = mcpClientCache.get(cacheKey);
     if (cached) {
         return cached;
     }
-    const loading = (async () => {
-        const client = new Client({
-            name: "agent-harness",
-            version: AGENT_HARNESS_VERSION,
-        });
-        const headers = {
-            ...(config.headers ?? {}),
-            ...(config.token ? { Authorization: `Bearer ${config.token}` } : {}),
-        };
-        const transport = config.transport === "http"
-            ? new StreamableHTTPClientTransport(new URL(config.url ?? ""), {
-                requestInit: Object.keys(headers).length > 0 ? { headers } : undefined,
-            })
-            : config.transport === "sse"
-                ? new SSEClientTransport(new URL(config.url ?? ""), {
-                    requestInit: Object.keys(headers).length > 0 ? { headers } : undefined,
-                })
-                : config.transport === "websocket"
-                    ? new WebSocketClientTransport(new URL(config.url ?? ""))
-                    : new StdioClientTransport({
-                        command: config.command ?? "",
-                        args: config.args,
-                        env: createRuntimeEnv(config.env),
-                        cwd: config.cwd,
-                    });
-        await client.connect(transport);
-        return client;
-    })();
+    const loading = mcpClientLoader(config).catch((error) => {
+        if (mcpClientCache.get(cacheKey) === loading) {
+            mcpClientCache.delete(cacheKey);
+        }
+        throw error;
+    });
     mcpClientCache.set(cacheKey, loading);
     return loading;
 }
+export async function closeMcpClientsForWorkspace(workspace) {
+    const cacheKeys = new Set();
+    for (const tool of workspace.tools.values()) {
+        if (tool.type !== "mcp") {
+            continue;
+        }
+        const config = readMcpServerConfig(workspace, tool);
+        if (!config) {
+            continue;
+        }
+        cacheKeys.add(createMcpCacheKey(config));
+    }
+    await Promise.all(Array.from(cacheKeys, (cacheKey) => closeCachedMcpClient(cacheKey)));
+}
+export function __resetMcpClientCacheForTests() {
+    mcpClientCache.clear();
+    mcpClientLoader = createConnectedMcpClient;
+}
+export function __setMcpClientCacheEntryForTests(config, clientPromise) {
+    mcpClientCache.set(createMcpCacheKey(config), clientPromise);
+}
+export function __setMcpClientLoaderForTests(loader) {
+    mcpClientLoader = loader;
+}
 async function getRemoteMcpToolDescriptor(config, remoteToolName) {
-    const client = await getOrCreateMcpClient(config);
-    const result = await client.listTools();
+    const result = await withRecoveredMcpClient(config, (client) => client.listTools());
     const tool = result.tools.find((item) => typeof item.name === "string" && item.name === remoteToolName);
     if (!tool || typeof tool.name !== "string") {
         return null;
@@ -124,8 +203,7 @@ async function getRemoteMcpToolDescriptor(config, remoteToolName) {
     };
 }
 export async function listRemoteMcpTools(config) {
-    const client = await getOrCreateMcpClient(config);
-    const result = await client.listTools();
+    const result = await withRecoveredMcpClient(config, (client) => client.listTools());
     return result.tools
         .filter((tool) => typeof tool.name === "string")
         .map((tool) => ({
@@ -155,11 +233,10 @@ export function createMcpToolResolver(workspace) {
                 description: tool.description,
                 inputSchemaPromise: descriptorPromise.then((descriptor) => descriptor?.inputSchema),
                 async invoke(input) {
-                    const client = await getOrCreateMcpClient(serverConfig);
-                    const result = await client.callTool({
+                    const result = await withRecoveredMcpClient(serverConfig, (client) => client.callTool({
                         name: remoteToolName,
                         arguments: typeof input === "object" && input !== null ? input : {},
-                    });
+                    }));
                     const textParts = Array.isArray(result.content)
                         ? result.content
                             .filter((item) => typeof item === "object" && item !== null && "type" in item)