@botbotgo/agent-harness 0.0.251 → 0.0.253

package/README.md

@@ -580,14 +580,14 @@ const result = await request(runtime, {
     onUpstreamEvent(event) {
       console.log("raw upstream event", event);
     },
-    onUpstreamItem(item) {
+    onTraceItem(item) {
       console.log("upstream agent", item.agentId, item.event);
     },
   },
 });
 ```
 
-`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.
+`onUpstreamEvent(...)` preserves the raw upstream event payload. `onTraceItem(...)` 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.
 
@@ -703,6 +703,8 @@ Discovery rules:
 Example workspaces:
 
 - `examples/hello-skill-app/` keeps the smallest local tool + skill workspace
+- `examples/multimodal-app/` keeps the smallest image-plus-PDF example and sends both through one `request(...)` call
+- `examples/plan-and-run-app/` keeps the smallest public-API planning example and prints both the plan and the observed execution steps
 - `examples/runtime-flow-demo/` runs one real hosted-model request and exports a Mermaid flowchart from runtime plus upstream events
 - `examples/protocol-hello-world/` shows the same minimal direct agent wired to ACP, A2A, and AG-UI hello-world transport samples
 
@@ -835,11 +837,8 @@ spec:
     path: store.sqlite
   - kind: Checkpointer
     name: default
-    checkpointerKind: MemorySaver
-  - kind: Checkpointer
-    name: sqlite
-    checkpointerKind: SqliteSaver
-    path: checkpoints.sqlite
+    checkpointerKind: FileCheckpointer
+    path: checkpoints.json
 ```
 
 ### `config/runtime/runtime-memory.yaml`
@@ -1017,6 +1016,7 @@ Primary exports:
 - `listArtifacts`
 - `getArtifact`
 - `listRequestEvents`
+- `listRequestTraceItems`
 - `exportRequestPackage`
 - `exportSessionPackage`
 - `exportEvaluationBundle`
@@ -1033,16 +1033,15 @@ Primary exports:
 - `serveToolsOverStdio`
 - `stop`
 - `createUpstreamTimelineReducer`
-- `buildFlowGraph`
-- `exportFlowGraphToMermaid`
-- `exportFlowGraphToSequenceMermaid`
+- `exportFlow`
+- `exportSequence`
 
 Inspection helpers:
 
 - `createUpstreamTimelineReducer()` reduces raw upstream model/tool/chain events into ordered step-like projections for inspection and visualization.
-- `buildFlowGraph(...)` combines persisted runtime timeline items with optional upstream projections into a detailed flow graph utility shape, including best-effort delegated subagent transitions when raw upstream events are available.
-- `exportFlowGraphToMermaid(...)` renders that inspection graph as Mermaid flowchart text. By default it emits the product view: agent and sub-agent delegation plus user-defined model, tool, and skill calls. Use `view: "debug"` to include runtime inspection detail.
-- `exportFlowGraphToSequenceMermaid(...)` renders the same inspection graph as a Mermaid sequence diagram. By default it emits only user-defined participants and calls, while `view: "debug"` includes runtime participants and lifecycle messages.
+- `listRequestTraceItems(runtime, { sessionId, requestId })` returns the persisted request trace items that back runtime diagrams and post-run inspection. Each trace item carries the normalized runtime surface record plus the source upstream event.
+- `exportFlow(runtime, { sessionId, requestId })` loads one persisted request record from the runtime and renders it as Mermaid flowchart text. It uses the built-in product view defaults for direction, grouping, and visible kinds so callers do not need to carry visualization options in normal product code.
+- `exportSequence(runtime, { sessionId, requestId })` loads the same persisted request record and renders it as a Mermaid sequence diagram for the same persisted trace-backed request.
 
 These helpers are visualization and inspection utilities. They do not introduce a canonical harness-owned execution protocol.
 
@@ -1055,7 +1054,7 @@ ACP transport notes:
 - `serveA2aHttp(runtime)` exposes an A2A-compatible HTTP JSON-RPC bridge plus agent card discovery, mapping both existing methods such as `message/send` and A2A v1.0 PascalCase methods such as `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, `GetExtendedAgentCard`, and task push-notification config methods onto the existing session/request runtime surface. The bridge now advertises both `1.0` and `0.3` JSON-RPC interfaces, sets `capabilities.streaming = true` plus `capabilities.pushNotifications = true`, validates `A2A-Version`, records `A2A-Extensions` into runtime invocation metadata, publishes `TASK_STATE_*` statuses plus the `{ task }` `SendMessage` wrapper, streams an initial `{ task }` snapshot plus later `{ statusUpdate }` payloads over SSE for v1 streaming methods, and can send best-effort webhook task snapshots for configured push notification receivers.
 - `serveAgUiHttp(runtime)` exposes an AG-UI-compatible HTTP SSE bridge that projects runtime lifecycle, text output, upstream thinking, step progress, and tool calls onto `RUN_*`, `TEXT_MESSAGE_*`, `THINKING_TEXT_MESSAGE_*`, `STEP_*`, and `TOOL_CALL_*` 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.
