@botbotgo/agent-harness 0.0.122 → 0.0.124

package/README.md

@@ -14,7 +14,7 @@
 # @botbotgo/agent-harness
 
 <p align="center">
-  <strong>The production runtime for multi-agent systems—built to ship, operate, and recover, not just execute.</strong>
+  <strong>The application runtime for multi-agent products with approvals, recovery, and operator control built in.</strong>
 </p>
 
 <p align="center">
@@ -29,9 +29,38 @@
   >
 </p>
 
+## What Problem We Solve
+
+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:
+
+- more generated logic creates more execution paths to inspect, interrupt, retry, and recover
+- natural-language entrypoints turn approvals and policy boundaries into runtime requirements
+- backend, prompt, and tool changes happen faster, but product-facing behavior still needs one stable control surface
+- MCP and provider-native tooling expand what agents can reach, which raises the bar for governance
+
+Teams still need answers to the runtime questions that appear after that shift:
+
+- how approvals are resolved and audited
+- how runs, threads, and events stay inspectable
+- how execution recovers after interruption, failure, or restart
+- how routing, concurrency, and maintenance policy stay consistent
+- how backend churn does not leak into the product model
+
+`agent-harness` solves that layer. It keeps agent execution upstream while making the application runtime operable, recoverable, and governable.
+
+Concretely, that means:
+
+- a product-facing approval and operator surface instead of backend-specific middleware state
+- persisted `runs`, `threads`, `approvals`, and `events` as stable runtime records
+- restart-safe recovery and continuation as system-managed behavior
+- YAML-owned routing, concurrency, maintenance, and recovery policy
+- adapter isolation so backend replacement does not redefine the public runtime model
+
 ## Product Overview
 
-`@botbotgo/agent-harness` is a workspace-shaped application runtime for real agent products.
+`@botbotgo/agent-harness` is a workspace-shaped application runtime for real multi-agent products.
 
 It is not a new agent framework. It is the runtime layer around LangChain v1 and DeepAgents that turns one workspace into one operable application runtime.
 
@@ -39,7 +68,7 @@ The point is simple:
 
 - Codex, Claude Code, and Cursor are products for people using agents
 - LangChain v1 and DeepAgents are frameworks for defining agent execution semantics
-- `agent-harness` is the runtime product layer for shipping, operating, recovering, and governing multi-agent applications
+- `agent-harness` is the runtime product layer for operating, recovering, approving, and governing multi-agent applications
 
 The product boundary is strict:
 
@@ -61,6 +90,14 @@ The runtime provides:
 - local `resources/tools/` `tool({...})` modules and `resources/skills/` discovery
 - persisted threads, runs, approvals, events, queue state, and recovery metadata
 
+In practice, the harness exists for the parts that are painful to rebuild inside every agent app:
+
+- approval inboxes and human decision flow
+- persisted runs, threads, and inspectable event history
+- runtime-managed recovery after interrupts, failures, or process restart
+- 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 config instead of reverse-engineering adapter behavior from source.
 
 The default rule is:
@@ -89,7 +126,7 @@ Recommended orchestration shape for long-running flows:
 
 ## Why This Exists
 
-Most agent demos stop at execution.
+Most agent tooling stops at execution.
 
 Real products need a runtime that can answer harder questions:
 
@@ -103,9 +140,10 @@ Real products need a runtime that can answer harder questions:
 
 ## What Makes It Different
 
-- It treats `runs`, `threads`, `approvals`, `events`, and recovery as product concepts
+- It treats `runs`, `threads`, `approvals`, `events`, and recovery as first-class product records
+- It gives operators a runtime control surface instead of exposing raw backend internals
 - It keeps checkpoint resume system-managed instead of promoting checkpoint internals into the primary API
-- It lets YAML own assembly complexity while code keeps a tiny surface
+- 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
 
 ## Quick Start

package/README.zh.md

@@ -14,7 +14,7 @@
 # @botbotgo/agent-harness
 
 <p align="center">
-  <strong>面向多 agent 生产落地的运行时：为上线、运维与恢复而设计，而不止步于执行。</strong>
+  <strong>面向多 agent 产品的应用运行时：内建审批、恢复与运维控制，而不只是执行。</strong>
 </p>
 
 <p align="center">
@@ -29,9 +29,38 @@
   >
 </p>
 
