@botbotgo/agent-harness 0.0.210 → 0.0.212

package/README.md

@@ -14,11 +14,11 @@
 # @botbotgo/agent-harness
 
 <p align="center">
-  <strong>The application runtime for multi-agent products with approvals, recovery, and operator control built in.</strong>
+  <strong>Build a stable, enterprise-grade, operable 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>
+  <strong>Ship quickly: one workspace assembles into one production-ready product runtime.</strong>
 </p>
 
 <p align="center">
@@ -39,14 +39,14 @@
 
 <p align="center">
   <em
-    >We specialize in AI solutions. If you have a product idea you want to ship,
+    >For AI solutions and help shipping a product idea, contact
     <a href="mailto:info@easynet.world">info@easynet.world</a>.</em
   >
 </p>
 
-## Start In A Few Lines
+## Start in a few lines
 
-You can start one agent runtime in a few lines of code:
+You can boot an agent runtime in a few lines of code:
 
 ```ts
 import { createAgentHarness, request, stop } from "@botbotgo/agent-harness";
@@ -65,16 +65,17 @@ try {
 }
 ```
 
-If your team already has a LangChain v1 or DeepAgents workspace, the point is to keep that stack and add approvals,
-recovery, inspection, and operator control around it instead of rewriting into a second framework.
+The goal is an **operable** runtime: approvals, recovery, inspection, and governance—ready for production operations.
+Where you already use LangChain v1 or DeepAgents for execution, agent-harness adds the product runtime layer around
+them without forcing a rewrite.
 
 ## Documentation Paths
 
-Read the repository in this order:
+Choose an entry point that matches what you need:
 
-- **Technology:** boundary judgment, side-by-side comparison, runtime model, protocol surfaces, API, recovery, approvals, and operator control
+- **Technology:** capability comparison, runtime model, protocol surfaces, API, recovery, approvals, and operator control
 - **Product:** what the stable runtime surface already is, which product scenarios it fits, and why it is not another agent framework
-- **Commercial:** deployment support, launch help, hardening, and handoff after the technical and product story is already clear
+- **Commercial:** pricing, engagement process, and scoped services for deployment help, launch hardening, and team handoff
 
 Recommended entry points:
 
@@ -86,18 +87,18 @@ Recommended entry points:
 
 ## License & Commercial Support
 
-This repository is licensed under **Apache License 2.0**.
+This project is licensed under **Apache License 2.0**.
 [LICENSE](./LICENSE)
 
-Core runtime is open source, so you can inspect and run it freely.
-Commercial support comes after adoption and focuses on helping teams get to a production-ready handoff, including:
+Core runtime is open source: inspect and run it freely.
+Commercial support focuses on helping teams reach a production-ready handoff, including:
 
 - Deployment and integration guidance for your environment
 - Initial deployment setup and launch assistance
 - Priority issue triage and troubleshooting
 - Runtime governance, approval flow, and recovery hardening support
 - Custom tools, connectors, and protocol integrations
-- Operator runbooks and handoff guidance for the client team
+- Operator runbooks and handoff guidance for your team
 
 Production operations, managed hosting, on-call coverage, and long-term run-the-system support are not included by default.
 If a team wants us to take on that responsibility, we scope it separately based on environment complexity and SLA expectations.
@@ -108,29 +109,29 @@ If your team needs a scalable enterprise setup, please contact:
 Additional docs:
 
 - [Commercial service offerings](./docs/commercial-pricing.md)
-- [Lead-to-paid process](./docs/enterprise-process.md)
+- [Commercial engagement process](./docs/enterprise-process.md)
 
 ## Easy to start · Full runtime · Configure and extend
 