-- `listRequestEvents(...)` and `exportRequestPackage(...)` are the request-first inspection helpers.
+- `listRequestEvents(...)`, `listRequestTraceItems(...)`, and `exportRequestPackage(...)` are the request-first inspection helpers.
 - `exportRequestPackage(...)` and `exportSessionPackage(...)` package stable runtime records, transcript, approvals, events, artifacts, and governance evidence 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. MCP server catalogs can also declare trust tier, access mode, tenant scope, approval policy, prompt-injection risk, and OAuth scope metadata so governance bundles capture why one remote tool is treated as high-risk.
 - Protocol responsibilities stay split on purpose: ACP is the primary editor/client runtime boundary, A2A is the streaming-capable agent-platform bridge with polling compatibility, AG-UI is the UI event surface, and runtime MCP is the operator-facing control plane exported as MCP tools.

package/README.zh.md

@@ -666,6 +666,8 @@ await stop(runtime);
 示例工作区：
 
 - `examples/hello-skill-app/` 保留最小的本地 tool + skill 工作区
+- `examples/multimodal-app/` 保留最小的图片 + PDF 示例，并通过一次 `request(...)` 调用发送
+- `examples/plan-and-run-app/` 保留最小的公开 API 规划示例，并同时打印规划步骤和真实执行步骤
 - `examples/runtime-flow-demo/` 会跑一次真实 hosted model 请求，并把 runtime 与 upstream events 导出为 Mermaid flowchart
 - `examples/protocol-hello-world/` 展示同一个最小 direct agent 的 ACP、A2A 与 AG-UI 三种 hello-world 传输示例
 
@@ -795,11 +797,8 @@ spec:
     path: store.sqlite
   - kind: Checkpointer
     name: default
