stable-harness 0.0.7 → 0.0.9

package/docs/tooling/0.1.0-bettercall-tool-quality.zh.md

@@ -0,0 +1,231 @@
+# BetterCall Tool Call Quality
+
+本文说明 `stable-harness` 如何通过 `@botbotgo/better-call` 提升 tool call 质量。
+
+核心原则：
+
+- DeepAgents/LangGraph 负责 agent loop、tool selection、是否再次调用工具。
+- BetterCall 负责工具调用进入真实执行层前的 validate + repair + block。
+- stable-harness tool gateway 负责运行时治理：agent inventory、context-aware semantic validator、错误投影、trace/event。
+
+## 接入位置
+
+`stable-harness` 在 tool gateway 创建阶段准备 BetterCall validation tools：
+
+```ts
+const registry = new Map(prepareBetterCallTools(tools, options.betterCall).map((tool) => [tool.id, tool]));
+```
+
+内部做一次薄映射：
+
+| stable-harness tool | BetterCall tool |
+| --- | --- |
+| `id` | `name` |
+| `description` | `description` |
+| `schema` | `schema` |
+| validation-only `invoke(input)` | returns `input` |
+
+这样 runtime 每次执行工具时不再临时创建单工具 wrapper，而是复用创建 gateway 时由 `betterTools(...)` 生成的 validation tools。BetterCall mode 默认为 `repair`；当配置了 `repair` function 或 `repairModel` 时，tool selection 和 arguments/schema 错误会先修复并二次验证，仍无法通过时才拒绝。
+
+## 总体流程
+
+```mermaid
+flowchart TD
+  A["Workspace tools"] --> B["createInMemoryToolGateway(tools)"]
+  B --> C["prepareBetterCallTools(tools)"]
+  C --> D["betterTools(tools.map(toBetterCallTool))"]
+  D --> E["Tool registry stores original tool + BetterCall validation tool"]
+
+  F["DeepAgents/LangGraph selects tool + args"] --> G["stable-harness runtime checks agent inventory"]
+  G --> H["tool gateway invoke"]
+  H --> S{"registered tool?"}
+  S -- "no" --> R["BetterCall repair tool selection within allowed inventory"]
+  S -- "yes" --> I["stable validateArgs(context)"]
+  R --> I
+  I --> J["BetterCall validate + repair + block"]
+  J --> K{"valid or repaired?"}
+  K -- "yes" --> L["execute original tool.invoke(safe args, context)"]
+  K -- "no" --> M["ToolArgumentValidationError with structured issues"]
+  M --> N["DeepAgents receives tool error observation"]
+  N --> O["model may issue corrected tool call"]
+```
+
+## 质量提升点
+
+| Layer | 检查内容 | 失败时 |
+| --- | --- | --- |
+| Agent inventory | 当前 agent 是否允许调用该 tool | runtime 直接拒绝 |
+| stable semantic validator | 需要 `context` 的业务/运行时规则 | reject 或 repair args |
+| BetterCall tool selection | tool name 是否存在于 wrapped tools | 默认 repair mode；修复后的 tool 仍必须在 agent inventory 内 |
+| BetterCall arguments/schema | required、type、enum、extra arg | 默认 repair mode；配置 repair 后先修复，失败才 block |
+| Error projection | BetterCall path 转换为 stable-harness 参数 path | 返回可读结构化错误 |
+| DeepAgents repair loop | 模型看到 tool error 后是否重试 | 上游 agent loop 决定 |
+
+## Sequence: Gateway 初始化
+
+```mermaid
+sequenceDiagram
+  participant App as Workspace App
+  participant Gateway as createInMemoryToolGateway
+  participant Adapter as stable BetterCall adapter
+  participant BC as betterTools
+  participant Registry as Tool Registry
+
+  App->>Gateway: tools array
+  Gateway->>Adapter: prepareBetterCallTools(tools)
+  Adapter->>Adapter: map stable tool id -> BetterCall tool name
+  Adapter->>BC: betterTools(mappedTools, { mode: "repair", repair/repairModel })
+  BC-->>Adapter: validation tools
+  Adapter-->>Gateway: runtime tools with validationTool
+  Gateway->>Registry: store by stable tool.id
+```
+
+要点：
+
+- `betterTools(...)` 在 gateway 创建阶段调用一次，默认 `mode` 是 `repair`。
+- `ToolGatewayTool` 的公开类型不暴露 `validationTool`。
+- 原始 stable tool 的 `invoke(args, context)` 不被 BetterCall 替换；BetterCall 只做执行前验证、修复和拦截。
+
+## Sequence: Tool Selection Repair
+
+```mermaid
+sequenceDiagram
+  participant Runtime as stable runtime
+  participant Gateway as tool gateway
+  participant BC as BetterCall reliableToolCalls
+  participant Tool as Repaired tool
+
+  Runtime->>Gateway: repairToolCall(wrongTool, args, allowedToolIds)
+  Gateway->>BC: all registered tools filtered by allowedToolIds
+  BC->>BC: repair tool name + args
+  alt repaired to allowed registered tool
+    BC-->>Gateway: safe toolId + args
+    Gateway-->>Runtime: repaired tool call
+    Runtime->>Gateway: invoke(repaired toolId, args)
+    Gateway->>Tool: execute after argument validation
+  else cannot repair or repaired tool not allowed
+    BC-->>Gateway: no safe call
+    Gateway-->>Runtime: block with inventory/registration error
+  end
+```
+
+修复 tool selection 时，stable-harness 只把当前 agent 允许的工具传给 BetterCall。即使 repair model 返回了别的工具，只要不在 `allowedToolIds` 里，runtime 仍然拒绝执行。
+
+## Sequence: Validate + Repair + Block
+
+```mermaid
+sequenceDiagram
+  participant DA as DeepAgents/LangGraph
+  participant Runtime as stable runtime
+  participant Gateway as tool gateway
+  participant Semantic as validateArgs(context)
+  participant BC as BetterCall validation tool
+  participant Tool as Original tool
+
+  DA->>Runtime: selected tool + args
+  Runtime->>Runtime: verify tool is assigned to agent
+  Runtime->>Gateway: invoke(toolId, args, context)
+  Gateway->>Semantic: validateArgs(args, context)
+  alt semantic reject
+    Semantic-->>Gateway: reject with issues
+    Gateway-->>Runtime: ToolArgumentValidationError
+  else semantic repair or allow
+    Semantic-->>Gateway: repaired/allowed args
+    Gateway->>BC: validationTool.invoke(args)
+    alt BetterCall repairs
+      BC-->>Gateway: safe args
+      Gateway->>Tool: invoke(safe args, context)
+      Tool-->>Gateway: output
+      Gateway-->>Runtime: tool result
+    else BetterCall rejects
+      BC-->>Gateway: BetterToolValidationError(issues)
+      Gateway->>Gateway: map $.calls[0].args.x -> $.x
+      Gateway-->>Runtime: ToolArgumentValidationError
+    else BetterCall accepts
+      BC-->>Gateway: validated args
+      Gateway->>Tool: invoke(args, context)
+      Tool-->>Gateway: output
+      Gateway-->>Runtime: tool result
+    end
+  end
+```
+
+BetterCall 默认运行在 repair mode。配置了 `repair` function 或 `repairModel` 时，BetterCall 会先尝试修复 arguments，再二次验证，验证通过后才允许执行。没有可用修复器时，它会退化为 validate + block，保证错误调用不会进入真实工具。
+
+## Sequence: DeepAgents 自我修复
+
+```mermaid
+sequenceDiagram
+  participant Model as Agent model
+  participant DA as DeepAgents/LangGraph loop
+  participant Gateway as stable tool gateway
+  participant BC as BetterCall validation
+  participant Tool as Real tool
+
+  Model-->>DA: tool call with bad args
+  DA->>Gateway: invoke tool
+  Gateway->>BC: validate args
+  BC-->>Gateway: reject structured issues
+  Gateway-->>DA: ToolMessage(status="error")
+  DA->>Model: feed tool error observation
+  Model-->>DA: corrected tool call
+  DA->>Gateway: invoke corrected tool
+  Gateway->>BC: validate corrected args
+  BC-->>Gateway: accept
+  Gateway->>Tool: execute real tool
+  Tool-->>DA: result
+```
+
+这一步不是 stable-harness 本地 replay tool call，也不是 TODO/text parsing。模型是否根据错误再次调用工具，属于 DeepAgents/LangGraph agent loop。
+
+## Sequence: BetterCall repairModel 模式
+
+`@botbotgo/better-call` package 本身支持：
+
+```ts
+const tools = betterTools([searchTool, calculatorTool], { repairModel });
+```
+
+当前 stable-harness tool gateway 默认使用 BetterCall `repair` mode，并允许通过 `betterCall.repair` 或 `betterCall.repairModel` 注入修复器。没有修复器时，安全语义仍然是 block。
+
+配置 `repairModel` 后，流程是：
+
+```mermaid
+sequenceDiagram
+  participant Gateway as stable tool gateway
+  participant BC as BetterCall
+  participant Repair as repairModel
+  participant Tool as Real tool
+
+  Gateway->>BC: validationTool.invoke(args)
+  BC-->>Gateway: reject
+  BC->>Repair: repair prompt + issues
+  Repair-->>BC: corrected calls JSON
+  BC->>BC: validate repaired args again
+  alt repaired valid
+    BC-->>Gateway: repaired args
+    Gateway->>Tool: execute with repaired args
+  else repaired invalid
+    BC-->>Gateway: structured rejection
+    Gateway-->>Gateway: block before execution
+  end
+```
+
+这会让 gateway 在返回错误给 DeepAgents 之前先修一次。修复后仍不合法时，才把结构化错误交回 DeepAgents/LangGraph agent loop。
+
+## 错误类型分类
+
+| Category | Example | stable-harness 行为 |
+| --- | --- | --- |
+| Tool selection | unknown tool、wrong tool name | 默认 repair mode；修复后仍必须是当前 agent 允许的 registered tool，否则拒绝 |
+| Irrelevance | no tool should be called | BetterCall 可在 package 层识别；gateway 层通常已有 selected tool |
+| Arguments | missing required arg、wrong arg name、wrong type | 默认 repair mode；有修复器时先 repair，再二次验证 |
+| Schema | invalid enum、extra arg | 默认 repair mode；可修复项先 repair，仍无法通过 schema 时拒绝 |
+| Semantic | workspace-relative path、domain-specific ticker | stable `validateArgs(context)` 拒绝或 repair |
+
+## 当前验证
+
+- `npm run check`
+- `npm test`：74/74 通过
+- `npm run check:rules`
+- BetterCall package 已发布到 npm：`@botbotgo/better-call@0.1.1`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stable-harness",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "type": "module",
   "description": "Stable application runtime and operator control plane for agent workspaces.",
   "license": "MIT",
@@ -18,6 +18,7 @@
   },
   "files": [
     "README.md",
+    "docs/**/*.md",
     "dist/*.js",
     "dist/*.d.ts",
     "dist/compat/**/*.js",
@@ -66,6 +67,7 @@
     "prepack": "npm run release:minify",
     "release:minify": "find dist packages -type f -name '*.js' \\( -path 'dist/*' -o -path '*/dist/*' \\) -exec sh -c 'for f do ./node_modules/.bin/terser \"$f\" --compress passes=2 --mangle keep_fnames=true --keep-fnames --keep-classnames --module --comments false --output \"$f\"; done' sh {} +",
     "release:check-package": "node scripts/release/check-npm-package.mjs",
+    "release:smoke": "node scripts/release/smoke-npm-install.mjs",
     "release:pack": "npm run build && npm run release:check-package && npm pack --dry-run",
     "release:publish": "npm publish --access public --registry https://registry.npmjs.org/",
     "example:minimal": "node dist/examples/minimal-deepagents/run.js"