-**At a glance:** the onboarding path stays thin, the runtime capabilities ship as a complete layer, and most ongoing work moves into **YAML configuration** plus **extensions** (local tools, SKILL packages, MCP) instead of bespoke runtime infrastructure.
+**At a glance:** onboarding stays thin, the runtime ships as a full layer, and day-to-day work lives in **YAML** plus **extensions** (local tools, SKILL packages, MCP)—not bespoke runtime plumbing.
 
 - **Easy to start:** `createAgentHarness` → `request` → `stop`, plus inspection helpers such as `subscribe`, `listSessions`, `listApprovals`, and `resolveApproval`.
 - **Configure:** routing, models, tools, stores, backends, MCP, recovery, and maintenance in declarative workspace YAML (see [Quick Start](#quick-start) and [How To Configure](#how-to-configure)).
 - **Extend:** drop `tool({...})` modules and SKILL trees under `resources/`, wire shared tools and MCP in catalogs, and let agents whitelist what they use.
 - **Built into the runtime:** persisted `requests`, `sessions`, `approvals`, and `events`; recovery and queueing; streaming listeners; MCP in/out; LangChain v1 and DeepAgents adapters—so you do not rebuild that layer per app.
 
-## Current Public Surface
+## Runtime capabilities at a glance
 
-The repository now ships more than a thin runtime bootstrap. The public surface is already broad enough that the homepage and docs need to describe it as a product runtime with external protocol boundaries, not only as YAML plus tools.
+The public API spans a full product runtime—persistent records, memory and evidence, protocol surfaces, and governance—not only a thin bootstrap around YAML and tools.
 
 - **Core runtime API:** `createAgentHarness`, `request`, `subscribe`, `resolveApproval`, inspection helpers, and stable persisted runtime records for `requests`, `sessions`, `approvals`, `events`, and artifacts.
 - **Runtime memory and evidence:** `memorize`, `recall`, `listMemories`, memory policy hooks, `listArtifacts`, `getArtifact`, `exportEvaluationBundle`, `replayEvaluationBundle`, and request/session evidence export helpers.
 - **Protocol and transport surfaces:** `createAcpServer`, `serveAcpStdio`, `serveAcpHttp`, `serveA2aHttp`, `serveAgUiHttp`, and `createRuntimeMcpServer` / `serveRuntimeMcpOverStdio`.
 - **Governed workspace runtime:** YAML-owned routing, concurrency, maintenance, MCP policy, runtime governance bundles, and approval defaults for sensitive memory or write-like MCP side effects.
 
-`deepagents-acp` is part of the current public story, not only a direction hidden in planning notes: `agent-harness` is moving toward a standard runtime boundary that external clients can talk to directly while the harness keeps persistence, recovery, approvals, and operator control runtime-owned.
+If you integrate external clients, treat `deepagents-acp` as the primary protocol direction: clients connect through that surface while `agent-harness` keeps persistence, recovery, approvals, and operator control on the runtime side.
 
-## What Problem We Solve
+## The problem this solves
 
 In one line: `agent-harness` productizes the runtime work that usually appears after the demo.
 
@@ -164,7 +165,7 @@ Teams still need clear answers to the runtime questions that appear after that s
 
 `agent-harness` solves that layer. It keeps agent execution upstream while turning the application runtime into something teams can operate, recover, and govern.
 
-That makes the product story easier to explain:
+In short:
 
 - you bring the workspace, agents, tools, and prompts
 - `agent-harness` brings persisted `requests`, `sessions`, `approvals`, `events`, recovery, and operator visibility
@@ -221,7 +222,7 @@ In practice, the harness exists for the parts that are expensive and repetitive
 - 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 configuration instead of reverse-engineering adapter behavior from source.
+The default workspace configuration shipped with the package is deliberately full-shaped. The bundled YAML keeps explicit defaults for important runtime and agent knobs so teams can start from concrete configuration instead of reverse-engineering adapter behavior from source.
 
 The default rule is:
 
@@ -241,7 +242,7 @@ Start with these user-facing docs:
 - `docs/long-term-memory.md`
 - `docs/memory-policy-reference.md`
 
-Maintainer notes and internal product-boundary discussions remain in the repository, but they are intentionally not part of the primary public reading path.
+Deeper design notes and boundary discussions ship alongside the package for advanced readers; everyday integration and operations rely on the README, developer docs, and topical references above.
 
 `deepagents-acp` is the required external protocol direction when external tools need a standard runtime boundary. The harness should conform to `deepagents-acp` semantics at that boundary while keeping runtime lifecycle, persistence, recovery, and governance harness-owned.
 
@@ -251,20 +252,6 @@ Recommended orchestration shape for long-running flows:
 - use `backend: deepagent` when you want high-level execution semantics with minimal application wiring
 - keep `backend: langchain-v1` for lighter direct-response or explicitly chosen V1 agent shapes
 
-## Why This Exists
-
-Most agent tooling stops at execution. Production software does not.
-
-Real products need a runtime that can answer harder questions:
-
-- Where do requests live?
-- How are approvals resolved?
-- What survives process restart?
-- How do you inspect sessions and events without exposing raw backend state?
-- How do you swap backend implementations without rewriting the product model?
-
-`agent-harness` is the layer that answers those questions without turning your application API into a mirror of LangChain v1 or DeepAgents.
-
 ## What Makes It Different
 
 - It treats `requests`, `sessions`, `approvals`, `events`, and recovery as first-class product records
@@ -274,9 +261,9 @@ Real products need a runtime that can answer harder questions:
 - It lets YAML own assembly and operating policy while code keeps a small, stable surface
 - It goes deep on runtime concerns that upstream libraries do not fully productize
 
-## What To Sell First
+## Primary use cases
 
-The product story should stay scenario-shaped instead of drifting back to a generic "multi-agent runtime" pitch.
+These scenarios map most directly to what the runtime is built for:
 
 - Enterprise internal agent runtime: approvals, restart-safe recovery, operator evidence, and policy-owned MCP access.
 - Code modernization runtime: long-running coding flows, approval checkpoints, resumable runs, and exported evidence packages.
@@ -367,7 +354,7 @@ Three-minute mental model:
 2. Call `request(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:
+In brief:
 
 - your team builds the agent app
 - `agent-harness` makes that app operable
@@ -718,7 +705,7 @@ Current temporary limits on the `backend: langchain-v1` path are:
 
 - approval-gated side-effect tools are less reliable than the DeepAgents path under real remote models
 - long multi-agent or orchestration-heavy flows are not the recommended default path
-- the repository now treats DeepAgents as the default execution path for complex runtime coverage, and LangChain v1 should be selected explicitly when a workspace truly wants that behavior
+- the package now treats DeepAgents as the default execution path for complex runtime coverage, and LangChain v1 should be selected explicitly when a workspace truly wants that behavior
 
 Practical guidance:
 
@@ -748,6 +735,8 @@ Important fields:
 - `maintenance.checkpoints` trims backend checkpoint state used for resume/recovery
 - `maintenance.records` trims harness-owned terminal session/request records stored in `runtime.sqlite`
 
+When libSQL reports an error against harness runtime persistence, the message is prefixed with the absolute path to `runtime.sqlite`. For constraint-class failures (or whenever you set `AGENT_HARNESS_RUNTIME_SQLITE_DEBUG=1`), the message also includes a truncated copy of the failing SQL so you can tell harness persistence apart from other SQLite databases in the same process.
+
 Example:
 
 ```yaml
@@ -963,7 +952,7 @@ spec:
     middleware: []
 ```
 
-For backend-specific options, prefer the upstream concept directly inside `spec.config`. Keep the public runtime contract in the main developer docs and API reference rather than relying on maintainer-only comparison notes.
+For backend-specific options, prefer the upstream concept directly inside `spec.config`. Keep the public runtime contract in the main developer docs and API reference rather than relying only on informal comparison notes.
 
 ## Design Notes
 

package/README.zh.md

@@ -14,11 +14,11 @@
 # @botbotgo/agent-harness
 
 <p align="center">
-  <strong>面向多 agent 产品的应用运行时：内建审批、恢复与运维控制，而不只是执行。</strong>
+  <strong>快速搭建稳定、可运维的企业级多智能体运行时：内置审批、恢复与运维能力，不止于「能跑通执行」。</strong>
 </p>
 
 <p align="center">
-  <strong>把一个 agent 工作区直接变成一套可运行的产品级 runtime。</strong>
+  <strong>一个工作区即可装配成面向生产的运行时（产品级能力）。</strong>
 </p>
 
 <p align="center">
@@ -27,7 +27,7 @@
 </p>
 
 <p align="center">
-  <a href="https://botbotgo.github.io/agent-harness/development/">开发文档</a>
+  <a href="https://botbotgo.github.io/agent-harness/development/zh/">开发文档</a>
   （多页面静态文档位于 <code>docs/development/</code>，支持 English / 中文）
 </p>
 
@@ -39,14 +39,14 @@
 
 <p align="center">
   <em
-    >我们专注于 AI 解决方案。若有希望落地的产品想法，欢迎来信
+    >如需 AI 解决方案或产品落地支持，欢迎来信
     <a href="mailto:info@easynet.world">info@easynet.world</a>。</em
   >
 </p>
 
 ## 几行代码启动
 
-几行代码就可以把一个 workspace 启动成 agent runtime：
+几行代码即可把工作区跑成智能体运行时：
 
 ```ts
 import { createAgentHarness, request, stop } from "@botbotgo/agent-harness";
@@ -65,74 +65,73 @@ try {
 }
 ```
 
-如果你的团队已经有 LangChain v1 或 DeepAgents 的 workspace，重点不是重写，而是在现有栈外面补上 approvals、
-recovery、inspection 和 operator control。
+目标是交付<strong>可运维</strong>的运行时：审批、恢复、可观测与治理默认就绪。若执行层已采用 LangChain v1 或 DeepAgents，可在其之上衔接产品级运行时，无需推倒重来。
 
 ## 阅读路径
 
-建议按这个顺序理解仓库：
+按你的目标选入口即可：
 
-- **技术：** 边界判断、并列对比、runtime 模型、协议接面、API、恢复、审批和 operator control
-- **产品：** 当前已经稳定公开的 runtime 能力面、适合的产品场景，以及为什么它不是另一个 agent framework
-- **商业：** 在技术和产品叙事已经清晰之后，再提供部署支持、上线协助、加固和交接服务
+- **想尽快接入：** 从[开发文档](./docs/development/zh/index.html)起步，再按需打开 API、协议与 Cookbook。
+- **想弄清边界：** 读[并列对比](./docs/development/zh/comparison.html)，区分运行时产品与上游执行框架。
+- **需要部署、加固或交接支持：** 查看[商业服务](./docs/commercial-pricing.md)与[合作流程](./docs/enterprise-process.md)。
 
 推荐入口：
 
-- [开发文档入口](./docs/development/index.html)
-- [并列对比页](./docs/development/comparison.html)
-- [API 参考](./docs/development/api-reference.html)
-- [协议接面](./docs/development/protocol-surfaces.html)
+- [开发文档入口](./docs/development/zh/index.html)
+- [并列对比页](./docs/development/zh/comparison.html)
+- [API 参考](./docs/development/zh/api-reference.html)
+- [协议接入说明](./docs/development/zh/protocol-surfaces.html)
 - [商业服务价格说明](./docs/commercial-pricing.md)
 
 ## 许可证与商业支持
 
-本仓库采用 **Apache License 2.0** 开源许可。[查看 LICENSE](./LICENSE)
+本项目采用 **Apache License 2.0** 开源许可。[查看 LICENSE](./LICENSE)
 
-核心运行时保持开源，方便你自由查看与试用。
-商业支持放在 adoption 之后，聚焦“帮助团队完成生产落地与交接”的能力，包括：
+核心运行时开源，可自由查看与试用。
+商业支持侧重帮助团队完成生产落地与交接，例如：
 
-- 你的环境中的部署与接入咨询
-- 初期 deployment 搭建与上线协助
+- 部署与接入咨询（面向你的环境）
+- 初期环境搭建与上线协助
 - 优先故障响应与问题排查
 - 运行时治理、审批流和恢复能力加固支持
 - 定制工具、连接器与协议接入开发
-- 面向客户团队的操作手册与交接说明
+- 操作手册与交接说明（面向接手团队）
 
-正式生产运维、托管、值班响应和长期代运营不属于默认服务内容。
-如果客户希望我们承担这部分责任，会根据环境复杂度和 SLA 要求单独评估与报价。
+正式生产运维、托管、值班与长期代运营不在默认范围内。
+若需要我方承担上述职责，将按环境与 SLA 单独评估与报价。
 
-如果你需要企业级合作方案，请联系：**[info@easynet.world](mailto:info@easynet.world)**。
+企业级合作请联络：**[info@easynet.world](mailto:info@easynet.world)**。
 
 相关资料：
 
 - [商业服务价格说明](./docs/commercial-pricing.md)
-- [咨询到签约流程](./docs/enterprise-process.md)
+- [商业合作流程](./docs/enterprise-process.md)
 
 ## 容易上手 · 能力齐全 · 配置与扩展
 
-**一句话：** 接入面保持很薄，运行时能力整层交付，日常主要工作集中在 **YAML 配置** 与 **扩展**（本地工具、SKILL 包、MCP），而不是反复自建运行时基础设施。
+**一句话：** 对外接口保持精简、运行时能力一次备齐，日常工作落在 **YAML 配置** 与 **扩展**（本地工具、SKILL、MCP）上，而不是反复搭建运行时底座。
 
 - **容易上手：** `createAgentHarness` → `request` → `stop`，以及 `subscribe`、`listSessions`、`listApprovals`、`resolveApproval` 等查询与控制能力。
 - **配置：** 路由、模型、工具、存储、后端、MCP、恢复与维护写在声明式工作区 YAML 里（见[快速开始](#快速开始)与[如何配置](#如何配置)）。
 - **扩展：** 在 `resources/` 下放置 `tool({...})` 模块与 SKILL 目录，在目录里声明共享工具与 MCP，再由各 agent 按名字白名单启用。
 - **内建运行时：** 持久化 `requests`、`sessions`、`approvals` 与 `events`；恢复与排队；流式监听；MCP 接入与对外暴露；LangChain v1 与 DeepAgents 适配——避免每个应用重复造这一层。
 
-## 当前公开能力面
+## 运行时能力速览
 
-如果你想先知道今天能直接用什么，可以先看这一节。`agent-harness` 已经提供完整的运行时能力，而不只是一个启动脚手架。
+若你想先看「今天能直接用到什么」，可从本节读起。`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`。
+- **核心 runtime API：** `createAgentHarness`、`request`、`subscribe`、`resolveApproval`、各类查询与检查辅助 API，以及稳定持久化的 `requests`、`sessions`、`approvals`、`events` 与 artifacts 记录。
+- **运行时 memory 与证据能力：** `memorize`、`recall`、`listMemories`、memory policy hooks、`listArtifacts`、`getArtifact`、`exportEvaluationBundle`、`replayEvaluationBundle`，以及 request / session 级证据导出辅助函数。
+- **协议与传输层：** `createAcpServer`、`serveAcpStdio`、`serveAcpHttp`、`serveA2aHttp`、`serveAgUiHttp`，以及 `createRuntimeMcpServer` / `serveRuntimeMcpOverStdio`。
 - **受治理的工作区运行时：** 由 YAML 持有的路由、并发、维护、MCP 策略、runtime governance bundles，以及针对敏感 memory 或写类 MCP 副作用的默认审批门槛。
 
-如果你的产品需要对接外部客户端，也可以从这里理解边界：`deepagents-acp` 是主要的外部协议方向，而持久化、恢复、审批和运行控制仍由 `agent-harness` 负责。
+若你的产品需要对接外部客户端，可从本节理解边界：`deepagents-acp` 是主要的外部协议接入方向；持久化、恢复、审批与运行控制仍由 `agent-harness` 在运行时侧承担。
 
-## 我们解决什么问题
+## 这能解决什么问题
 
-一句话概括：`agent-harness` 把通常在 demo 之后才暴露出来的运行时工作，提前做成产品 runtime 的一部分。
+一句话概括：`agent-harness` 把通常在 demo 之后才不得不补上的运行时工作，提前做成产品运行时的一部分。
 
-如果团队已经有 agents、prompts、tools 和 workflows，真正缺的通常不是再多一层执行，而是把这些能力变成“可运维软件”的运行时层。
+如果团队已经有 agents、prompts、tools 和 workflows，真正缺的通常不是再多一层执行，而是把这些能力沉淀成**可长期运维的软件**所需的运行时层。
 
 第一天就能直接拿到的东西：
 
@@ -219,27 +218,27 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 - 队列、并发、维护与运维策略
 - 即使后端变更也保持稳定的运行时记录模型
 
-仓库自带的默认配置刻意做成「形状完整」。随仓库提供的 YAML 对关键运行时与 agent 开关给出显式默认值，便于从具体配置起步，而不必从源码反推适配器行为。
+本包附带的默认工作区配置刻意做成「形状完整」。随发行版提供的 YAML 对关键运行时与 agent 开关给出显式默认值，便于从具体配置起步，而不必从源码反推适配器行为。
 
 默认原则是：
 
 - 若 LangChain v1 或 DeepAgents 已有能力，则在 YAML 中映射并在内部适配
 - 除非问题确实属于运行时职责，否则不增加新的公共运行时 API
 
-建议从这些面向用户的文档开始：
+建议从这些面向用户的文档开始（中文多页面在 `docs/development/zh/`）：
 
-- `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`
+- `docs/development/zh/index.html`
+- `docs/development/zh/getting-started.html`
+- `docs/development/zh/comparison.html`
+- `docs/development/zh/api-reference.html`
+- `docs/development/zh/protocol-surfaces.html`
+- `docs/development/zh/cookbook.html`
 - `docs/runtime-inspection-contract.md`
 - `docs/tool-execution-policy.md`
 - `docs/long-term-memory.md`
 - `docs/memory-policy-reference.md`
 
-仓库里仍然保留了部分设计说明和边界讨论，但日常使用时不需要先读这些内容。
+项目内还包含面向进阶读者与贡献者的设计说明与边界讨论；日常接入与运维以 README、开发文档与上文专题为准即可。
 
 当外部工具需要标准运行时边界时，`deepagents-acp` 是必须遵循的外部协议方向。`agent-harness` 应在该边界上严格契合 `deepagents-acp` 语义，同时继续把运行时生命周期、持久化、恢复与治理保留在 harness 内部。
 
@@ -249,36 +248,22 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 - 想用高层执行语义、少写应用编排时，优先选择 `backend: deepagent`
 - 轻量 direct-response 或明确需要 V1 agent 语义时，使用 `backend: langchain-v1`
 
-## 为何需要它
-
-多数 agent 工具停在「能跑」，但生产软件不能只停在这里。
-
-真实产品需要能回答更难问题的运行时：
-
-- 请求（requests）存在哪里？
-- 审批如何闭环？
-- 进程重启后什么还在？
-- 如何在不暴露原始后端状态的前提下检查会话与事件？
-- 如何在不大改产品模型的前提下替换后端实现？
-
-`agent-harness` 在不把应用 API 做成 LangChain v1 / DeepAgents 翻版的前提下，回答这些问题。
-
 ## 有何不同
 
-- 将 `requests`、`sessions`、`approvals`、`events` 与恢复视为一等产品记录
-- 给运维侧提供运行时控制面，而不是暴露原始后端内部结构
+- 将 `requests`、`sessions`、`approvals`、`events` 与恢复视为核心产品数据（长期可查、可治理）
+- 给运维侧提供运行时控制面，而不是把原始后端内部结构直接暴露出去
 - 将可观测性与治理留在运行时：包括 trace correlation、continuity metadata，以及高风险副作用的默认审批
 - 将 checkpoint 恢复作为系统管理的行为，而不是把 checkpoint 细节抬成主 API
 - 复杂装配与运行策略交给 YAML，代码面保持小而稳
 - 在上游库未充分产品化的运行时问题上做深做透
 
-## 先卖哪三类场景
+## 典型应用场景
 
-如果你在评估落地场景，可以先从下面三类最直接的用法理解它。
+下面三类用法与 runtime 的设计目标最直接对应：
 
-- 企业内部 agent 运行时：审批、重启恢复、operator 证据链，以及由策略持有的 MCP 访问控制。
+- 企业内部智能体运行时：审批、重启恢复、运维侧证据链，以及由策略约束的 MCP 访问控制。
 - 代码现代化运行时：长链路 coding flow、审批检查点、可恢复 runs，以及可导出的运行证据包。
-- 协议桥接运行时：ACP、A2A、AG-UI 与 runtime MCP 共用一套稳定控制面，而不是每个对外接面各写一层胶水。
+- 协议桥接运行时：ACP、A2A、AG-UI 与 runtime MCP 共用一套稳定控制面，而不是为每个对外入口各写一层集成胶水。
 
 一套常见的 runtime 治理默认值大致如下：
 
@@ -365,7 +350,7 @@ try {
 2. 用 `request(runtime, { ... })` 执行一次请求。
 3. 把持久化的运行时记录当成产品资产，而不是只盯着最终回答。
 
-如果再压缩成最短产品表述，就是：
+一句话概括：
 
 - 你的团队负责构建 agent app
 - `agent-harness` 负责让这个 app 可运维
@@ -505,7 +490,7 @@ const recalled = await recall(runtime, {
 
 - `memorize(...)` 返回稳定的 `MemoryRecord` 与 `MemoryDecision` 结果，而 merge、review、archive 与存储布局仍由 runtime 内部托管
 - `recall(...)` 返回按相关性排序、并按 scope / kind 过滤后的 `MemoryRecord`
-- `listMemories(...)` 返回稳定的 `MemoryRecord`，用于 inspection / admin 场景；如果不传 status 过滤器，默认只返回 `active`
+- `listMemories(...)` 返回稳定的 `MemoryRecord`，用于排查与管理场景；如果不传 status 过滤器，默认只返回 `active`
 - `updateMemory(...)` 通过 `memoryId` 更新单条 durable memory，而不暴露内部 store namespace
 - `removeMemory(...)` 通过 `memoryId` 删除单条 durable memory，并重建运行时托管的 projection
 - 业务知识分类、review UI 与管理后台仍应留在应用层
@@ -661,12 +646,12 @@ await stop(runtime);
 本地 function tool 如果在模块里声明了 schema，runtime governance 会直接把该模块 schema 视为事实来源；不需要为了 schema-bound 元数据再额外复制一份 YAML `inputSchema.ref`。
 若本地工具使用 Zod schema，请让工作区或隔离的 `resources` 包统一使用 `zod@^4`，避免 raw shape validator 与 runtime 解析落在不同 major 版本上。
 
-主要有三层配置：
+配置大致分这几层（由下至上叠加）：
 
-- 先由 workspace 启动时扫描本地和附加的 `resources` 包，建立统一 registry
-- agent 再按名字白名单选择 tools 与 skills
-- `config/runtime/workspace.yaml` 中的运行时策略
-- `config/catalogs/*.yaml` 中的可复用对象目录
+- workspace 启动时扫描本地与附加的 `resources` 包，建立统一 registry
+- 各 agent 再按名称白名单选用 tools 与 skills
+- `config/runtime/workspace.yaml` 承载运行时策略
+- `config/catalogs/*.yaml` 承载可复用对象目录
 - `config/**/*.yaml` 中的 agent 装配
 
 ### Backend 选择建议
@@ -677,7 +662,7 @@ await stop(runtime);
 
 - 在真实远端模型下，带 approval 的副作用工具调用稳定性弱于 DeepAgents 路径
 - 不建议把它作为长链路、多 agent、重 orchestration 流程的默认执行路径
-- 仓库当前已把 DeepAgents 作为复杂运行时覆盖的默认主路径；只有在工作区明确需要 V1 行为时，才应显式选择 LangChain v1
+- 本包当前已把 DeepAgents 作为复杂运行时覆盖的默认主路径；只有在工作区明确需要 V1 行为时，才应显式选择 LangChain v1
 
 实际建议：
 
@@ -709,6 +694,8 @@ await stop(runtime);
 - `maintenance.checkpoints` 清理后端用于 resume/recovery 的 checkpoint 状态
 - `maintenance.records` 清理 harness 自己保存在 `runtime.sqlite` 中、已结束的 session/request 记录
 
+当 libSQL 对 harness 运行时持久化报错时，错误信息会带上 `runtime.sqlite` 的绝对路径。对约束类错误（或设置环境变量 `AGENT_HARNESS_RUNTIME_SQLITE_DEBUG=1` 时），信息中还会包含被截断的失败 SQL，便于在同一进程里区分 harness 与其它 SQLite 数据库。
+
 示例：
 
 ```yaml

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.209";
+export declare const AGENT_HARNESS_VERSION = "0.0.211";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.209";
+export const AGENT_HARNESS_VERSION = "0.0.211";

package/dist/persistence/sqlite-store.js

@@ -27,6 +27,27 @@ function toSqliteUrl(filePath) {
 function nowIso() {
     return new Date(Date.now()).toISOString();
 }
+function runtimeSqliteErrorShouldIncludeSql(baseMessage) {
+    if (process.env.AGENT_HARNESS_RUNTIME_SQLITE_DEBUG === "1") {
+        return true;
+    }
+    return /SQLITE_CONSTRAINT|FOREIGN KEY|UNIQUE constraint|NOT NULL/i.test(baseMessage);
+}
+function formatRuntimeSqliteErrorMessage(dbPath, sql, baseMessage) {
+    let detail = `agent-harness runtime SQLite (${dbPath}): ${baseMessage}`;
+    if (sql && runtimeSqliteErrorShouldIncludeSql(baseMessage)) {
+        const sqlPreview = sql.replace(/\s+/g, " ").trim();
+        const truncated = sqlPreview.length > 220 ? `${sqlPreview.slice(0, 220)}…` : sqlPreview;
+        detail += ` [sql=${truncated}]`;
+    }
+    return detail;
+}
+function throwWrappedRuntimeSqliteError(dbPath, sql, error) {
+    const base = error instanceof Error ? error.message : String(error);
+    const wrapped = new Error(formatRuntimeSqliteErrorMessage(dbPath, sql, base));
+    wrapped.cause = error;
+    throw wrapped;
+}
 function buildWhereClause(filters) {
     const active = filters.filter(([, value]) => value !== undefined);
     if (active.length === 0) {
@@ -42,12 +63,18 @@ async function selectProtectedThreadIds(dbPath) {
         return [];
     }
     const client = createClient({ url: toSqliteUrl(dbPath) });
-    const result = await client.execute(`SELECT DISTINCT thread_id
+    const sql = `SELECT DISTINCT thread_id
      FROM runs
      WHERE checkpoint_ref IS NOT NULL
        AND checkpoint_ref != ''
-       AND (resumable = 1 OR state NOT IN ('completed', 'failed'))`);
-    return result.rows.map((row) => asString(asRow(row).thread_id)).filter((value) => value.length > 0);
+       AND (resumable = 1 OR state NOT IN ('completed', 'failed'))`;
+    try {
+        const result = await client.execute(sql);
+        return result.rows.map((row) => asString(asRow(row).thread_id)).filter((value) => value.length > 0);
+    }
+    catch (error) {
+        throwWrappedRuntimeSqliteError(dbPath, sql, error);
+    }
 }
 export async function listProtectedCheckpointThreadIds(dbPath) {
     return new Set(await selectProtectedThreadIds(dbPath));
@@ -83,16 +110,26 @@ export class SqlitePersistence {
     }
     async rawExecute(sql, args) {
         const client = await this.getClient();
-        if (args) {
-            await client.execute(sql, args);
-            return;
+        try {
+            if (args) {
+                await client.execute(sql, args);
+                return;
+            }
+            await client.execute(sql);
+        }
+        catch (error) {
+            throwWrappedRuntimeSqliteError(this.dbPath, sql, error);
         }
-        await client.execute(sql);
     }
     async rawSelectAll(sql, args) {
         const client = await this.getClient();
-        const result = args ? await client.execute(sql, args) : await client.execute(sql);
-        return result.rows.map((row) => asRow(row));
+        try {
+            const result = args ? await client.execute(sql, args) : await client.execute(sql);
+            return result.rows.map((row) => asRow(row));
+        }
+        catch (error) {
+            throwWrappedRuntimeSqliteError(this.dbPath, sql, error);
+        }
     }
     async ensureInitialized() {
         if (this.initialized) {
@@ -286,18 +323,25 @@ export class SqlitePersistence {
     async execute(sql, args) {
         await this.ensureInitialized();
         const client = await this.getClient();
-        if (args) {
-            await client.execute(sql, args);
-            return;
+        try {
+            if (args) {
+                await client.execute(sql, args);
+                return;
+            }
+            await client.execute(sql);
+        }
+        catch (error) {
+            throwWrappedRuntimeSqliteError(this.dbPath, sql, error);
         }
-        await client.execute(sql);
     }
     async executeTransaction(steps) {
         await this.ensureInitialized();
         const client = await this.getClient();
-        await client.execute("BEGIN IMMEDIATE");
+        let lastSql = "BEGIN IMMEDIATE";
         try {
+            await client.execute("BEGIN IMMEDIATE");
             for (const step of steps) {
+                lastSql = step.sql;
                 if (step.args) {
                     await client.execute(step.sql, step.args);
                 }
@@ -305,6 +349,7 @@ export class SqlitePersistence {
                     await client.execute(step.sql);
                 }
             }
+            lastSql = "COMMIT";
             await client.execute("COMMIT");
         }
         catch (error) {
@@ -314,21 +359,31 @@ export class SqlitePersistence {
             catch {
                 // Ignore rollback failures and preserve the original error.
             }
-            throw error;
+            throwWrappedRuntimeSqliteError(this.dbPath, lastSql, error);
         }
     }
     async selectOne(sql, args) {
         await this.ensureInitialized();
         const client = await this.getClient();
-        const result = args ? await client.execute(sql, args) : await client.execute(sql);
-        const first = result.rows[0];
-        return first ? asRow(first) : null;
+        try {
+            const result = args ? await client.execute(sql, args) : await client.execute(sql);
+            const first = result.rows[0];
+            return first ? asRow(first) : null;
+        }
+        catch (error) {
+            throwWrappedRuntimeSqliteError(this.dbPath, sql, error);
+        }
     }
     async selectAll(sql, args) {
         await this.ensureInitialized();
         const client = await this.getClient();
-        const result = args ? await client.execute(sql, args) : await client.execute(sql);
-        return result.rows.map((row) => asRow(row));
+        try {
+            const result = args ? await client.execute(sql, args) : await client.execute(sql);
+            return result.rows.map((row) => asRow(row));
+        }
+        catch (error) {
+            throwWrappedRuntimeSqliteError(this.dbPath, sql, error);
+        }
     }
     mapThreadSummary(row) {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.210",
+  "version": "0.0.212",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",
@@ -70,6 +70,7 @@
     "test:real-providers": "vitest run test/providers/real-provider-harness.test.ts",
     "security:ci": "npm audit --omit=dev --audit-level=high",
     "security:report": "npm audit --omit=dev --json > security-audit-report.json || true",
+    "docs:sync-dev-nav": "node ./scripts/sync-developer-docs-nav.mjs",
     "release:prepare": "npm version patch --no-git-tag-version && node ./scripts/sync-example-version.mjs",
     "release:pack": "npm pack --dry-run",
     "release:publish": "npm publish --access public --registry https://registry.npmjs.org/"