-    checkpointerKind: MemorySaver
-  - kind: Checkpointer
-    name: sqlite
-    checkpointerKind: SqliteSaver
-    path: checkpoints.sqlite
+    checkpointerKind: FileCheckpointer
+    path: checkpoints.json
 ```
 
 ### `config/runtime/runtime-memory.yaml`
@@ -975,6 +974,7 @@ spec:
 - `listArtifacts`
 - `getArtifact`
 - `listRequestEvents`
+- `listRequestTraceItems`
 - `exportRequestPackage`
 - `exportSessionPackage`
 - `exportEvaluationBundle`
@@ -991,16 +991,15 @@ spec:
 - `serveToolsOverStdio`
 - `stop`
 - `createUpstreamTimelineReducer`
-- `buildFlowGraph`
-- `exportFlowGraphToMermaid`
-- `exportFlowGraphToSequenceMermaid`
+- `exportFlow`
+- `exportSequence`
 
 Inspection 辅助工具：
 
 - `createUpstreamTimelineReducer()` 可把上游 model/tool/chain 原始事件归约成有序的 step-like 投影，便于检查和可视化。
-- `buildFlowGraph(...)` 可把持久化 runtime timeline 与可选的 upstream projections 组合成详细 flow graph utility 数据结构；当提供原始 upstream events 时，也会尽力补出 subagent delegation 转移。
-- `exportFlowGraphToMermaid(...)` 可把该 inspection graph 导出为 Mermaid flowchart 文本。默认输出 product 视图，只保留 agent / sub-agent delegation 以及用户定义的 model、tool、skill 调用；传 `view: "debug"` 才会带上 runtime 检查细节。
-- `exportFlowGraphToSequenceMermaid(...)` 可把同一份 inspection graph 导出为 Mermaid sequence diagram。默认只输出用户定义的参与者与调用；传 `view: "debug"` 才会包含 runtime participant 与生命周期消息。
+- `listRequestTraceItems(runtime, { sessionId, requestId })` 可直接读取持久化的 request trace items。这些 trace item 是运行图和运行后检查的基础数据，每条记录都同时带有规范化后的 runtime surface 与来源 upstream event。
+- `exportFlow(runtime, { sessionId, requestId })` 可直接从 runtime 读取单个持久化 request record，并导出成 Mermaid flowchart 文本。它内建产品视图默认值，直接固定方向、分组与可见 kind，调用方不需要再额外传一套可视化参数。
+- `exportSequence(runtime, { sessionId, requestId })` 可从同一份持久化 request record 导出 Mermaid sequence diagram，并与同一份持久化 trace 对齐。
 
 这些 helper 只用于可视化与检查，不代表新的 harness 官方执行协议。
 
@@ -1013,7 +1012,7 @@ ACP transport 说明：
 - `serveA2aHttp(runtime)` 提供 A2A HTTP JSON-RPC bridge 与 agent card discovery，同时兼容 `message/send` 这类旧方法，以及 `SendMessage`、`SendStreamingMessage`、`GetTask`、`ListTasks`、`CancelTask`、`SubscribeToTask`、`GetExtendedAgentCard` 与 task push-notification config 这类 A2A v1.0 方法，并统一映射到现有 session/request 运行记录。bridge 现在会同时声明 `1.0` 与 `0.3` 两个 JSON-RPC interface、把 `capabilities.streaming` 和 `capabilities.pushNotifications` 都设为 `true`、校验 `A2A-Version`、把 `A2A-Extensions` 记录进 runtime invocation metadata、发布 `TASK_STATE_*` 状态与 `SendMessage` 的 `{ task }` wrapper、在 v1 streaming 方法上先通过 SSE 输出 `{ task }` 初始快照，再输出 `{ statusUpdate }` 增量状态，并可向已配置的 webhook receiver 发送 best-effort task push notifications。
 - `serveAgUiHttp(runtime)` 提供 AG-UI HTTP SSE bridge，把 runtime 生命周期、文本输出、upstream thinking、step 进度与 tool call 投影成 `RUN_*`、`TEXT_MESSAGE_*`、`THINKING_TEXT_MESSAGE_*`、`STEP_*` 与 `TOOL_CALL_*` 事件，便于 UI 客户端直接接入。
 - `createRuntimeMcpServer(runtime)` 与 `serveRuntimeMcpOverStdio(runtime)` 会把持久化 runtime 控制面本身暴露成 MCP tools，包括 sessions、requests、approvals、artifacts、events 与 package export helpers。
-- `listRequestEvents(...)` 与 `exportRequestPackage(...)` 是 request-first 的检查 helper。
+- `listRequestEvents(...)`、`listRequestTraceItems(...)` 与 `exportRequestPackage(...)` 是 request-first 的检查 helper。
 - `exportRequestPackage(...)` 与 `exportSessionPackage(...)` 可把稳定 runtime 记录、transcript、approvals、events、artifacts 与 governance evidence 一起打包给管理工具，而不必直接访问 persistence 内部实现。
 - `runtime/default.governance.remoteMcp` 现在可以按 MCP server 或 transport 做 allow/deny、审批升级，并把 transport 风险等级写进 runtime governance bundles。MCP server catalog 也可以声明 trust tier、access mode、tenant scope、approval policy、prompt-injection risk 与 OAuth scope 元数据，让治理快照能解释为什么某个远端工具被视为高风险。
 - 协议分工要继续保持清晰：ACP 是 editor / client 的主运行时边界，A2A 是支持 streaming 且兼容轮询的 agent-platform bridge，AG-UI 是 UI 事件面，runtime MCP 是以 MCP tools 暴露的 operator control plane。

package/dist/api.d.ts

@@ -7,7 +7,6 @@ export { AgentHarnessAcpServer, createAcpServer } from "./acp.js";
 export { createAcpStdioClient } from "./protocol/acp/client.js";
 export type { AcpApproval, AcpArtifact, AcpEventNotification, AcpJsonRpcError, AcpJsonRpcRequest, AcpJsonRpcResponse, AcpJsonRpcSuccess, AcpRequestRecord, AcpRunRequestParams, AcpServerCapabilities, AcpSessionRecord, } from "./acp.js";
 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, SessionListSummary, RuntimeSessionPackageInput, RuntimeSessionPackage, UpdateMemoryInput, } from "./contracts/types.js";
 export type { AcpHttpServer, AcpHttpServerOptions } from "./protocol/acp/http.js";
@@ -28,18 +27,20 @@ export type RequestEvent = {
     source: "runtime" | "policy" | "surface" | "worker";
     payload: Record<string, unknown>;
 };
-export type RequestUpstreamEventItem = {
+export type RequestTraceItem = {
     sessionId: string;
     requestId: string;
-    agentId: string;
-    agentName?: string;
-    surfaceItems?: import("./contracts/types.js").RuntimeSurfaceItem[];
+    surfaceItem: import("./contracts/types.js").RuntimeSurfaceItem;
     event: unknown;
 };
+export type RequestFlowGraphInput = {
+    sessionId: string;
+    requestId: string;
+};
 export type PublicRunListeners = {
     onEvent?: (event: RequestEvent) => void | Promise<void>;
     onUpstreamEvent?: RunListeners["onUpstreamEvent"];
-    onUpstreamItem?: (item: RequestUpstreamEventItem) => void | Promise<void>;
+    onTraceItem?: (item: RequestTraceItem) => void | Promise<void>;
 };
 export type Approval = {
     approvalId: string;
@@ -147,6 +148,8 @@ export declare function listRequests(runtime: AgentHarnessRuntime, filter?: {
 }): Promise<RequestSummary[]>;
 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 exportFlow(runtime: AgentHarnessRuntime, input: RequestFlowGraphInput): Promise<string>;
+export declare function exportSequence(runtime: AgentHarnessRuntime, input: RequestFlowGraphInput): Promise<string>;
 export declare function deleteSession(runtime: AgentHarnessRuntime, sessionId: string): Promise<boolean>;
 export declare function listApprovals(runtime: AgentHarnessRuntime, filter?: PublicApprovalFilter): Promise<Approval[]>;
 export declare function getApproval(runtime: AgentHarnessRuntime, approvalId: string): Promise<Approval | null>;
@@ -163,6 +166,10 @@ export declare function listRequestEvents(runtime: AgentHarnessRuntime, input: {
     sessionId: string;
     requestId: string;
 }): Promise<RequestEvent[]>;
+export declare function listRequestTraceItems(runtime: AgentHarnessRuntime, input: {
+    sessionId: string;
+    requestId: string;
+}): Promise<RequestTraceItem[]>;
 export declare function getHealth(runtime: AgentHarnessRuntime): Promise<RuntimeHealthSnapshot>;
 export declare function getOperatorOverview(runtime: AgentHarnessRuntime, options?: {
     limit?: number;

package/dist/api.js

@@ -1,4 +1,5 @@
 import { AgentHarnessRuntime } from "./runtime/harness.js";
+import { buildFlowGraph, exportFlowGraphToMermaid as exportFlowGraphFromGraph, exportFlowGraphToSequenceMermaid as exportSequenceGraphFromGraph, } from "./flow/index.js";
 import { serveA2aOverHttp } from "./protocol/a2a/http.js";
 import { serveAgUiOverHttp } from "./protocol/ag-ui/http.js";
 import { serveAcpOverHttp } from "./protocol/acp/http.js";
@@ -8,7 +9,6 @@ import { loadWorkspace } from "./workspace/compile.js";
 export { AgentHarnessAcpServer, createAcpServer } from "./acp.js";
 export { createAcpStdioClient } from "./protocol/acp/client.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
-export { buildFlowGraph, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid } from "./flow/index.js";
 export { createUpstreamTimelineReducer } from "./upstream-events.js";
 function toApprovalRecord(record) {
     return {
@@ -53,6 +53,20 @@ function toPublicEvent(event) {
         payload: event.payload,
     };
 }
+function toPublicTraceItem(input) {
+    const typed = typeof input.item === "object" && input.item !== null
+        ? input.item
+        : null;
+    if (!typed?.surfaceItem) {
+        return null;
+    }
+    return {
+        sessionId: input.sessionId,
+        requestId: input.requestId,
+        surfaceItem: typed.surfaceItem,
+        event: typed.event,
+    };
+}
 function toPublicRunListeners(listeners) {
     if (!listeners) {
         return undefined;
@@ -60,13 +74,11 @@ function toPublicRunListeners(listeners) {
     return {
         onEvent: listeners.onEvent ? async (event) => listeners.onEvent(toPublicEvent(event)) : undefined,
         onUpstreamEvent: listeners.onUpstreamEvent,
-        onUpstreamItem: listeners.onUpstreamItem
-            ? async (item) => listeners.onUpstreamItem({
+        onTraceItem: listeners.onTraceItem
+            ? async (item) => listeners.onTraceItem({
                 sessionId: item.threadId,
                 requestId: item.runId,
-                agentId: item.agentId,
-                agentName: item.agentName,
-                surfaceItems: item.surfaceItems,
+                surfaceItem: item.surfaceItem,
                 event: item.event,
             })
             : undefined,
@@ -210,6 +222,42 @@ export async function getSession(runtime, sessionId) {
 export async function getRequest(runtime, requestId) {
     return runtime.getRequest(requestId);
 }
+async function buildRequestFlowGraph(runtime, input) {
+    const request = await runtime.getRequest(input.requestId);
+    if (!request) {
+        throw new Error(`Request ${input.requestId} was not found.`);
+    }
+    if (request.sessionId !== input.sessionId) {
+        throw new Error(`Request ${input.requestId} belongs to session ${request.sessionId}, not ${input.sessionId}.`);
+    }
+    const traceItems = (request.traceItems ?? [])
+        .map((item) => toPublicTraceItem({
+        sessionId: input.sessionId,
+        requestId: input.requestId,
+        item,
+    }))
+        .filter((item) => item !== null);
+    return buildFlowGraph({
+        sessionId: input.sessionId,
+        requestId: input.requestId,
+        runtimeTimeline: request.runtimeTimeline,
+        upstreamEvents: traceItems,
+        metadata: {
+            state: request.state,
+            ...(request.runtimeSnapshot ? { runtimeSnapshot: request.runtimeSnapshot } : {}),
+        },
+    });
+}
+export async function exportFlow(runtime, input) {
+    return exportFlowGraphFromGraph(await buildRequestFlowGraph(runtime, input), {
+        direction: "TD",
+        includeGroups: false,
+        includeKinds: ["agent", "llm", "tool", "skill", "memory"],
+    });
+}
+export async function exportSequence(runtime, input) {
+    return exportSequenceGraphFromGraph(await buildRequestFlowGraph(runtime, input));
+}
 export async function deleteSession(runtime, sessionId) {
     return runtime.deleteSession(sessionId);
 }
@@ -233,6 +281,22 @@ export async function getArtifact(runtime, input) {
 export async function listRequestEvents(runtime, input) {
     return (await runtime.listRequestEvents(input.sessionId, input.requestId)).map(toPublicEvent);
 }
+export async function listRequestTraceItems(runtime, input) {
+    const request = await runtime.getRequest(input.requestId);
+    if (!request) {
+        throw new Error(`Request ${input.requestId} was not found.`);
+    }
+    if (request.sessionId !== input.sessionId) {
+        throw new Error(`Request ${input.requestId} belongs to session ${request.sessionId}, not ${input.sessionId}.`);
+    }
+    return (request.traceItems ?? [])
+        .map((item) => toPublicTraceItem({
+        sessionId: input.sessionId,
+        requestId: input.requestId,
+        item,
+    }))
+        .filter((item) => item !== null);
+}
 export async function getHealth(runtime) {
     return runtime.getHealth();
 }

package/dist/config/agents/direct.yaml

@@ -36,9 +36,9 @@ spec:
   mcpServers: []
   # Runtime execution feature: checkpointer config passed into the selected backend adapter.
   # Even the lightweight direct path can benefit from resumable state during interactive use.
-  # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`, `SqliteSaver`.
-  # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
-  checkpointer: sqlite
+  # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`.
+  # The repository default uses the file-backed preset so durable checkpoint state does not require native sqlite bindings.
+  checkpointer: default
   # Upstream execution feature: LangGraph store available to middleware and runtime context hooks.
   # The default direct host keeps this enabled so middleware can use the same durable store surface as other hosts.
   store: default

