@botbotgo/agent-harness 0.0.232 → 0.0.233

package/README.md

@@ -1028,9 +1028,9 @@ ACP transport notes:
 - `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.
-- `exportRequestPackage(...)` and `exportSessionPackage(...)` package stable runtime records, transcript, approvals, events, and artifacts for operator tooling without reaching into persistence internals.
+- `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.
 - `runtime/default.observability.tracing` can now describe exporter metadata such as OTLP endpoints and propagation mode, so frozen runtime snapshots keep trace-correlation plus operator-visible export context without exposing backend-private span internals.
-- `agent-harness runtime overview`, `agent-harness runtime health`, `agent-harness runtime approvals list|watch`, and `agent-harness runtime runs list|tail` provide a thin operator CLI over persisted runtime health, queue pressure, governance risk, approval queues, and active run state.
+- `agent-harness runtime overview`, `agent-harness runtime health`, `agent-harness runtime approvals list|watch`, `agent-harness runtime runs list|tail`, and `agent-harness runtime export request|session` provide a thin operator CLI over persisted runtime health, queue pressure, governance risk, approval queues, active run state, and audit-ready evidence packages.
 - detailed A2A adapter guidance lives in [`docs/a2a-bridge.md`](docs/a2a-bridge.md)

package/README.zh.md

@@ -986,9 +986,9 @@ ACP transport 说明：
 - `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。
-- `exportRequestPackage(...)` 与 `exportSessionPackage(...)` 可把稳定 runtime 记录、transcript、approvals、events 和 artifacts 打包给管理工具，而不必直接访问 persistence 内部实现。
+- `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。
 - `runtime/default.observability.tracing` 现在可描述 OTLP endpoint 和 propagation mode 这类 exporter 元数据，使冻结的 runtime snapshot 在保留 trace correlation 的同时，也能保留有用的导出上下文，而不暴露 backend 私有 span 细节。
