@botbotgo/agent-harness 0.0.210 → 0.0.211

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">
@@ -44,9 +44,9 @@
   >
 </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:
 
-- **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:** deployment support, launch help, hardening, and handoff once the technical fit and product scope are clear
 
 Recommended entry points:
 
@@ -89,15 +90,15 @@ Recommended entry points:
 This repository 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,11 +109,11 @@ 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)).
@@ -121,7 +122,7 @@ Additional docs:
 
 ## Current Public Surface
 
-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 package is more than a thin bootstrap: the public surface is broad enough to describe as a full product runtime with external protocol boundaries—not just YAML plus 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.
@@ -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
@@ -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.
+Additional contributor-oriented design notes live in the repository; you do not need them for everyday integration and operations.
 
 `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.
 
@@ -274,9 +275,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 +368,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
@@ -748,6 +749,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 +966,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">
@@ -46,7 +46,7 @@
 
 ## 几行代码启动
 
-几行代码就可以把一个 workspace 启动成 agent runtime：
+几行代码即可把工作区跑成智能体运行时：
 
 ```ts
 import { createAgentHarness, request, stop } from "@botbotgo/agent-harness";
@@ -65,52 +65,51 @@ try {
 }
 ```
 
-如果你的团队已经有 LangChain v1 或 DeepAgents 的 workspace，重点不是重写，而是在现有栈外面补上 approvals、
-recovery、inspection 和 operator control。
+目标是交付<strong>可运维</strong>的运行时：审批、恢复、可观测与治理默认就绪。若执行层已采用 LangChain v1 或 DeepAgents，可在其之上衔接产品级运行时，无需推倒重来。
 
 ## 阅读路径
 
 建议按这个顺序理解仓库：
 
-- **技术：** 边界判断、并列对比、runtime 模型、协议接面、API、恢复、审批和 operator control
-- **产品：** 当前已经稳定公开的 runtime 能力面、适合的产品场景，以及为什么它不是另一个 agent framework
-- **商业：** 在技术和产品叙事已经清晰之后，再提供部署支持、上线协助、加固和交接服务
+- **技术：** 能力对比、运行模型、协议接入、API、恢复、审批与运维控制
+- **产品：** 稳定的公开运行时能力、适用场景，以及它为何不是又一个 agent 框架
+- **商业：** 在技术与产品范围理清之后，再谈部署支持、上线协助、加固与交接
 
 推荐入口：
 
 - [开发文档入口](./docs/development/index.html)
 - [并列对比页](./docs/development/comparison.html)
 - [API 参考](./docs/development/api-reference.html)
-- [协议接面](./docs/development/protocol-surfaces.html)
+- [协议接入说明](./docs/development/protocol-surfaces.html)
 - [商业服务价格说明](./docs/commercial-pricing.md)
 
 ## 许可证与商业支持
 
 本仓库采用 **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 里（见[快速开始](#快速开始)与[如何配置](#如何配置)）。
@@ -119,20 +118,20 @@ recovery、inspection 和 operator control。
 
 ## 当前公开能力面
 
-如果你想先知道今天能直接用什么，可以先看这一节。`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` 负责。
 
 ## 我们解决什么问题
 
-一句话概括：`agent-harness` 把通常在 demo 之后才暴露出来的运行时工作，提前做成产品 runtime 的一部分。
+一句话概括：`agent-harness` 把通常在 demo 之后才不得不补上的运行时工作，提前做成产品运行时的一部分。
 
-如果团队已经有 agents、prompts、tools 和 workflows，真正缺的通常不是再多一层执行，而是把这些能力变成“可运维软件”的运行时层。
+如果团队已经有 agents、prompts、tools 和 workflows，真正缺的通常不是再多一层执行，而是把这些能力沉淀成**可长期运维的软件**所需的运行时层。
 
 第一天就能直接拿到的东西：
 
@@ -239,7 +238,7 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 - `docs/long-term-memory.md`
 - `docs/memory-policy-reference.md`
 
-仓库里仍然保留了部分设计说明和边界讨论，但日常使用时不需要先读这些内容。
+仓库中也包含面向贡献者的设计说明与边界讨论；日常接入与运维不必先读这些内容。
 
 当外部工具需要标准运行时边界时，`deepagents-acp` 是必须遵循的外部协议方向。`agent-harness` 应在该边界上严格契合 `deepagents-acp` 语义，同时继续把运行时生命周期、持久化、恢复与治理保留在 harness 内部。
 
@@ -265,20 +264,20 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 
 ## 有何不同
 
-- 将 `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 +364,7 @@ try {
 2. 用 `request(runtime, { ... })` 执行一次请求。
 3. 把持久化的运行时记录当成产品资产，而不是只盯着最终回答。
 
-如果再压缩成最短产品表述，就是：
+一句话概括：
 
 - 你的团队负责构建 agent app
 - `agent-harness` 负责让这个 app 可运维
@@ -505,7 +504,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 +660,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 选择建议
@@ -709,6 +708,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.210";

package/dist/package-version.js

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

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.211",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",