@botbotgo/agent-harness 0.0.183 → 0.0.185

package/README.md

@@ -42,10 +42,21 @@
 
 **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.
 
-- **Easy to start:** `createAgentHarness` → `run` → `stop`, plus inspection helpers such as `subscribe`, `listSessions`, `listApprovals`, and `resolveApproval`.
+- **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 `runs`, `threads`, `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.
+- **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
 
@@ -55,7 +66,7 @@ If your team already has agents, prompts, tools, and workflows, the missing laye
 
 What you get on day one:
 
-- a runtime that keeps `runs`, `threads`, `approvals`, and `events` as inspectable product records
+- a runtime that keeps `requests`, `sessions`, `approvals`, and `events` as inspectable product records
 - a recovery path that survives interruption, restart, and operator decisions
 - stable run correlation and continuity metadata so operators can join one persisted run to logs, traces, and fallback transitions
 - approval defaults for sensitive durable memory writes and write-like MCP calls instead of relying on each tool definition to remember governance
@@ -74,7 +85,7 @@ Once the demo works, the real software problem changes shape:
 Teams still need clear answers to the runtime questions that appear after that shift:
 
 - how approvals are resolved and audited
-- how runs, threads, and events stay inspectable
+- how requests, sessions, 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
@@ -84,13 +95,13 @@ Teams still need clear answers to the runtime questions that appear after that s
 That makes the product story easier to explain:
 
 - you bring the workspace, agents, tools, and prompts
-- `agent-harness` brings persisted `runs`, `threads`, `approvals`, `events`, recovery, and operator visibility
+- `agent-harness` brings persisted `requests`, `sessions`, `approvals`, `events`, recovery, and operator visibility
 - your application gets one stable runtime contract instead of backend-specific runtime plumbing
 
 In concrete terms:
 
 - a product-facing approval and operator surface instead of backend-specific middleware state
-- persisted `runs`, `threads`, `approvals`, and `events` as stable runtime records
+- persisted `requests`, `sessions`, `approvals`, and `events` as stable runtime records
 - runtime-owned inspection fields such as tracing correlation ids and continuity metadata instead of provider-private observability handles
 - restart-safe recovery and continuation as system-managed behavior
 - default runtime governance for high-risk memory and MCP side effects
@@ -123,17 +134,17 @@ That means:
 
 The runtime provides:
 
-- `createAgentHarness(workspaceRoot)`, `run(...)`, `memorize(...)`, `recall(...)`, `listMemories(...)`, `updateMemory(...)`, `removeMemory(...)`, `resolveApproval(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
+- `createAgentHarness(workspaceRoot)`, `request(...)`, `memorize(...)`, `recall(...)`, `listMemories(...)`, `updateMemory(...)`, `removeMemory(...)`, `resolveApproval(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
 - 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
 
@@ -258,12 +269,12 @@ your-workspace/
 Minimal usage:
 
 ```ts
-import { createAgentHarness, run, stop } from "@botbotgo/agent-harness";
+import { createAgentHarness, request, stop } from "@botbotgo/agent-harness";
 
 const runtime = await createAgentHarness("/absolute/path/to/workspace");
 
 try {
-  const result = await run(runtime, {
+  const result = await request(runtime, {
     agentId: "auto",
     input: "Explain what this workspace is for.",
   });
@@ -277,7 +288,7 @@ try {
 Three-minute mental model:
 
 1. Point `createAgentHarness(...)` at a workspace root.
-2. Call `run(runtime, { ... })` to execute one request.
+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:
@@ -289,7 +300,7 @@ If you want the shortest possible mental model:
 
 - one workspace becomes one runtime
 - YAML defines assembly and policy
-- `run(runtime, { ... })` executes requests against that runtime
+- `request(runtime, { ... })` executes requests against that runtime
 - the runtime owns lifecycle, inspection, and recovery
 
 ## Feature List
@@ -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
@@ -362,9 +373,9 @@ const runtime = await createAgentHarness("/path/to/workspace", {
 ### Run A Request
 
 ```ts
-import { run } from "@botbotgo/agent-harness";
+import { request } from "@botbotgo/agent-harness";
 
-const result = await run(runtime, {
+const result = await request(runtime, {
   agentId: "orchestra",
   input: "Summarize the runtime design.",
   invocation: {
@@ -381,7 +392,7 @@ const result = await run(runtime, {
 });
 ```
 
-`run(runtime, { ... })` creates or continues a persisted session and returns `sessionId`, `requestId`, `state`, and compact text `output`. Richer upstream result shapes stay available through `outputContent`, `contentBlocks`, and `structuredResponse`.
+`request(runtime, { ... })` creates or continues a persisted session and returns `sessionId`, `requestId`, `state`, and compact text `output`. Richer upstream result shapes stay available through `outputContent`, `contentBlocks`, and `structuredResponse`.
 
 Use `listRequests(runtime)` and `getRequest(runtime, requestId)` when a product needs a request-centric operations surface such as a review queue or execution dashboard.
 
@@ -398,9 +409,9 @@ For multimodal chat turns, keep the user-visible content in `input`.
 - persistence, replay, and transcript inspection should treat `input` as the source of truth for user-visible multimodal chat content
 
 ```ts
-import { normalizeUserChatInput, run } from "@botbotgo/agent-harness";
+import { normalizeUserChatInput, request } from "@botbotgo/agent-harness";
 
-const result = await run(
+const result = await request(
   runtime,
   {
     agentId: "orchestra",
@@ -415,7 +426,7 @@ const result = await run(
 );
 ```
 
-Use `normalizeUserChatInput(...)` when a product already has chat-style user messages and wants to project one user turn onto the stable `run(..., { input, invocation })` surface without introducing a separate harness-owned chat API.
+Use `normalizeUserChatInput(...)` when a product already has chat-style user messages and wants to project one user turn onto the stable `request(..., { input, invocation })` surface without introducing a separate harness-owned chat API.
 
 ### Store And Recall Durable Runtime Memory
 
@@ -453,7 +464,7 @@ Use `memorize(...)`, `recall(...)`, `listMemories(...)`, `updateMemory(...)`, an
 ### Let The Runtime Route
 
 ```ts
-const result = await run(runtime, {
+const result = await request(runtime, {
   agentId: "auto",
   input: "Inspect the repository and explain the release flow.",
 });
@@ -464,7 +475,7 @@ const result = await run(runtime, {
 ### Stream Output And Events
 
 ```ts
-const result = await run(runtime, {
+const result = await request(runtime, {
   agentId: "orchestra",
   input: "Inspect the workspace and explain the available tools.",
   listeners: {
@@ -487,16 +498,16 @@ const result = await run(runtime, {
 });
 ```
 
-`onUpstreamEvent(...)` preserves the raw upstream event payload. `onUpstreamItem(...)` adds runtime correlation metadata such as `threadId`, `runId`, and the current `agentId`, which is useful for flow-graph capture and delegated sub-agent inspection.
+`onUpstreamEvent(...)` preserves the raw upstream event payload. `onUpstreamItem(...)` adds runtime correlation metadata such as `sessionId`, `requestId`, and the current `agentId`, which is useful for flow-graph capture and delegated sub-agent inspection.
 
 `subscribe(...)` is the read-only observer surface over stored lifecycle events.
 
 The runtime event stream includes:
 
-- `run.created`
-- `run.queued`
-- `run.dequeued`
-- `run.state.changed`
+- `request.created`
+- `request.queued`
+- `request.dequeued`
+- `request.state.changed`
 - `approval.requested`
 - `approval.resolved`
 - `output.delta`
@@ -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:
 
@@ -897,7 +908,7 @@ Primary exports:
 
 - `createAgentHarness`
 - `AgentHarnessRuntime`
-- `run`
+- `request`
 - `resolveApproval`
 - `subscribe`
 - `listRequests`
@@ -909,8 +920,8 @@ Primary exports:
 - `getApproval`
 - `listArtifacts`
 - `getArtifact`
-- `listRunEvents`
-- `exportRunPackage`
+- `listRequestEvents`
+- `exportRequestPackage`
 - `exportSessionPackage`
 - `exportEvaluationBundle`
 - `replayEvaluationBundle`
@@ -945,6 +956,7 @@ ACP transport notes:
 - `serveA2aHttp(runtime)` exposes a minimal A2A-compatible HTTP JSON-RPC bridge plus agent card discovery, mapping `message/send`, `tasks/get`, and `tasks/cancel` onto the existing session/request runtime surface.
 - `serveAgUiHttp(runtime)` exposes a minimal AG-UI-compatible HTTP SSE bridge that projects `run + output.delta + final result` onto `RUN_STARTED`, `TEXT_MESSAGE_*`, and `RUN_FINISHED` events for UI clients.
 - `createRuntimeMcpServer(runtime)` and `serveRuntimeMcpOverStdio(runtime)` expose the persisted runtime control surface itself as MCP tools, including sessions, requests, approvals, artifacts, events, and package export helpers.
-- `exportRunPackage(...)` and `exportSessionPackage(...)` package stable runtime records, transcript, approvals, events, and artifacts for operator tooling without reaching into persistence internals.
+- `listRequestEvents(...)` and `exportRequestPackage(...)` are the request-first inspection helpers.
+- `exportRequestPackage(...)` and `exportSessionPackage(...)` package stable runtime records, transcript, approvals, events, and artifacts for operator tooling without reaching into persistence internals.
 - `runtime/default.governance.remoteMcp` can now deny or allow specific MCP servers, raise approval requirements by transport, and stamp transport-based risk tiers into runtime governance bundles.
 - detailed A2A adapter guidance lives in [`docs/a2a-bridge.md`](docs/a2a-bridge.md)

package/README.zh.md

@@ -42,10 +42,21 @@
 
 **一句话：** 接入面保持很薄，运行时能力整层交付，日常主要工作集中在 **YAML 配置** 与 **扩展**（本地工具、SKILL 包、MCP），而不是反复自建运行时基础设施。
 
-- **容易上手：** `createAgentHarness` → `run` → `stop`，以及 `subscribe`、`listSessions`、`listApprovals`、`resolveApproval` 等查询与控制能力。
+- **容易上手：** `createAgentHarness` → `request` → `stop`，以及 `subscribe`、`listSessions`、`listApprovals`、`resolveApproval` 等查询与控制能力。
 - **配置：** 路由、模型、工具、存储、后端、MCP、恢复与维护写在声明式工作区 YAML 里（见[快速开始](#快速开始)与[如何配置](#如何配置)）。
 - **扩展：** 在 `resources/` 下放置 `tool({...})` 模块与 SKILL 目录，在目录里声明共享工具与 MCP，再由各 agent 按名字白名单启用。
-- **内建运行时：** 持久化 `runs`、`threads`、`approvals` 与 `events`；恢复与排队；流式监听；MCP 接入与对外暴露；LangChain v1 与 DeepAgents 适配——避免每个应用重复造这一层。
+- **内建运行时：** 持久化 `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 自有职责。
 
 ## 我们解决什么问题
 
@@ -55,7 +66,7 @@
 
 第一天就能直接拿到的东西：
 
-- 把 `runs`、`threads`、`approvals`、`events` 作为可查询产品记录保存下来的 runtime
+- 把 `requests`、`sessions`、`approvals`、`events` 作为可查询产品记录保存下来的 runtime
 - 能跨中断、重启和人工决策继续推进的恢复路径
 - 稳定的 run 关联与连续性元数据，让一次持久化运行能和日志、trace、fallback 过程对齐
 - 对敏感 durable memory 写入和写类 MCP 调用默认走审批，而不是把治理责任留给每个工具定义自己记住
@@ -74,7 +85,7 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 团队仍然要正面回答这些运行时问题：
 
 - 审批怎么决策、怎么审计
-- runs、threads、events 怎么稳定可查
+- requests、sessions、events 怎么稳定可查
 - 执行被打断、失败或进程重启后怎么恢复
 - 路由、并发和维护策略怎么保持一致
 - 后端频繁变化时，怎么不让产品模型跟着漂移
@@ -84,13 +95,13 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 换成更直接的产品语言，就是：
 
 - 你负责工作区、agents、tools 和 prompts
-- `agent-harness` 负责持久化 `runs`、`threads`、`approvals`、`events`、恢复能力与运维可见性
+- `agent-harness` 负责持久化 `requests`、`sessions`、`approvals`、`events`、恢复能力与运维可见性
 - 你的应用拿到的是一个稳定的 runtime 契约，而不是一堆 backend 专属的运行时胶水代码
 
 具体来说，就是把这些能力沉到运行时里：
 
 - 面向产品的审批与运维控制面，而不是 backend 专属的中间件状态
-- 稳定持久化的 `runs`、`threads`、`approvals` 与 `events` 记录
+- 稳定持久化的 `requests`、`sessions`、`approvals` 与 `events` 记录
 - 由运行时持有的 tracing correlation id 与 continuity metadata，而不是 provider 私有观测句柄
 - 由系统托管的重启恢复与中断续跑
 - 面向高风险 memory / MCP 副作用的默认治理策略
@@ -123,17 +134,17 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 
 运行时提供：
 
-- `createAgentHarness(workspaceRoot)`、`run(...)`、`memorize(...)`、`recall(...)`、`listMemories(...)`、`updateMemory(...)`、`removeMemory(...)`、`resolveApproval(...)`、`subscribe(...)`、各类查询方法，以及 `stop(...)`
+- `createAgentHarness(workspaceRoot)`、`request(...)`、`memorize(...)`、`recall(...)`、`listMemories(...)`、`updateMemory(...)`、`removeMemory(...)`、`resolveApproval(...)`、`subscribe(...)`、各类查询方法，以及 `stop(...)`
 - 以 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 的执行语义留在上游，同时把产品契约稳定下来
 
@@ -255,12 +266,12 @@ your-workspace/
 最小用法：
 
 ```ts
-import { createAgentHarness, run, stop } from "@botbotgo/agent-harness";
+import { createAgentHarness, request, stop } from "@botbotgo/agent-harness";
 
 const runtime = await createAgentHarness("/absolute/path/to/workspace");
 
 try {
-  const result = await run(runtime, {
+  const result = await request(runtime, {
     agentId: "auto",
     input: "Explain what this workspace is for.",
   });
@@ -274,7 +285,7 @@ try {
 三分钟心智模型：
 
 1. 用 `createAgentHarness(...)` 指向一个 workspace root。
-2. 用 `run(runtime, { ... })` 执行一次请求。
+2. 用 `request(runtime, { ... })` 执行一次请求。
 3. 把持久化的运行时记录当成产品资产，而不是只盯着最终回答。
 
 如果再压缩成最短产品表述，就是：
@@ -286,7 +297,7 @@ try {
 
 - 一个工作区对应一个运行时
 - YAML 定义装配与策略
-- `run(runtime, { ... })` 在该运行时上执行请求
+- `request(runtime, { ... })` 在该运行时上执行请求
 - 运行时负责生命周期、可观测性与恢复
 
 ## 功能列表
@@ -297,7 +308,7 @@ try {
 - LangChain v1 与 DeepAgents 后端适配
 - 自动发现本地工具与 SKILL 包
 - 原生 provider 工具、MCP 工具与工作区本地工具模块
-- 持久化线程、运行、审批、生命周期事件与排队运行
+- 持久化会话、请求、审批、生命周期事件与排队请求
 - 运行时管理的恢复与 checkpoint 维护
 - 运行结果中的结构化输出与多模态内容保留
 - 将 agent 声明的 MCP 服务桥接进来
@@ -358,9 +369,9 @@ const runtime = await createAgentHarness("/path/to/workspace", {
 ### 发起一次运行
 
 ```ts
-import { run } from "@botbotgo/agent-harness";
+import { request } from "@botbotgo/agent-harness";
 
-const result = await run(runtime, {
+const result = await request(runtime, {
   agentId: "orchestra",
   input: "Summarize the runtime design.",
   invocation: {
@@ -377,7 +388,7 @@ const result = await run(runtime, {
 });
 ```
 
-`run(runtime, { ... })` 会创建或延续持久化会话，并返回 `sessionId`、`requestId`、`state` 以及紧凑文本 `output`。更丰富的上游结果形态仍可通过 `outputContent`、`contentBlocks`、`structuredResponse` 等获得。
+`request(runtime, { ... })` 会创建或延续持久化会话，并返回 `sessionId`、`requestId`、`state` 以及紧凑文本 `output`。更丰富的上游结果形态仍可通过 `outputContent`、`contentBlocks`、`structuredResponse` 等获得。
 
 如果产品需要 request 视角的操作界面，例如 review queue 或执行看板，可使用 `listRequests(runtime)` 与 `getRequest(runtime, requestId)`。
 
@@ -425,7 +436,7 @@ const recalled = await recall(runtime, {
 ### 由运行时路由
 
 ```ts
-const result = await run(runtime, {
+const result = await request(runtime, {
   agentId: "auto",
   input: "Inspect the repository and explain the release flow.",
 });
@@ -436,7 +447,7 @@ const result = await run(runtime, {
 ### 流式输出与事件
 
 ```ts
-const result = await run(runtime, {
+const result = await request(runtime, {
   agentId: "orchestra",
   input: "Inspect the workspace and explain the available tools.",
   listeners: {
@@ -457,10 +468,10 @@ const result = await run(runtime, {
 
 运行时事件流包括：
 
-- `run.created`
-- `run.queued`
-- `run.dequeued`
-- `run.state.changed`
+- `request.created`
+- `request.queued`
+- `request.dequeued`
+- `request.state.changed`
 - `approval.requested`
 - `approval.resolved`
 - `output.delta`
@@ -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 主机示例：
 
@@ -856,7 +867,7 @@ spec:
 
 - `createAgentHarness`
 - `AgentHarnessRuntime`
-- `run`
+- `request`
 - `resolveApproval`
 - `subscribe`
 - `listRequests`
@@ -868,8 +879,8 @@ spec:
 - `getApproval`
 - `listArtifacts`
 - `getArtifact`
-- `listRunEvents`
-- `exportRunPackage`
+- `listRequestEvents`
+- `exportRequestPackage`
 - `exportSessionPackage`
 - `exportEvaluationBundle`
 - `replayEvaluationBundle`
@@ -904,6 +915,7 @@ ACP transport 说明：
 - `serveA2aHttp(runtime)` 提供最小可用的 A2A HTTP JSON-RPC bridge 与 agent card discovery，把 `message/send`、`tasks/get`、`tasks/cancel` 映射到现有 session/request runtime surface。
 - `serveAgUiHttp(runtime)` 提供最小可用的 AG-UI HTTP SSE bridge，把现有 `run + output.delta + final result` 投影成 `RUN_STARTED`、`TEXT_MESSAGE_*` 与 `RUN_FINISHED` 事件，便于 UI 客户端直接接入。
 - `createRuntimeMcpServer(runtime)` 与 `serveRuntimeMcpOverStdio(runtime)` 会把持久化 runtime 控制面本身暴露成 MCP tools，包括 sessions、requests、approvals、artifacts、events 与 package export helpers。
-- `exportRunPackage(...)` 与 `exportSessionPackage(...)` 可把稳定 runtime 记录、transcript、approvals、events 和 artifacts 打包给 operator tooling，而不必直接访问 persistence 内部实现。
+- `listRequestEvents(...)` 与 `exportRequestPackage(...)` 是 request-first 的检查 helper。
+- `exportRequestPackage(...)` 与 `exportSessionPackage(...)` 可把稳定 runtime 记录、transcript、approvals、events 和 artifacts 打包给 operator tooling，而不必直接访问 persistence 内部实现。
 - `runtime/default.governance.remoteMcp` 现在可以按 MCP server 或 transport 做 allow/deny、审批升级，并把 transport 风险等级写进 runtime governance bundles。
 - 更详细的 A2A 适配层开发说明见 [`docs/a2a-bridge.md`](docs/a2a-bridge.md)

package/dist/acp.d.ts

@@ -1,6 +1,6 @@
 import type { ArtifactRecord, HarnessEvent, RequestRecord, RunOptions, SessionRecord } from "./contracts/types.js";
 import type { AgentHarnessRuntime } from "./runtime/harness.js";
-import { getApproval } from "./api.js";
+import { getApproval, type PublicRunListeners } from "./api.js";
 type JsonRpcId = string | number | null;
 export type AcpJsonRpcRequest = {
     jsonrpc?: "2.0";
@@ -31,8 +31,9 @@ export type AcpArtifact = ArtifactRecord & {
 };
 export type AcpRunRequestParams = Omit<Extract<RunOptions, {
     input: unknown;
-}>, "threadId"> & {
+}>, "threadId" | "listeners"> & {
     sessionId?: string;
+    listeners?: PublicRunListeners;
 };
 export type AcpServerCapabilities = {
     sessions: {

package/dist/acp.js

@@ -1,4 +1,4 @@
-import { getApproval, getArtifact, getRequest, getSession, listApprovals, listArtifacts, listRequests, listSessions, resolveApproval, run, } from "./api.js";
+import { getApproval, getArtifact, getRequest, getSession, listApprovals, listArtifacts, listRequests, listSessions, request, resolveApproval, } from "./api.js";
 const CAPABILITIES = {
     sessions: { list: true, get: true },
     requests: { submit: true, list: true, get: true },
@@ -146,7 +146,7 @@ export class AgentHarnessAcpServer {
             }
             case "requests.submit": {
                 const payload = asObject(params, method);
-                return run(this.runtime, {
+                return request(this.runtime, {
                     agentId: readOptionalString(payload.agentId),
                     input: payload.input,
                     invocation: payload.invocation,

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import type { ArtifactListing, CancelOptions, InvocationEnvelope, ListMemoriesInput, ListMemoriesResult, MemoryRecord, MemorizeInput, MemorizeResult, MessageContent, RecallInput, RecallResult, RemoveMemoryInput, RequestRecord, RequestSummary, ResumeOptions, RunDecisionOptions, RunResult, RunStartOptions, RuntimeHealthSnapshot, RuntimeAdapterOptions, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult, RuntimeRunPackage, RuntimeRunPackageInput, RuntimeSessionPackage, RuntimeSessionPackageInput, SessionRecord, SessionSummary, UpdateMemoryInput, WorkspaceLoadOptions } from "./contracts/types.js";
+import type { ArtifactListing, CancelOptions, InvocationEnvelope, ListMemoriesInput, ListMemoriesResult, MemoryRecord, MemorizeInput, MemorizeResult, MessageContent, RecallInput, RecallResult, RemoveMemoryInput, RequestRecord, RequestSummary, ResumeOptions, RunDecisionOptions, RunListeners, RunResult, RunStartOptions, RuntimeHealthSnapshot, RuntimeAdapterOptions, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult as InternalRuntimeEvaluationReplayResult, RuntimeSessionPackage, RuntimeSessionPackageInput, SessionRecord, SessionSummary, TranscriptMessage, UpdateMemoryInput, WorkspaceLoadOptions } from "./contracts/types.js";
 import { AgentHarnessRuntime } from "./runtime/harness.js";
 import type { InventoryAgentRecord, InventorySkillRecord } from "./runtime/harness/system/inventory.js";
 import type { RequirementAssessmentOptions } from "./runtime/harness/system/skill-requirements.js";
@@ -8,12 +8,36 @@ export type { AcpApproval, AcpArtifact, AcpEventNotification, AcpJsonRpcError, A
 export { AgentHarnessRuntime } from "./runtime/harness.js";
 export { buildFlowGraph, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid } from "./flow/index.js";
 export { createUpstreamTimelineReducer } from "./upstream-events.js";
-export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult, RuntimeRunPackage, RuntimeRunPackageInput, RuntimeSessionPackage, RuntimeSessionPackageInput, UpdateMemoryInput, } from "./contracts/types.js";
+export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeSessionPackageInput, RuntimeSessionPackage, UpdateMemoryInput, } from "./contracts/types.js";
 export type { AcpHttpServer, AcpHttpServerOptions } from "./protocol/acp/http.js";
 export type { A2aAgentCard, A2aHttpServer, A2aHttpServerOptions, A2aTask, A2aTaskState } from "./protocol/a2a/http.js";
 export type { AcpStdioServer, AcpStdioServerOptions } from "./protocol/acp/stdio.js";
 export type { AgUiEvent, AgUiHttpServer, AgUiHttpServerOptions, AgUiRunAgentInput } from "./protocol/ag-ui/http.js";
-type PublicApprovalRecord = {
+export type RequestEventType = "request.created" | "request.queued" | "request.dequeued" | "request.state.changed" | "request.resumed" | Exclude<NonNullable<RunListeners["onEvent"]> extends (event: infer T) => unknown ? T extends {
+    eventType: infer E;
+} ? E : never : never, "run.created" | "run.queued" | "run.dequeued" | "run.state.changed" | "run.resumed"> | (string & {});
+export type RequestEvent = {
+    eventId: string;
+    eventType: RequestEventType;
+    timestamp: string;
+    sessionId: string;
+    requestId: string;
+    sequence: number;
+    source: "runtime" | "policy" | "surface" | "worker";
+    payload: Record<string, unknown>;
+};
+export type RequestUpstreamEventItem = {
+    sessionId: string;
+    requestId: string;
+    agentId: string;
+    event: unknown;
+};
+export type PublicRunListeners = {
+    onEvent?: (event: RequestEvent) => void | Promise<void>;
+    onUpstreamEvent?: RunListeners["onUpstreamEvent"];
+    onUpstreamItem?: (item: RequestUpstreamEventItem) => void | Promise<void>;
+};
+export type Approval = {
     approvalId: string;
     pendingActionId: string;
     sessionId: string;
@@ -25,23 +49,49 @@ type PublicApprovalRecord = {
     allowedDecisions: Array<"approve" | "edit" | "reject">;
     inputPreview: Record<string, unknown>;
 };
+export type RequestArtifactListing = Omit<ArtifactListing, "threadId" | "runId"> & {
+    sessionId: string;
+    requestId: string;
+};
+export type RequestPackageInput = {
+    sessionId: string;
+    requestId: string;
+    includeArtifacts?: boolean;
+    includeArtifactContents?: boolean;
+    includeRuntimeHealth?: boolean;
+};
+export type RequestPackage = {
+    session: SessionRecord | null;
+    request: RequestRecord | null;
+    approvals: Approval[];
+    transcript: TranscriptMessage[];
+    events: RequestEvent[];
+    artifacts: RequestArtifactListing["items"];
+    runtimeHealth?: RuntimeHealthSnapshot;
+};
+export type RuntimeEvaluationReplayResult = Omit<InternalRuntimeEvaluationReplayResult, "result"> & {
+    result: PublicRunResult;
+};
 type PublicApprovalFilter = {
-    status?: PublicApprovalRecord["status"];
+    status?: Approval["status"];
     sessionId?: string;
     requestId?: string;
 };
-type PublicRunStartOptions = Omit<RunStartOptions, "threadId"> & {
+type PublicRunStartOptions = Omit<RunStartOptions, "threadId" | "listeners"> & {
     sessionId?: string;
+    listeners?: PublicRunListeners;
 };
-type PublicRunDecisionOptions = Omit<RunDecisionOptions, "threadId" | "runId"> & {
+type PublicRunDecisionOptions = Omit<RunDecisionOptions, "threadId" | "runId" | "listeners"> & {
     sessionId: string;
     requestId?: string;
+    listeners?: PublicRunListeners;
 };
 type PublicRunOptions = PublicRunStartOptions | PublicRunDecisionOptions;
 type PublicRunResult = Omit<RunResult, "threadId" | "runId"> & {
     sessionId: string;
     requestId: string;
 };
+export type RequestResult = PublicRunResult;
 export type UserChatMessage = {
     role: "user";
     content: MessageContent;
@@ -61,13 +111,13 @@ type CreateAgentHarnessOptions = {
 export declare function createAgentHarness(): Promise<AgentHarnessRuntime>;
 export declare function createAgentHarness(workspaceRoot: string, options?: CreateAgentHarnessOptions): Promise<AgentHarnessRuntime>;
 export declare function normalizeUserChatInput(input: UserChatInput, options?: NormalizeUserChatInputOptions): Pick<RunStartOptions, "input" | "invocation">;
-export declare function run(runtime: AgentHarnessRuntime, options: PublicRunOptions): Promise<PublicRunResult>;
+export declare function request(runtime: AgentHarnessRuntime, options: PublicRunOptions): Promise<PublicRunResult>;
 export declare function memorize(runtime: AgentHarnessRuntime, input: MemorizeInput): Promise<MemorizeResult>;
 export declare function recall(runtime: AgentHarnessRuntime, input: RecallInput): Promise<RecallResult>;
 export declare function listMemories(runtime: AgentHarnessRuntime, input?: ListMemoriesInput): Promise<ListMemoriesResult>;
 export declare function updateMemory(runtime: AgentHarnessRuntime, input: UpdateMemoryInput): Promise<MemoryRecord>;
 export declare function removeMemory(runtime: AgentHarnessRuntime, input: RemoveMemoryInput): Promise<MemoryRecord>;
-export declare function subscribe(runtime: AgentHarnessRuntime, listener: Parameters<AgentHarnessRuntime["subscribe"]>[0]): () => void;
+export declare function subscribe(runtime: AgentHarnessRuntime, listener: (event: RequestEvent) => void | Promise<void>): () => void;
 export declare function listSessions(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listThreads"]>[0]): Promise<SessionSummary[]>;
 export declare function listRequests(runtime: AgentHarnessRuntime, filter?: {
     agentId?: string;
@@ -77,23 +127,23 @@ export declare function listRequests(runtime: AgentHarnessRuntime, filter?: {
 export declare function getSession(runtime: AgentHarnessRuntime, sessionId: string): Promise<SessionRecord | null>;
 export declare function getRequest(runtime: AgentHarnessRuntime, requestId: string): Promise<RequestRecord | null>;
 export declare function deleteSession(runtime: AgentHarnessRuntime, sessionId: string): Promise<boolean>;
-export declare function listApprovals(runtime: AgentHarnessRuntime, filter?: PublicApprovalFilter): Promise<PublicApprovalRecord[]>;
-export declare function getApproval(runtime: AgentHarnessRuntime, approvalId: string): Promise<PublicApprovalRecord | null>;
+export declare function listApprovals(runtime: AgentHarnessRuntime, filter?: PublicApprovalFilter): Promise<Approval[]>;
+export declare function getApproval(runtime: AgentHarnessRuntime, approvalId: string): Promise<Approval | null>;
 export declare function listArtifacts(runtime: AgentHarnessRuntime, input: {
     sessionId: string;
     requestId: string;
-}): Promise<ArtifactListing>;
+}): Promise<RequestArtifactListing>;
 export declare function getArtifact(runtime: AgentHarnessRuntime, input: {
     sessionId: string;
     requestId: string;
     artifactPath: string;
 }): Promise<unknown>;
-export declare function listRunEvents(runtime: AgentHarnessRuntime, input: {
+export declare function listRequestEvents(runtime: AgentHarnessRuntime, input: {
     sessionId: string;
     requestId: string;
-}): Promise<import("./contracts/runtime.js").HarnessEvent[]>;
+}): Promise<RequestEvent[]>;
 export declare function getHealth(runtime: AgentHarnessRuntime): Promise<RuntimeHealthSnapshot>;
-export declare function exportRunPackage(runtime: AgentHarnessRuntime, input: RuntimeRunPackageInput): Promise<RuntimeRunPackage>;
+export declare function exportRequestPackage(runtime: AgentHarnessRuntime, input: RequestPackageInput): Promise<RequestPackage>;
 export declare function exportSessionPackage(runtime: AgentHarnessRuntime, input: RuntimeSessionPackageInput): Promise<RuntimeSessionPackage>;
 export declare function exportEvaluationBundle(runtime: AgentHarnessRuntime, input: RuntimeEvaluationExportInput): Promise<RuntimeEvaluationExport>;
 export declare function replayEvaluationBundle(runtime: AgentHarnessRuntime, input: RuntimeEvaluationReplayInput): Promise<RuntimeEvaluationReplayResult>;
@@ -113,7 +163,7 @@ export declare function resolveApproval(runtime: AgentHarnessRuntime, options: R
 }): Promise<PublicRunResult>;
 export declare function cancelRun(runtime: AgentHarnessRuntime, options: CancelOptions & {
     requestId?: string;
-}): Promise<RunResult>;
+}): Promise<PublicRunResult>;
 export declare function stop(runtime: AgentHarnessRuntime): Promise<void>;
 export declare function createToolMcpServer(runtime: AgentHarnessRuntime, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;
 export declare function serveToolsOverStdio(runtime: AgentHarnessRuntime, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;

package/dist/api.js

@@ -71,6 +71,69 @@ function toApprovalRecord(record) {
         inputPreview: record.inputPreview,
     };
 }
+function toPublicEventType(eventType) {
+    switch (eventType) {
+        case "run.created":
+            return "request.created";
+        case "run.queued":
+            return "request.queued";
+        case "run.dequeued":
+            return "request.dequeued";
+        case "run.state.changed":
+            return "request.state.changed";
+        case "run.resumed":
+            return "request.resumed";
+        default:
+            return eventType;
+    }
+}
+function toPublicEvent(event) {
+    return {
+        eventId: event.eventId,
+        eventType: toPublicEventType(event.eventType),
+        timestamp: event.timestamp,
+        sessionId: event.threadId,
+        requestId: event.runId,
+        sequence: event.sequence,
+        source: event.source,
+        payload: event.payload,
+    };
+}
+function toPublicRunListeners(listeners) {
+    if (!listeners) {
+        return undefined;
+    }
+    return {
+        onEvent: listeners.onEvent ? async (event) => listeners.onEvent(toPublicEvent(event)) : undefined,
+        onUpstreamEvent: listeners.onUpstreamEvent,
+        onUpstreamItem: listeners.onUpstreamItem
+            ? async (item) => listeners.onUpstreamItem({
+                sessionId: item.threadId,
+                requestId: item.runId,
+                agentId: item.agentId,
+                event: item.event,
+            })
+            : undefined,
+    };
+}
+function toRequestArtifactListing(listing) {
+    return {
+        sessionId: listing.threadId,
+        requestId: listing.runId,
+        items: listing.items,
+    };
+}
+function toRequestPackage(pkg) {
+    return {
+        session: pkg.session,
+        request: pkg.request,
+        approvals: pkg.approvals.map(toApprovalRecord),
+        transcript: pkg.transcript,
+        events: pkg.events.map(toPublicEvent),
+        artifacts: pkg.artifacts,
+        ...(pkg.runtimeHealth ? { runtimeHealth: pkg.runtimeHealth } : {}),
+    };
+}
 function toPublicRunResult(result) {
     return {
         sessionId: result.threadId,
@@ -96,7 +159,7 @@ function toInternalRunOptions(options) {
             approvalId: options.approvalId,
             decision: options.decision,
             editedInput: options.editedInput,
-            listeners: options.listeners,
+            listeners: toPublicRunListeners(options.listeners),
             runId: options.requestId,
             threadId: options.sessionId,
         };
@@ -105,7 +168,7 @@ function toInternalRunOptions(options) {
         agentId: options.agentId,
         input: options.input,
         invocation: options.invocation,
-        listeners: options.listeners,
+        listeners: toPublicRunListeners(options.listeners),
         priority: options.priority,
         threadId: options.sessionId,
     };
@@ -131,7 +194,7 @@ export function normalizeUserChatInput(input, options = {}) {
         : normalizeMessageContent(input);
     return options.invocation ? { input: content, invocation: options.invocation } : { input: content };
 }
-export async function run(runtime, options) {
+export async function request(runtime, options) {
     return toPublicRunResult(await runtime.run(toInternalRunOptions(options)));
 }
 export async function memorize(runtime, input) {
@@ -150,7 +213,9 @@ export async function removeMemory(runtime, input) {
     return runtime.removeMemory(input);
 }
 export function subscribe(runtime, listener) {
-    return runtime.subscribe(listener);
+    return runtime.subscribe(async (event) => {
+        await listener(toPublicEvent(event));
+    });
 }
 export async function listSessions(runtime, filter) {
     return (await runtime.listThreads(filter)).map(toSessionSummary);
@@ -185,19 +250,19 @@ export async function getApproval(runtime, approvalId) {
     return record ? toApprovalRecord(record) : null;
 }
 export async function listArtifacts(runtime, input) {
-    return runtime.listArtifacts(input.sessionId, input.requestId);
+    return toRequestArtifactListing(await runtime.listArtifacts(input.sessionId, input.requestId));
 }
 export async function getArtifact(runtime, input) {
     return runtime.readArtifact(input.sessionId, input.requestId, input.artifactPath);
 }
-export async function listRunEvents(runtime, input) {
-    return runtime.listRunEvents(input.sessionId, input.requestId);
+export async function listRequestEvents(runtime, input) {
+    return (await runtime.listRunEvents(input.sessionId, input.requestId)).map(toPublicEvent);
 }
 export async function getHealth(runtime) {
     return runtime.getHealth();
 }
-export async function exportRunPackage(runtime, input) {
-    return runtime.exportRunPackage(input);
+export async function exportRequestPackage(runtime, input) {
+    return toRequestPackage(await runtime.exportRunPackage(input));
 }
 export async function exportSessionPackage(runtime, input) {
     return runtime.exportSessionPackage(input);
@@ -206,7 +271,11 @@ export async function exportEvaluationBundle(runtime, input) {
     return runtime.exportEvaluationBundle(input);
 }
 export async function replayEvaluationBundle(runtime, input) {
-    return runtime.replayEvaluationBundle(input);
+    const replayed = await runtime.replayEvaluationBundle(input);
+    return {
+        ...replayed,
+        result: toPublicRunResult(replayed.result),
+    };
 }
 export function serveAcpStdio(runtime, options) {
     return serveAcpOverStdio(runtime, options);
@@ -233,10 +302,10 @@ export async function resolveApproval(runtime, options) {
     return toPublicRunResult(await runtime.resume(toInternalResumeOptions(options)));
 }
 export async function cancelRun(runtime, options) {
-    return runtime.cancelRun({
+    return toPublicRunResult(await runtime.cancelRun({
         ...options,
         runId: options.requestId ?? options.runId,
-    });
+    }));
 }
 export async function stop(runtime) {
     return runtime.stop();

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportRunPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, listRunEvents, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
+export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportRequestPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listRequestEvents, listSessions, memorize, normalizeUserChatInput, request, recall, removeMemory, resolveApproval, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
 export type { AcpApproval, AcpArtifact, AcpEventNotification, AcpJsonRpcError, AcpJsonRpcRequest, AcpJsonRpcResponse, AcpJsonRpcSuccess, AcpRequestRecord, AcpRunRequestParams, AcpServerCapabilities, AcpSessionRecord, } from "./acp.js";
-export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult, RuntimeRunPackage, RuntimeRunPackageInput, RuntimeSessionPackage, RuntimeSessionPackageInput, UpdateMemoryInput, UserChatInput, UserChatMessage, } from "./api.js";
+export type { Approval, ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, PublicRunListeners, RequestArtifactListing, RequestEvent, RequestEventType, RequestPackage, RequestPackageInput, RequestResult, RequestUpstreamEventItem, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult, RuntimeSessionPackage, RuntimeSessionPackageInput, UpdateMemoryInput, UserChatInput, UserChatMessage, } from "./api.js";
 export type { BuildFlowGraphInput, FlowEdge, FlowEdgeKind, FlowGraph, FlowGraphMermaidOptions, FlowGraphSequenceMermaidOptions, FlowGroup, FlowGroupKind, FlowNode, FlowNodeKind, FlowNodeLayer, FlowNodeStatus, } from "./flow/index.js";
 export type { A2aAgentCard, A2aHttpServer, A2aHttpServerOptions, A2aTask, A2aTaskState, AcpHttpServer, AcpHttpServerOptions, AcpStdioServer, AcpStdioServerOptions, AgUiEvent, AgUiHttpServer, AgUiHttpServerOptions, AgUiRunAgentInput, } from "./api.js";
 export type { RuntimeMcpServerOptions, ToolMcpServerOptions } from "./mcp.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportRunPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, listRunEvents, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
+export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportRequestPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listRequestEvents, listSessions, memorize, normalizeUserChatInput, request, recall, removeMemory, resolveApproval, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
 export { tool } from "./tools.js";

package/dist/init-project.js

@@ -294,7 +294,7 @@ function renderRunScript(options) {
         ? "Research the latest model and tooling trends for AI product teams. Return a concise brief with sources and caveats."
         : "Analyze the current architecture direction for this product and return a concise brief with assumptions and caveats.";
     return `import { fileURLToPath } from "node:url";
-import { createAgentHarness, run, stop } from "@botbotgo/agent-harness";
+import { createAgentHarness, request, stop } from "@botbotgo/agent-harness";
 
 const appRoot = fileURLToPath(new URL("..", import.meta.url));
 const args = process.argv.slice(2);
@@ -321,7 +321,7 @@ const input = inputParts.join(" ").trim() ||
 const runtime = await createAgentHarness(appRoot);
 
 try {
-  const result = await run(runtime, {
+  const result = await request(runtime, {
     agentId: requestedAgentId,
     input,
   });

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { ApprovalRecord, ArtifactListing, CompiledTool, HarnessEvent, ParsedToolObject, RunResult, RunState, RunSummary, RuntimeRunPackage, RuntimeRunPackageInput, RuntimeSessionPackage, RuntimeSessionPackageInput, ThreadRecord, ThreadSummary } from "./contracts/types.js";
+import type { ApprovalRecord, ArtifactListing, CompiledTool, HarnessEvent, ParsedToolObject, RunResult, RunState, RunSummary, RuntimeSessionPackage, RuntimeSessionPackageInput, ThreadRecord, ThreadSummary } from "./contracts/types.js";
 export type ToolMcpServerOptions = {
     agentId: string;
     serverInfo?: {
@@ -45,8 +45,14 @@ type RuntimeMcpRuntime = {
     }) => Promise<RunResult>;
     listArtifacts: (threadId: string, runId: string) => Promise<ArtifactListing>;
     readArtifact: (threadId: string, runId: string, artifactPath: string) => Promise<unknown>;
-    listRunEvents: (threadId: string, runId: string) => Promise<HarnessEvent[]>;
-    exportRunPackage: (input: RuntimeRunPackageInput) => Promise<RuntimeRunPackage>;
+    listRunEvents: (sessionId: string, requestId: string) => Promise<HarnessEvent[]>;
+    exportRunPackage: (input: {
+        sessionId: string;
+        requestId: string;
+        includeArtifacts?: boolean;
+        includeArtifactContents?: boolean;
+        includeRuntimeHealth?: boolean;
+    }) => Promise<unknown>;
     exportSessionPackage: (input: RuntimeSessionPackageInput) => Promise<RuntimeSessionPackage>;
 };
 export declare function createToolMcpServerFromTools(tools: ToolMcpServerTool[], options: ToolMcpServerOptions): Promise<McpServer>;

package/dist/mcp.js

@@ -212,7 +212,7 @@ export async function createRuntimeMcpServer(runtime, options = {}) {
                 text: renderToolOutput(await runtime.readArtifact(input.sessionId, input.requestId, input.artifactPath)),
             }],
     }));
-    server.tool("list_run_events", "List persisted runtime events for one request.", {
+    server.tool("list_request_events", "List persisted runtime events for one request.", {
         sessionId: z.string(),
         requestId: z.string(),
     }, async (input) => ({
@@ -221,7 +221,7 @@ export async function createRuntimeMcpServer(runtime, options = {}) {
                 text: renderToolOutput(await runtime.listRunEvents(input.sessionId, input.requestId)),
             }],
     }));
-    server.tool("export_run_package", "Export a stable runtime run package for one request.", {
+    server.tool("export_request_package", "Export a stable runtime request package for one request.", {
         sessionId: z.string(),
         requestId: z.string(),
         includeArtifacts: z.boolean().optional(),

package/dist/package-version.d.ts

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

package/dist/package-version.js

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

package/package.json

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