-- `agent-harness runtime overview`、`agent-harness runtime health`、`agent-harness runtime approvals list|watch` 与 `agent-harness runtime runs list|tail` 提供了一层轻量 CLI，可直接查看 runtime health、queue pressure、governance risk、审批队列和运行状态。
+- `agent-harness runtime overview`、`agent-harness runtime health`、`agent-harness runtime approvals list|watch`、`agent-harness runtime runs list|tail` 与 `agent-harness runtime export request|session` 提供了一层轻量 CLI，可直接查看 runtime health、queue pressure、governance risk、审批队列、运行状态与可审计证据包。
 - 更详细的 A2A 适配层开发说明见 [`docs/a2a-bridge.md`](docs/a2a-bridge.md)

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, RunListeners, RunResult, RunStartOptions, RuntimeHealthSnapshot, RuntimeGovernanceDiagnostics, RuntimeOperatorOverview, RuntimeQueueDiagnostics, RuntimeAdapterOptions, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult as InternalRuntimeEvaluationReplayResult, RuntimeSessionPackage, RuntimeSessionPackageInput, SessionListSummary, SessionRecord, SessionSummary, TranscriptMessage, 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, RuntimeGovernanceEvidence, RuntimeGovernanceDiagnostics, RuntimeOperatorOverview, RuntimeQueueDiagnostics, RuntimeAdapterOptions, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult as InternalRuntimeEvaluationReplayResult, RuntimeSessionPackage, RuntimeSessionPackageInput, SessionListSummary, 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";
@@ -45,6 +45,7 @@ export type Approval = {
     sessionId: string;
     requestId: string;
     toolName: string;
+    approvalReason?: string;
     status: "pending" | "approved" | "edited" | "rejected" | "expired";
     requestedAt: string;
     resolvedAt: string | null;
@@ -69,6 +70,7 @@ export type RequestPackage = {
     transcript: TranscriptMessage[];
     events: RequestEvent[];
     artifacts: RequestArtifactListing["items"];
+    governance: RuntimeGovernanceEvidence;
     runtimeHealth?: RuntimeHealthSnapshot;
 };
 export type RuntimeEvaluationReplayResult = Omit<InternalRuntimeEvaluationReplayResult, "result"> & {

package/dist/api.js

@@ -17,6 +17,7 @@ function toApprovalRecord(record) {
         sessionId: record.threadId,
         requestId: record.runId,
         toolName: record.toolName,
+        ...(record.approvalReason ? { approvalReason: record.approvalReason } : {}),
         status: record.status,
         requestedAt: record.requestedAt,
         resolvedAt: record.resolvedAt,
@@ -84,6 +85,7 @@ function toRequestPackage(pkg) {
         transcript: pkg.transcript,
         events: pkg.events.map(toPublicEvent),
         artifacts: pkg.artifacts,
+        governance: pkg.governance,
         ...(pkg.runtimeHealth ? { runtimeHealth: pkg.runtimeHealth } : {}),
     };
 }

package/dist/cli.js

@@ -20,6 +20,8 @@ function renderUsage() {
   agent-harness runtime approvals watch [--workspace <path>] [--status <pending|approved|edited|rejected|expired>] [--poll-ms <ms>] [--once] [--json]
   agent-harness runtime runs list [--workspace <path>] [--agent <agentId>] [--thread <threadId>] [--state <state>] [--json]
   agent-harness runtime runs tail [--workspace <path>] [--agent <agentId>] [--thread <threadId>] [--state <state>] [--poll-ms <ms>] [--once] [--json]
+  agent-harness runtime export request --workspace <path> --session <sessionId> --request <requestId> [--artifacts] [--artifact-contents] [--health] [--json]
+  agent-harness runtime export session --workspace <path> --session <sessionId> [--artifacts] [--artifact-contents] [--health] [--json]
   agent-harness runtime-mcp serve [--workspace <path>]
 `;
 }
@@ -218,6 +220,80 @@ function parseRuntimeInspectOptions(args) {
     }
     return { workspaceRoot, json, once, pollMs, limit, status, state, agentId, threadId };
 }
+function parseRuntimeExportOptions(args) {
+    let workspaceRoot;
+    let sessionId;
+    let requestId;
+    let includeArtifacts = false;
+    let includeArtifactContents = false;
+    let includeRuntimeHealth = false;
+    let json = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--artifacts") {
+            includeArtifacts = true;
+            continue;
+        }
+        if (arg === "--artifact-contents") {
+            includeArtifacts = true;
+            includeArtifactContents = true;
+            continue;
+        }
+        if (arg === "--health") {
+            includeRuntimeHealth = true;
+            continue;
+        }
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--workspace" || arg === "--session" || arg === "--request") {
+            const value = args[index + 1];
+            if (!value) {
+                return {
+                    workspaceRoot,
+                    sessionId,
+                    requestId,
+                    includeArtifacts,
+                    includeArtifactContents,
+                    includeRuntimeHealth,
+                    json,
+                    error: `Missing value for ${arg}`,
+                };
+            }
+            if (arg === "--workspace") {
+                workspaceRoot = value;
+            }
+            else if (arg === "--session") {
+                sessionId = value;
+            }
+            else {
+                requestId = value;
+            }
+            index += 1;
+            continue;
+        }
+        return {
+            workspaceRoot,
+            sessionId,
+            requestId,
+            includeArtifacts,
+            includeArtifactContents,
+            includeRuntimeHealth,
+            json,
+            error: `Unknown option: ${arg}`,
+        };
+    }
+    return {
+        workspaceRoot,
+        sessionId,
+        requestId,
+        includeArtifacts,
+        includeArtifactContents,
+        includeRuntimeHealth,
+        json,
+    };
+}
 function renderJson(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
@@ -517,15 +593,73 @@ export async function runCli(argv, io = {}, deps = {}) {
         }
     }
     if (command === "runtime") {
-        const [subcommand, possibleNestedCommand, ...remainingArgs] = [projectName, ...rest];
+        const [subcommand, possibleNestedCommand, possibleThirdCommand, ...remainingArgs] = [projectName, ...rest];
         if (!subcommand) {
             stderr(renderUsage());
             return 1;
         }
+        if (subcommand === "export") {
+            const exportTarget = possibleNestedCommand;
+            const parsed = parseRuntimeExportOptions([possibleThirdCommand, ...remainingArgs].filter((item) => typeof item === "string"));
+            if (parsed.error) {
+                stderr(`${parsed.error}\n`);
+                stderr(renderUsage());
+                return 1;
+            }
+            if (!parsed.sessionId) {
+                stderr("Missing value for --session\n");
+                stderr(renderUsage());
+                return 1;
+            }
+            if (exportTarget !== "request" && exportTarget !== "session") {
+                stderr(renderUsage());
+                return 1;
+            }
+            if (exportTarget === "request" && !parsed.requestId) {
+                stderr("Missing value for --request\n");
+                stderr(renderUsage());
+                return 1;
+            }
+            try {
+                const runtime = await createHarness(path.resolve(cwd, parsed.workspaceRoot ?? "."));
+                try {
+                    if (exportTarget === "request") {
+                        const pkg = await runtime.exportRequestPackage({
+                            sessionId: parsed.sessionId,
+                            requestId: parsed.requestId,
+                            includeArtifacts: parsed.includeArtifacts,
+                            includeArtifactContents: parsed.includeArtifactContents,
+                            includeRuntimeHealth: parsed.includeRuntimeHealth,
+                        });
+                        stdout(renderJson(pkg));
+                    }
+                    else {
+                        const pkg = await runtime.exportSessionPackage({
+                            sessionId: parsed.sessionId,
+                            includeArtifacts: parsed.includeArtifacts,
+                            includeArtifactContents: parsed.includeArtifactContents,
+                            includeRuntimeHealth: parsed.includeRuntimeHealth,
+                        });
+                        stdout(renderJson(pkg));
+                    }
+                }
+                finally {
+                    await runtime.stop();
+                }
+                return 0;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                stderr(`${message}\n`);
+                return 1;
+            }
+        }
         const nestedCommand = (subcommand === "approvals" || subcommand === "runs") && possibleNestedCommand
             ? possibleNestedCommand
             : undefined;
-        const subcommandArgs = nestedCommand ? remainingArgs : [possibleNestedCommand, ...remainingArgs].filter((item) => typeof item === "string");
+        const subcommandArgs = nestedCommand
+            ? [possibleThirdCommand, ...remainingArgs].filter((item) => typeof item === "string")
+            : [possibleNestedCommand, possibleThirdCommand, ...remainingArgs].filter((item) => typeof item === "string");
         const parsed = parseRuntimeInspectOptions(subcommandArgs);
         if (parsed.error) {
             stderr(`${parsed.error}\n`);

package/dist/contracts/runtime.d.ts

@@ -572,6 +572,7 @@ export type ApprovalRecord = {
     threadId: string;
     runId: string;
     toolName: string;
+    approvalReason?: string;
     status: "pending" | "approved" | "edited" | "rejected" | "expired";
     requestedAt: string;
     resolvedAt: string | null;
@@ -726,6 +727,21 @@ export type RuntimeRunPackageInput = {
     includeArtifactContents?: boolean;
     includeRuntimeHealth?: boolean;
 };
+export type RuntimeApprovalSummary = {
+    total: number;
+    pending: number;
+    approved: number;
+    edited: number;
+    rejected: number;
+    expired: number;
+    toolNames: string[];
+    approvalReasons: string[];
+};
+export type RuntimeGovernanceEvidence = {
+    bundles: RuntimeGovernanceBundle[];
+    approvalSummary: RuntimeApprovalSummary;
+    summary: string;
+};
 export type RuntimeRunPackage = {
     session: SessionRecord | null;
     request: RequestRecord | null;
@@ -733,6 +749,7 @@ export type RuntimeRunPackage = {
     transcript: TranscriptMessage[];
     events: HarnessEvent[];
     artifacts: RuntimeEvaluationArtifact[];
+    governance: RuntimeGovernanceEvidence;
     runtimeHealth?: RuntimeHealthSnapshot;
 };
 export type RuntimeSessionPackageInput = {
@@ -747,6 +764,14 @@ export type RuntimeSessionPackage = {
     approvals: ApprovalRecord[];
     transcript: TranscriptMessage[];
     runs: RuntimeRunPackage[];
+    governance: {
+        runs: Array<{
+            requestId: string;
+            evidence: RuntimeGovernanceEvidence;
+        }>;
+        approvalSummary: RuntimeApprovalSummary;
+        summary: string;
+    };
     runtimeHealth?: RuntimeHealthSnapshot;
 };
 export type RuntimeInventoryContext = {

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.231";
+export declare const AGENT_HARNESS_VERSION = "0.0.232";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.231";
+export const AGENT_HARNESS_VERSION = "0.0.232";

package/dist/runtime/harness.js

@@ -69,6 +69,24 @@ function toSessionListSummary(session) {
         snippet: normalizeSessionListText(session.lastMessage?.content, 160),
     };
 }
+function summarizeApprovalEvidence(approvals) {
+    const toolNames = Array.from(new Set(approvals
+        .map((approval) => approval.toolName)
+        .filter((toolName) => typeof toolName === "string" && toolName.trim().length > 0)));
+    const approvalReasons = Array.from(new Set(approvals
+        .map((approval) => approval.approvalReason)
+        .filter((reason) => typeof reason === "string" && reason.trim().length > 0)));
+    return {
+        total: approvals.length,
+        pending: approvals.filter((approval) => approval.status === "pending").length,
+        approved: approvals.filter((approval) => approval.status === "approved").length,
+        edited: approvals.filter((approval) => approval.status === "edited").length,
+        rejected: approvals.filter((approval) => approval.status === "rejected").length,
+        expired: approvals.filter((approval) => approval.status === "expired").length,
+        toolNames,
+        approvalReasons,
+    };
+}
 export class AgentHarnessRuntime {
     workspace;
     runtimeAdapterOptions;
@@ -710,6 +728,15 @@ export class AgentHarnessRuntime {
                 ? { content: await this.persistence.readArtifact(input.sessionId, input.requestId, artifact.path) }
                 : {}),
         })));
+        const approvalSummary = summarizeApprovalEvidence(approvals);
+        const bundles = request?.runtimeSnapshot?.governance?.bundles ?? [];
+        const governanceSummaryParts = [
+            `${bundles.length} governance bundle(s)`,
+            `${approvalSummary.total} approval record(s)`,
+        ];
+        if (approvalSummary.approvalReasons.length > 0) {
+            governanceSummaryParts.push(`reasons=${approvalSummary.approvalReasons.join(",")}`);
+        }
         return {
             session,
             request,
@@ -717,6 +744,11 @@ export class AgentHarnessRuntime {
             transcript,
             events,
             artifacts,
+            governance: {
+                bundles,
+                approvalSummary,
+                summary: governanceSummaryParts.join(" "),
+            },
             ...(input.includeRuntimeHealth === false ? {} : { runtimeHealth: await this.getHealth() }),
         };
     }
@@ -733,12 +765,25 @@ export class AgentHarnessRuntime {
             includeArtifactContents: input.includeArtifactContents,
             includeRuntimeHealth: false,
         })));
+        const approvals = await this.listApprovals({ threadId: input.sessionId });
+        const approvalSummary = summarizeApprovalEvidence(approvals);
+        const governanceRuns = runs
+            .filter((item) => item.request?.requestId)
+            .map((item) => ({
+            requestId: item.request.requestId,
+            evidence: item.governance,
+        }));
         return {
             session,
             requests: runs.map((item) => item.request).filter((item) => Boolean(item)),
-            approvals: await this.listApprovals({ threadId: input.sessionId }),
+            approvals,
             transcript: await this.persistence.listThreadMessages(input.sessionId, 500),
             runs,
+            governance: {
+                runs: governanceRuns,
+                approvalSummary,
+                summary: `${governanceRuns.length} run evidence package(s), ${approvalSummary.total} approval record(s)`,
+            },
             ...(input.includeRuntimeHealth === false ? {} : { runtimeHealth: await this.getHealth() }),
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.232",
+  "version": "0.0.233",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",