+## 我们解决什么问题
+
+AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正变难的是运行时运维。
+
+当 demo 跑起来之后，真正的软件问题会换一种形状出现：
+
+- 更多生成式逻辑，意味着更多要观测、打断、重试和恢复的执行路径
+- 自然语言入口让审批与策略边界变成运行时要求，而不是事后补丁
+- backend、prompt 和工具变化更快了，但面向产品的控制面仍然必须稳定
+- MCP 与 provider 原生工具扩展了 agent 的可触达范围，也同步抬高了治理要求
+
+团队仍然要回答这些运行时问题：
+
+- 审批怎么决策、怎么审计
+- runs、threads、events 怎么稳定可查
+- 执行被打断、失败或进程重启后怎么恢复
+- 路由、并发和维护策略怎么保持一致
+- 后端频繁变化时，怎么不让产品模型跟着漂移
+
+`agent-harness` 解决的就是这一层。它把 agent 执行留在上游，同时把应用运行时做成可运维、可恢复、可治理的系统。
+
+具体来说，就是把这些能力沉到运行时里：
+
+- 面向产品的审批与运维控制面，而不是 backend 专属的中间件状态
+- 稳定持久化的 `runs`、`threads`、`approvals` 与 `events` 记录
+- 由系统托管的重启恢复与中断续跑
+- 由 YAML 持有的路由、并发、维护与恢复策略
+- 通过适配器隔离 backend 变化，不让公共运行时模型漂移
+
 ## 产品概览
 
-`@botbotgo/agent-harness` 是面向真实 agent 产品的、工作区形态的应用运行时。
+`@botbotgo/agent-harness` 是面向真实多 agent 产品的、工作区形态的应用运行时。
 
 它不是又一个 agent 框架，而是围绕 LangChain v1 与 DeepAgents 的运行时层：把一个工作区变成一套可运维的应用运行时。
 
@@ -39,7 +68,7 @@
 
 - Codex、Claude Code、Cursor 是「人用 agent」的产品
 - LangChain v1 与 DeepAgents 是定义 agent 执行语义的框架
-- `agent-harness` 是交付、运维、恢复与治理多 agent 应用的运行时产品层
+- `agent-harness` 是负责运维、恢复、审批与治理多 agent 应用的运行时产品层
 
 产品边界是清晰的：
 
@@ -61,6 +90,14 @@
 - 本地 `resources/tools/` 中 `tool({...})` 工具模块与 `resources/skills/` 的发现
 - 持久化的线程、运行、审批、事件、队列状态与恢复元数据
 
+落到实际系统里，harness 主要解决那些每个 agent 应用都不想重复造一遍的运行时难题：
+
+- 审批收件箱与人工决策流
+- 持久化的 runs、threads 与可查询事件历史
+- 中断、失败或进程重启后的运行时托管恢复
+- 队列、并发、维护与运维策略
+- 即使后端变更也保持稳定的运行时记录模型
+
 仓库自带的默认配置刻意做成「形状完整」。随仓库提供的 YAML 对重要的运行时与 agent 开关给出显式默认值，便于从具体配置起步，而不必从源码反推适配器行为。
 
 默认原则是：
@@ -89,7 +126,7 @@
 
 ## 为何需要它
 
-多数 agent 演示停在「能跑」。
+多数 agent 工具停在「能跑」。
 
 真实产品需要能回答更难问题的运行时：
 
@@ -103,10 +140,11 @@
 
 ## 有何不同
 
-- 将 `runs`、`threads`、`approvals`、`events` 与恢复视为产品概念
+- 将 `runs`、`threads`、`approvals`、`events` 与恢复视为一等产品记录
+- 给运维侧提供运行时控制面，而不是暴露原始后端内部结构
 - 将 checkpoint 恢复作为系统管理的行为，而不是把 checkpoint 细节抬成主 API
-- 复杂装配交给 YAML，代码面保持极小
-- 在上游库未充分产品化的运行时时，做深做透
+- 复杂装配与运行策略交给 YAML，代码面保持极小
+- 在上游库未充分产品化的运行时问题上做深做透
 
 ## 快速开始
 

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.121";
+export declare const AGENT_HARNESS_VERSION = "0.0.123";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.121";
+export const AGENT_HARNESS_VERSION = "0.0.123";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.122",
+  "version": "0.0.124",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -15,6 +15,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "node": ">=24 <25"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/botbotgo/agent-harness.git"