@botbotgo/agent-harness 0.0.134 → 0.0.136

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
@@ -376,13 +423,12 @@ kind: Agent
 metadata:
   name: orchestra
 spec:
-  execution:
-    backend: deepagent
-    modelRef: model/default
-    mcpServers:
-      - name: browser
-        command: node
-        args: ["./mcp-browser-server.mjs"]
+  backend: deepagent
+  modelRef: model/default
+  mcpServers:
+    - name: browser
+      command: node
+      args: ["./mcp-browser-server.mjs"]
 ```
 
 Expose harness tools as an MCP server:
@@ -429,6 +475,14 @@ 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:
+
+- let workspace startup scan local and attached `resources` packages into one registry
+- let agents whitelist tools and skills by name
+- 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.
 
+Keep `config/catalogs/tools.yaml` for reusable shared tool objects rather than making it the default path for every local tool. Workspace-owned function tools should normally be discovered from `resources/tools/` and then whitelisted by name in each agent.
+
 ### `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
@@ -602,12 +660,12 @@ spec:
 
 ### `config/agents/*.yaml`
 
-Agents always use `kind: Agent` plus `spec.execution.backend`.
+Agents always use `kind: Agent` plus `spec.backend`.
 
-Use two nested sections:
+Use two sections:
 
 - `spec.runtime` for harness-owned runtime placement such as `spec.runtime.runRoot`
-- `spec.execution` for upstream execution semantics and adapter-facing config
+- top-level `spec` fields for upstream execution semantics and adapter-facing config
 
 Example direct host:
 
@@ -619,26 +677,28 @@ metadata:
 spec:
   runtime:
     runRoot: ./.agent
-  execution:
-    backend: langchain-v1
-    modelRef: model/default
-    tools: []
-    skills: []
-    memory: []
-    subagents: []
-    mcpServers: []
-    config:
-      checkpointer:
-        ref: checkpointer/default
-      store:
-        ref: store/default
-      interruptOn: {}
-      filesystem:
-        rootDir: .
-        virtualMode: true
-        maxFileSizeMb: 10
-      middleware: []
-      systemPrompt: Answer simple requests directly.
+  backend: langchain-v1
+  modelRef: model/default
+  tools:
+    - write_file:
+        subprocess: true
+  skills:
+    - code-review
+  memory: []
+  subagents: []
+  mcpServers: []
+  config:
+    checkpointer:
+      ref: checkpointer/default
+    store:
+      ref: store/default
+    interruptOn: {}
+    filesystem:
+      rootDir: .
+      virtualMode: true
+      maxFileSizeMb: 10
+    middleware: []
+    systemPrompt: Answer simple requests directly.
 ```
 
 Example orchestra host:
@@ -651,27 +711,28 @@ metadata:
 spec:
   runtime:
     runRoot: ./.agent
-  execution:
-    backend: deepagent
-    modelRef: model/default
-    memory:
-      - path: config/agent-context.md
-    tools: []
-    skills: []
-    subagents: []
-    mcpServers: []
-    config:
-      store:
-        ref: store/default
-      checkpointer:
-        ref: checkpointer/default
-      backend:
-        ref: backend/default
-      interruptOn: {}
-      middleware: []
+  backend: deepagent
+  modelRef: model/default
+  memory:
+    - path: config/agent-context.md
+  tools:
+    - stock_snapshot
+  skills:
+    - stock-research
+  subagents: []
+  mcpServers: []
+  config:
+    store:
+      ref: store/default
+    checkpointer:
+      ref: checkpointer/default
+    backend:
+      ref: backend/default
+    interruptOn: {}
+    middleware: []
 ```
 
-For backend-specific options, prefer the upstream concept directly inside `spec.execution.config`. Upstream feature coverage is tracked in [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md).
+For backend-specific options, prefer the upstream concept directly inside `spec.config`. Upstream feature coverage is tracked in [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md).
 
 ## Design Notes
 

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 可运维
+
 最短心智模型：
 
 - 一个工作区对应一个运行时