package/dist/config/agents/orchestra.yaml

@@ -43,9 +43,9 @@ spec:
   mcpServers: []
   # Runtime execution feature: checkpointer config passed into the selected backend adapter.
   # This persists resumable graph state for this agent.
-  # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`, `SqliteSaver`.
-  # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
-  checkpointer: sqlite
+  # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`.
+  # The repository default uses the file-backed preset so durable checkpoint state does not require native sqlite bindings.
+  checkpointer: default
   # Upstream execution feature: store config passed into the selected backend adapter.
   # In the default deepagent adapter this is the LangGraph store used by `StoreBackend` routes.
   # Built-in kinds in this harness today: `FileStore`, `InMemoryStore`.

package/dist/config/catalogs/stores.yaml

@@ -13,12 +13,6 @@ spec:
   # agent-harness feature: reusable checkpointer preset for resumable execution state.
   - kind: Checkpointer
     name: default
-    description: Default in-memory checkpointer preset for lightweight local development.
-    checkpointerKind: MemorySaver
-
-  # agent-harness feature: reusable sqlite checkpointer preset for longer-lived local runs.
-  - kind: Checkpointer
-    name: sqlite
-    description: Default sqlite-backed checkpointer preset for durable local graph state and maintenance sweeps.
-    checkpointerKind: SqliteSaver
-    path: checkpoints.sqlite
+    description: Default file-backed checkpointer preset for durable local graph state without native sqlite bindings.
+    checkpointerKind: FileCheckpointer
+    path: checkpoints.json

