@botbotgo/agent-harness 0.0.184 → 0.0.185

package/README.md

@@ -47,6 +47,17 @@
 - **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
+
+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.
+
+- **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.
+
 ## What Problem We Solve
 
 In one line: `agent-harness` productizes the runtime work that usually appears after the demo.
@@ -127,13 +138,13 @@ The runtime provides:
 - YAML-defined workspace assembly for routing, models, tools, stores, backends, MCP, recovery, and maintenance
 - backend-adapted execution with current LangChain v1 and DeepAgents adapters
 - local `resources/tools/` `tool({...})` modules and `resources/skills/` discovery
-- persisted threads, runs, approvals, events, queue state, and recovery metadata
+- persisted sessions, requests, approvals, events, queue state, and recovery metadata
 
 In practice, the harness exists for the parts that are expensive and repetitive to rebuild inside every agent app:
 
 - approval inboxes and human decision flow
-- persisted runs, threads, and inspectable event history
-- run correlation, continuity, and recovery inspection that still works after a stream fallback or restart
+- persisted requests, sessions, and inspectable event history
+- request correlation, continuity, and recovery inspection that still works after a stream fallback or restart
 - 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
@@ -189,17 +200,17 @@ Most agent tooling stops at execution. Production software does not.
 
 Real products need a runtime that can answer harder questions:
 
-- Where do runs live?
+- Where do requests live?
 - How are approvals resolved?
 - What survives process restart?
-- How do you inspect threads and events without exposing raw backend state?
+- 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 `runs`, `threads`, `approvals`, `events`, and recovery as first-class product records
+- It treats `requests`, `sessions`, `approvals`, `events`, and recovery as first-class product records
 - It gives operators a runtime control surface instead of exposing raw backend internals
 - It keeps observability and governance runtime-owned with trace correlation, continuity metadata, and approval defaults for sensitive side effects
 - It keeps checkpoint resume system-managed instead of promoting checkpoint internals into the primary API
@@ -211,7 +222,7 @@ Real products need a runtime that can answer harder questions:
 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 need approvals, restart recovery, queueing, or inspectable request 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
 
@@ -300,9 +311,9 @@ If you want the shortest possible mental model:
 - LangChain v1 and DeepAgents backend adaptation
 - Auto-discovered local `tool({...})` tools and SKILL packages
 - provider-native tools, MCP tools, and workspace-local tool modules
-- persisted threads, runs, approvals, lifecycle events, and queued runs
+- persisted sessions, requests, approvals, lifecycle events, and queued requests
 - runtime-managed recovery and checkpoint maintenance
-- structured output and multimodal content preservation in run results
+- structured output and multimodal content preservation in request results
 - MCP bridge support for agent-declared MCP servers
 - MCP server support for exposing harness tools outward
 - optional `mem0` semantic recall augmentation over canonical SQLite durable memory
@@ -658,7 +669,7 @@ Important fields:
 `maintenance.checkpoints` and `maintenance.records` are separate retention layers:
 
 - `maintenance.checkpoints` trims backend checkpoint state used for resume/recovery
-- `maintenance.records` trims harness-owned terminal thread/run records stored in `runtime.sqlite`
+- `maintenance.records` trims harness-owned terminal session/request records stored in `runtime.sqlite`
 
 Example:
 
@@ -845,7 +856,7 @@ spec:
     systemPrompt: Answer simple requests directly.
 ```
 
-When `config.filesystem.sessionStorage.enabled: true` is set for a LangChain binding, the runtime keeps one filesystem root per persisted session/thread and reuses the same runnable cache entry for repeated work on that session instead of collapsing every run onto one shared workspace directory.
+When `config.filesystem.sessionStorage.enabled: true` is set for a LangChain binding, the runtime keeps one filesystem root per persisted session and reuses the same runnable cache entry for repeated work on that session instead of collapsing every request onto one shared workspace directory.
 
 Example orchestra host:
 

package/README.zh.md

@@ -47,6 +47,17 @@
 - **扩展：** 在 `resources/` 下放置 `tool({...})` 模块与 SKILL 目录，在目录里声明共享工具与 MCP，再由各 agent 按名字白名单启用。
 - **内建运行时：** 持久化 `requests`、`sessions`、`approvals` 与 `events`；恢复与排队；流式监听；MCP 接入与对外暴露；LangChain v1 与 DeepAgents 适配——避免每个应用重复造这一层。
 
+## 当前公开能力面
+
+这个仓库现在公开交付的已经不只是一个很薄的 runtime bootstrap。对外能力已经足够大，首页和文档也应该把它描述成一个带外部协议边界的产品级 runtime，而不只是 “YAML + tools”。
+
+- **核心 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`。
+- **受治理的工作区运行时：** 由 YAML 持有的路由、并发、维护、MCP 策略、runtime governance bundles，以及针对敏感 memory 或写类 MCP 副作用的默认审批门槛。
+
+`deepagents-acp` 已不应该只藏在规划文档里。它已经是当前公开产品叙事的一部分：`agent-harness` 正在朝一个可被外部客户端直接接入的标准 runtime boundary 演进，同时继续把持久化、恢复、审批和 operator control 保持为 harness 自有职责。
+
 ## 我们解决什么问题
 
 一句话概括：`agent-harness` 把通常在 demo 之后才暴露出来的运行时工作，提前做成产品 runtime 的一部分。