@@ -376,13 +423,12 @@ kind: Agent
 metadata:
   name: orchestra
 spec:
-  execution:
-    backend: deepagent
-    modelRef: model/default
-    mcpServers:
-      - name: browser
-        command: node
-        args: ["./mcp-browser-server.mjs"]
+  backend: deepagent
+  modelRef: model/default
+  mcpServers:
+    - name: browser
+      command: node
+      args: ["./mcp-browser-server.mjs"]
 ```
 
 将 harness 工具作为 MCP 服务对外暴露：
@@ -431,6 +477,8 @@ await stop(runtime);
 
 主要有三层配置：
 
+- 先由 workspace 启动时扫描本地和附加的 `resources` 包，建立统一 registry
+- agent 再按名字白名单选择 tools 与 skills
 - `config/runtime/workspace.yaml` 中的运行时策略
 - `config/catalogs/*.yaml` 中的可复用对象目录
 - `config/agents/*.yaml` 中的 agent 装配
@@ -578,6 +626,8 @@ spec:
 
 内置工具族包括函数工具、后端工具、MCP 工具、bundle 与原生 provider 工具。原生 provider 工具在 YAML 中声明并直接解析到上游工厂。
 
+`config/catalogs/tools.yaml` 更适合放可复用共享工具对象，而不应成为每个本地工具的默认入口。工作区自有函数工具通常应从 `resources/tools/` 发现，再由各 agent 按名字白名单启用。
+
 ### `config/catalogs/mcp.yaml`
 
 命名 MCP 服务预设。
@@ -599,12 +649,12 @@ spec:
 
 ### `config/agents/*.yaml`
 
-Agent 始终使用 `kind: Agent` 以及 `spec.execution.backend`。
+Agent 始终使用 `kind: Agent` 以及 `spec.backend`。
 
-两个嵌套区块：
+两个区块：
 
 - `spec.runtime`：harness 侧运行时放置，例如 `spec.runtime.runRoot`
-- `spec.execution`：上游执行语义与面向适配器的配置
+- `spec` 顶层字段：上游执行语义与面向适配器的配置
 
 direct 主机示例：
 
@@ -616,26 +666,28 @@ metadata:
 spec:
   runtime:
     runRoot: ./.agent
-  execution:
-    backend: langchain-v1
-    modelRef: model/default
-    tools: []
-    skills: []
-    memory: []
-    subagents: []
-    mcpServers: []
-    config:
-      checkpointer:
-        ref: checkpointer/default
-      store:
-        ref: store/default
-      interruptOn: {}
-      filesystem:
-        rootDir: .
-        virtualMode: true
-        maxFileSizeMb: 10
-      middleware: []
-      systemPrompt: Answer simple requests directly.
+  backend: langchain-v1
+  modelRef: model/default
+  tools:
+    - write_file:
+        subprocess: true
+  skills:
+    - code-review
+  memory: []
+  subagents: []
+  mcpServers: []
+  config:
+    checkpointer:
+      ref: checkpointer/default
+    store:
+      ref: store/default
+    interruptOn: {}
+    filesystem:
+      rootDir: .
+      virtualMode: true
+      maxFileSizeMb: 10
+    middleware: []
+    systemPrompt: Answer simple requests directly.
 ```
 
 orchestra 主机示例：
@@ -648,27 +700,28 @@ metadata:
 spec:
   runtime:
     runRoot: ./.agent
-  execution:
-    backend: deepagent
-    modelRef: model/default
-    memory:
-      - path: config/agent-context.md
-    tools: []
-    skills: []
-    subagents: []
-    mcpServers: []
-    config:
-      store:
-        ref: store/default
-      checkpointer:
-        ref: checkpointer/default
-      backend:
-        ref: backend/default
-      interruptOn: {}
-      middleware: []
+  backend: deepagent
+  modelRef: model/default
+  memory:
+    - path: config/agent-context.md
+  tools:
+    - stock_snapshot
+  skills:
+    - stock-research
+  subagents: []
+  mcpServers: []
+  config:
+    store:
+      ref: store/default
+    checkpointer:
+      ref: checkpointer/default
+    backend:
+      ref: backend/default
+    interruptOn: {}
+    middleware: []
 ```
 
-后端相关选项优先直接写在 `spec.execution.config` 中沿用上游概念。上游能力覆盖见 [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md)。
+后端相关选项优先直接写在 `spec.config` 中沿用上游概念。上游能力覆盖见 [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md)。
 
 ## 设计说明
 

package/dist/config/agents/direct.yaml

@@ -1,7 +1,7 @@
 # agent-harness feature: schema version for this declarative config object.
 apiVersion: agent-harness/v1alpha1
 # agent-harness feature: object type discriminator.
-# Prefer the generic `Agent` form and select the concrete execution backend under `spec.execution`.
+# Prefer the generic `Agent` form and place execution fields directly under `spec`.
 kind: Agent
 metadata:
   # agent-harness feature: stable object id used for refs and host-agent selection.
@@ -19,74 +19,73 @@ spec:
   # =====================
   # Runtime Agent Features
   # =====================
-  execution:
-    # Current backend adapter for this host profile.
-    backend: langchain-v1
-    # Upstream execution feature: model ref for the underlying LLM used by the direct-response agent.
-    # This should point at a cheap, fast, general-purpose chat model, because `direct` is intended
-    # to be the low-latency path for simple requests.
-    modelRef: model/default
-    # Upstream execution feature: direct host starts with no attached explicit tools by default.
-    tools: []
-    # Upstream execution feature: direct host starts with no attached local skill packages by default.
-    skills: []
-    # Upstream execution feature: direct host does not bootstrap project memory by default.
-    memory: []
-    # Upstream execution feature: direct host does not predeclare subagents by default.
-    subagents: []
-    # Upstream execution feature: direct host does not attach MCP servers by default.
-    mcpServers: []
-    # Runtime execution feature: checkpointer config passed into the selected backend adapter.
-    # Even the lightweight direct path can benefit from resumable state during interactive use.
-    # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`, `SqliteSaver`.
-    # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
-    checkpointer:
-      ref: checkpointer/sqlite
-    # Upstream execution feature: LangGraph store available to middleware and runtime context hooks.
-    # The default direct host keeps this enabled so middleware can use the same durable store surface as other hosts.
-    store:
-      ref: store/default
-    # Upstream execution feature: no declarative HITL tool routing by default.
-    interruptOn: {}
-    # Upstream execution feature: filesystem middleware settings for LangChain v1 agents.
-    # This only becomes active when `middleware` includes `{ kind: filesystem }`, or when
-    # automatic upstream middleware such as skills or memory need a filesystem backend.
-    # Keep the default root inside the workspace so file-aware middleware stays bounded.
-    filesystem:
-      rootDir: .
-      virtualMode: true
-      maxFileSizeMb: 10
-    # Upstream execution feature: no extra declarative middleware beyond the runtime's automatic injections.
-    # Common upstream middleware kinds that this harness can compile directly from YAML:
-    # - `filesystem`
-    # - `patchToolCalls`
-    # - `summarization`
-    # - `dynamicSystemPrompt`
-    # - `humanInTheLoop`
-    # - `todoList`
-    # - `pii`, `piiRedaction`
-    #
-    # Keep the default empty so the lightweight direct host stays minimal.
-    middleware: []
-    # Upstream execution feature: system prompt for the lightweight direct-response host.
-    # This prompt should keep the agent focused on:
-    # - answering simple requests in one turn
-    # - staying lightweight instead of planning or orchestrating
-    # - avoiding delegation-heavy decomposition unless the caller explicitly switches agents
-    #
-    # The direct host is intentionally narrower than the orchestra host:
-    # - `direct` is optimized for latency and straightforward completion
-    # - `orchestra` is optimized for multi-step work, tools, and delegation
-    #
-    # Keep this prompt biased toward concise, self-contained answers. If richer routing policy is
-    # needed for choosing between host agents, configure that separately via `Runtime.spec.routing`
-    # rather than overloading the direct host prompt with classifier behavior.
-    systemPrompt: |-
-      You are the direct agent.
+  # Current backend adapter for this host profile.
+  backend: langchain-v1
+  # Upstream execution feature: model ref for the underlying LLM used by the direct-response agent.
+  # This should point at a cheap, fast, general-purpose chat model, because `direct` is intended
+  # to be the low-latency path for simple requests.
+  modelRef: model/default
+  # Upstream execution feature: direct host starts with no attached explicit tools by default.
+  tools: []
+  # Upstream execution feature: direct host starts with no attached local skill packages by default.
+  skills: []
+  # Upstream execution feature: direct host does not bootstrap project memory by default.
+  memory: []
+  # Upstream execution feature: direct host does not predeclare subagents by default.
+  subagents: []
+  # Upstream execution feature: direct host does not attach MCP servers by default.
+  mcpServers: []
+  # Runtime execution feature: checkpointer config passed into the selected backend adapter.
+  # Even the lightweight direct path can benefit from resumable state during interactive use.
+  # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`, `SqliteSaver`.
+  # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
+  checkpointer:
+    ref: checkpointer/sqlite
+  # Upstream execution feature: LangGraph store available to middleware and runtime context hooks.
+  # The default direct host keeps this enabled so middleware can use the same durable store surface as other hosts.
+  store:
+    ref: store/default
+  # Upstream execution feature: no declarative HITL tool routing by default.
+  interruptOn: {}
+  # Upstream execution feature: filesystem middleware settings for LangChain v1 agents.
+  # This only becomes active when `middleware` includes `{ kind: filesystem }`, or when
+  # automatic upstream middleware such as skills or memory need a filesystem backend.
+  # Keep the default root inside the workspace so file-aware middleware stays bounded.
+  filesystem:
+    rootDir: .
+    virtualMode: true
+    maxFileSizeMb: 10
+  # Upstream execution feature: no extra declarative middleware beyond the runtime's automatic injections.
+  # Common upstream middleware kinds that this harness can compile directly from YAML:
+  # - `filesystem`
+  # - `patchToolCalls`
+  # - `summarization`
+  # - `dynamicSystemPrompt`
+  # - `humanInTheLoop`
+  # - `todoList`
+  # - `pii`, `piiRedaction`
+  #
+  # Keep the default empty so the lightweight direct host stays minimal.
+  middleware: []
+  # Upstream execution feature: system prompt for the lightweight direct-response host.
+  # This prompt should keep the agent focused on:
+  # - answering simple requests in one turn
+  # - staying lightweight instead of planning or orchestrating
+  # - avoiding delegation-heavy decomposition unless the caller explicitly switches agents
+  #
+  # The direct host is intentionally narrower than the orchestra host:
+  # - `direct` is optimized for latency and straightforward completion
+  # - `orchestra` is optimized for multi-step work, tools, and delegation
+  #
+  # Keep this prompt biased toward concise, self-contained answers. If richer routing policy is
+  # needed for choosing between host agents, configure that separately via `Runtime.spec.routing`
+  # rather than overloading the direct host prompt with classifier behavior.
+  systemPrompt: |-
+    You are the direct agent.
 
-      This is a manual low-latency host.
-      Answer simple requests directly.
-      Keep the path lightweight.
-      Do not delegate.
-      Do not perform broad multi-step execution.
-      Do not behave like the default execution host.
+    This is a manual low-latency host.
+    Answer simple requests directly.
+    Keep the path lightweight.
+    Do not delegate.
+    Do not perform broad multi-step execution.
+    Do not behave like the default execution host.