package/dist/config/runtime/workspace.yaml

@@ -91,14 +91,13 @@ spec:
   # coupling cleanup to user-triggered checkpoint reads or writes.
   #
   # Current support:
-  # - checkpoint cleanup for `SqliteSaver` checkpointers only
   # - terminal runtime-record cleanup for structured thread/run metadata in `runtime.sqlite`
   # - oldest-first deletion by time policy and/or size policy
   # - background scheduling inside the harness lifecycle
   #
   maintenance:
     checkpoints:
-      enabled: true
+      enabled: false
       schedule:
         intervalSeconds: 3600
         runOnStartup: true

package/dist/contracts/runtime.d.ts

@@ -103,11 +103,14 @@ export type RuntimeSurfaceItem = {
     kind: RuntimeSurfaceKind;
     id: string;
     name: string;
-    label: string;
+    action: string;
     status: "started" | "completed" | "failed";
+    agentId?: string;
+    agentName?: string;
     ownerAgentId?: string;
     ownerAgentName?: string;
     sourceEventId?: string;
+    detail?: Record<string, unknown>;
 };
 export type AgentReference = {
     id: string;
@@ -428,15 +431,13 @@ export type UpstreamRuntimeEvent = unknown;
 export type UpstreamRuntimeEventItem = {
     threadId: string;
     runId: string;
-    agentId: string;
-    agentName?: string;
-    surfaceItems?: RuntimeSurfaceItem[];
+    surfaceItem: RuntimeSurfaceItem;
     event: UpstreamRuntimeEvent;
 };
 export type RuntimeListeners = {
     onEvent?: (event: HarnessEvent) => void | Promise<void>;
     onUpstreamEvent?: (event: UpstreamRuntimeEvent) => void | Promise<void>;
-    onUpstreamItem?: (item: UpstreamRuntimeEventItem) => void | Promise<void>;
+    onTraceItem?: (item: UpstreamRuntimeEventItem) => void | Promise<void>;
 };
 export type RunListeners = RuntimeListeners;
 export type MessageContentPart = {
@@ -477,9 +478,7 @@ export type HarnessStreamItem = {
     type: "upstream-event";
     threadId: string;
     runId: string;
-    agentId: string;
-    agentName?: string;
-    surfaceItems?: RuntimeSurfaceItem[];
+    surfaceItem?: RuntimeSurfaceItem;
     event: UpstreamRuntimeEvent;
 } | {
     type: "result";
@@ -519,9 +518,7 @@ export type RequestSummary = Omit<ThreadRunRecord, "threadId" | "runId"> & {
     requestId: string;
 };
 export type RequestRecord = RequestSummary & {
-    history?: RuntimeHistoryItem[];
-    runtimeSurface?: RuntimeSurfaceItem[];
-    upstreamEvents?: unknown[];
+    traceItems?: unknown[];
     runtimeTimeline?: RuntimeTimelineItem[];
 };
 /**
@@ -532,9 +529,7 @@ export type RunSummary = Omit<RequestSummary, "sessionId" | "requestId"> & {
     runId: string;
 };
 export type RunRecord = RunSummary & {
-    history?: RuntimeHistoryItem[];
-    runtimeSurface?: RuntimeSurfaceItem[];
-    upstreamEvents?: unknown[];
+    traceItems?: unknown[];
     runtimeTimeline?: RuntimeTimelineItem[];
 };
 /**