@@ -127,13 +138,13 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 - 以 YAML 描述的工作区装配：路由、模型、工具、存储、后端、MCP、恢复与维护等
 - 通过适配器对接当前的 LangChain v1 与 DeepAgents 执行
 - 本地 `resources/tools/` 中 `tool({...})` 工具模块与 `resources/skills/` 的发现
-- 持久化的线程、运行、审批、事件、队列状态与恢复元数据
+- 持久化的会话、请求、审批、事件、队列状态与恢复元数据
 
 落到实际系统里，harness 主要解决那些每个 agent 应用都不应该重复造一遍的运行时难题：
 
 - 审批收件箱与人工决策流
-- 持久化的 runs、threads 与可查询事件历史
-- 即使发生 stream fallback 或进程重启也还能成立的 run 关联、连续性与恢复观测
+- 持久化的 requests、sessions 与可查询事件历史
+- 即使发生 stream fallback 或进程重启也还能成立的 request 关联、连续性与恢复观测
 - 中断、失败或进程重启后的运行时托管恢复
 - 队列、并发、维护与运维策略
 - 即使后端变更也保持稳定的运行时记录模型
@@ -186,17 +197,17 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 
 真实产品需要能回答更难问题的运行时：
 
-- 运行（runs）存在哪里？
+- 请求（requests）存在哪里？
 - 审批如何闭环？
 - 进程重启后什么还在？
-- 如何在不暴露原始后端状态的前提下检查线程与事件？
+- 如何在不暴露原始后端状态的前提下检查会话与事件？
 - 如何在不大改产品模型的前提下替换后端实现？
 
 `agent-harness` 在不把应用 API 做成 LangChain v1 / DeepAgents 翻版的前提下，回答这些问题。
 
 ## 有何不同
 
-- 将 `runs`、`threads`、`approvals`、`events` 与恢复视为一等产品记录
+- 将 `requests`、`sessions`、`approvals`、`events` 与恢复视为一等产品记录
 - 给运维侧提供运行时控制面，而不是暴露原始后端内部结构
 - 将可观测性与治理留在运行时：包括 trace correlation、continuity metadata，以及高风险副作用的默认审批
 - 将 checkpoint 恢复作为系统管理的行为，而不是把 checkpoint 细节抬成主 API
@@ -208,7 +219,7 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 下面这些场景适合用 `agent-harness`：
 
 - 你已经确定产品需要 agents、tools、prompts 或 MCP，但真正缺的是运行时运维层
-- 你需要把审批、重启恢复、排队调度或可查询运行记录一起作为产品能力交付出去
+- 你需要把审批、重启恢复、排队调度或可查询请求记录一起作为产品能力交付出去
 - 你希望用一个 workspace 形态的装配模型取代每个应用各写一套启动和运行时胶水
 - 你想把 backend 的执行语义留在上游，同时把产品契约稳定下来
 
@@ -297,7 +308,7 @@ try {
 - LangChain v1 与 DeepAgents 后端适配
 - 自动发现本地工具与 SKILL 包
 - 原生 provider 工具、MCP 工具与工作区本地工具模块
-- 持久化线程、运行、审批、生命周期事件与排队运行
+- 持久化会话、请求、审批、生命周期事件与排队请求
 - 运行时管理的恢复与 checkpoint 维护
 - 运行结果中的结构化输出与多模态内容保留
 - 将 agent 声明的 MCP 服务桥接进来
@@ -618,7 +629,7 @@ await stop(runtime);
 `maintenance.checkpoints` 与 `maintenance.records` 是两层独立的保留策略：
 
 - `maintenance.checkpoints` 清理后端用于 resume/recovery 的 checkpoint 状态
-- `maintenance.records` 清理 harness 自己保存在 `runtime.sqlite` 中、已结束的 thread/run 记录
+- `maintenance.records` 清理 harness 自己保存在 `runtime.sqlite` 中、已结束的 session/request 记录
 
 示例：
 
@@ -804,7 +815,7 @@ spec:
     systemPrompt: Answer simple requests directly.
 ```
 
-当 LangChain 绑定启用 `config.filesystem.sessionStorage.enabled: true` 时，runtime 会为每个持久化 session/thread 维护独立的 filesystem 根目录，并按 session 复用 runnable cache，而不是把所有运行都压到同一个共享工作目录里。
+当 LangChain 绑定启用 `config.filesystem.sessionStorage.enabled: true` 时，runtime 会为每个持久化 session 维护独立的 filesystem 根目录，并按 session 复用 runnable cache，而不是把所有请求都压到同一个共享工作目录里。
 
 orchestra 主机示例：
 

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.183";
+export declare const AGENT_HARNESS_VERSION = "0.0.184";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.183";
+export const AGENT_HARNESS_VERSION = "0.0.184";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.184",
+  "version": "0.0.185",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",