@botbotgo/agent-harness 0.0.65 → 0.0.66

package/README.md

@@ -207,6 +207,8 @@ const result = await run(runtime, {
 
 `run(runtime, { ... })` creates or continues a persisted thread and returns `threadId`, `runId`, `state`, and compact text `output`. Richer upstream result shapes stay available through `outputContent`, `contentBlocks`, and `structuredResponse`.
 
+Use `listRuns(runtime)` and `getRun(runtime, runId)` when a product needs a run-centric operations surface such as a review queue or execution dashboard.
+
 Use `invocation` as the runtime-facing request envelope:
 
 - `invocation.context` for request-scoped execution context
@@ -575,6 +577,8 @@ Primary exports:
 - `run`
 - `resolveApproval`
 - `subscribe`
+- `listRuns`
+- `getRun`
 - `listThreads`
 - `getThread`
 - `deleteThread`

package/README.zh.md

@@ -206,6 +206,8 @@ const result = await run(runtime, {
 
 `run(runtime, { ... })` 会创建或延续持久化线程，并返回 `threadId`、`runId`、`state` 以及紧凑文本 `output`。更丰富的上游结果形态仍可通过 `outputContent`、`contentBlocks`、`structuredResponse` 等获得。
 
+如果产品需要 run 视角的操作界面，例如 review queue 或执行看板，可使用 `listRuns(runtime)` 与 `getRun(runtime, runId)`。
+
 将 `invocation` 作为面向运行时的请求信封：
 
 - `invocation.context`：请求级执行上下文
@@ -567,6 +569,8 @@ spec:
 - `run`
 - `resolveApproval`
 - `subscribe`
+- `listRuns`
+- `getRun`
 - `listThreads`
 - `getThread`
 - `deleteThread`

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import type { ApprovalRecord, RunOptions, ResumeOptions, RuntimeAdapterOptions, ThreadSummary, ThreadRecord, WorkspaceLoadOptions } from "./contracts/types.js";
+import type { ApprovalRecord, RunRecord, RunOptions, RunSummary, ResumeOptions, RuntimeAdapterOptions, ThreadSummary, ThreadRecord, WorkspaceLoadOptions } from "./contracts/types.js";
 import { AgentHarnessRuntime } from "./runtime/harness.js";
 import type { InventoryAgentRecord, InventorySkillRecord } from "./runtime/inventory.js";
 import type { RequirementAssessmentOptions } from "./runtime/skill-requirements.js";
@@ -13,7 +13,9 @@ export declare function createAgentHarness(workspaceRoot: string, options?: Crea
 export declare function run(runtime: AgentHarnessRuntime, options: RunOptions): Promise<import("./contracts/types.js").RunResult>;
 export declare function subscribe(runtime: AgentHarnessRuntime, listener: Parameters<AgentHarnessRuntime["subscribe"]>[0]): () => void;
 export declare function listThreads(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listThreads"]>[0]): Promise<ThreadSummary[]>;
+export declare function listRuns(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listRuns"]>[0]): Promise<RunSummary[]>;
 export declare function getThread(runtime: AgentHarnessRuntime, threadId: string): Promise<ThreadRecord | null>;
+export declare function getRun(runtime: AgentHarnessRuntime, runId: string): Promise<RunRecord | null>;
 export declare function deleteThread(runtime: AgentHarnessRuntime, threadId: string): Promise<boolean>;
 export declare function listApprovals(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listApprovals"]>[0]): Promise<ApprovalRecord[]>;
 export declare function getApproval(runtime: AgentHarnessRuntime, approvalId: string): Promise<ApprovalRecord | null>;

package/dist/api.js

@@ -16,9 +16,15 @@ export function subscribe(runtime, listener) {
 export async function listThreads(runtime, filter) {
     return runtime.listThreads(filter);
 }
+export async function listRuns(runtime, filter) {
+    return runtime.listRuns(filter);
+}
 export async function getThread(runtime, threadId) {
     return runtime.getThread(threadId);
 }
+export async function getRun(runtime, runId) {
+    return runtime.getRun(runId);
+}
 export async function deleteThread(runtime, threadId) {
     return runtime.deleteThread(threadId);
 }

package/dist/contracts/types.d.ts

@@ -361,6 +361,7 @@ export type TranscriptMessage = {
 };
 export type ThreadRunRecord = {
     runId: string;
+    threadId: string;
     agentId: string;
     executionMode: string;
     adapterKind?: string;
@@ -370,6 +371,8 @@ export type ThreadRunRecord = {
     checkpointRef: string | null;
     resumable: boolean;
 };
+export type RunSummary = ThreadRunRecord;
+export type RunRecord = RunSummary;
 export type ThreadRecord = {
     threadId: string;
     entryAgentId: string;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, describeInventory, getApproval, getThread, listAgentSkills, listApprovals, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, describeInventory, getApproval, getRun, getThread, listAgentSkills, listApprovals, listRuns, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
 export type { ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, describeInventory, getApproval, getThread, listAgentSkills, listApprovals, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, describeInventory, getApproval, getRun, getThread, listAgentSkills, listApprovals, listRuns, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
 export { tool } from "./tools.js";

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.64";
+export declare const AGENT_HARNESS_VERSION = "0.0.65";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.64";
+export const AGENT_HARNESS_VERSION = "0.0.65";

package/dist/persistence/file-store.d.ts

@@ -1,4 +1,4 @@
-import type { ArtifactListing, ArtifactRecord, DelegationRecord, HarnessEvent, InternalApprovalRecord, InvocationEnvelope, MessageContent, RunState, ThreadSummary, ThreadRunRecord, TranscriptMessage } from "../contracts/types.js";
+import type { ArtifactListing, ArtifactRecord, DelegationRecord, HarnessEvent, InternalApprovalRecord, InvocationEnvelope, MessageContent, RunSummary, RunState, ThreadSummary, ThreadRunRecord, TranscriptMessage } from "../contracts/types.js";
 type ThreadMeta = {
     threadId: string;
     workspaceId: string;
@@ -73,6 +73,9 @@ export declare class FilePersistence {
     appendEvent(event: HarnessEvent): Promise<void>;
     listSessions(): Promise<ThreadSummary[]>;
     listRunIndexes(): Promise<RunIndexRecord[]>;
+    private readRunSummary;
+    listRuns(): Promise<RunSummary[]>;
+    getRun(runId: string): Promise<RunSummary | null>;
     getSession(threadId: string): Promise<ThreadSummary | null>;
     getThreadMeta(threadId: string): Promise<ThreadMeta | null>;
     listThreadRuns(threadId: string): Promise<ThreadRunRecord[]>;

package/dist/persistence/file-store.js

@@ -190,6 +190,38 @@ export class FilePersistence {
         const entries = (await readdir(runIndexDir)).sort();
         return Promise.all(entries.map((entry) => readJson(path.join(runIndexDir, entry))));
     }
+    async readRunSummary(threadId, runId) {
+        const runDir = this.runDir(threadId, runId);
+        const [meta, lifecycle] = await Promise.all([
+            readJson(path.join(runDir, "meta.json")),
+            readJson(path.join(runDir, "lifecycle.json")),
+        ]);
+        return {
+            runId: meta.runId,
+            threadId: meta.threadId,
+            agentId: meta.agentId,
+            executionMode: meta.executionMode,
+            adapterKind: meta.adapterKind ?? meta.executionMode,
+            createdAt: meta.createdAt,
+            updatedAt: meta.updatedAt,
+            state: lifecycle.state,
+            checkpointRef: lifecycle.checkpointRef,
+            resumable: lifecycle.resumable,
+        };
+    }
+    async listRuns() {
+        const indexes = await this.listRunIndexes();
+        const runs = await Promise.all(indexes.map((record) => this.readRunSummary(record.threadId, record.runId)));
+        return runs.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+    }
+    async getRun(runId) {
+        const indexPath = this.runIndexPath(runId);
+        if (!(await fileExists(indexPath))) {
+            return null;
+        }
+        const index = await readJson(indexPath);
+        return this.readRunSummary(index.threadId, index.runId);
+    }
     async getSession(threadId) {
         const filePath = path.join(this.runRoot, "indexes", "threads", `${threadId}.json`);
         if (!(await fileExists(filePath))) {
@@ -221,24 +253,7 @@ export class FilePersistence {
             return [];
         }
         const runIds = (await readdir(runsDir)).sort();
-        const runs = await Promise.all(runIds.map(async (runId) => {
-            const runDir = this.runDir(threadId, runId);
-            const [meta, lifecycle] = await Promise.all([
-                readJson(path.join(runDir, "meta.json")),
-                readJson(path.join(runDir, "lifecycle.json")),
-            ]);
-            return {
-                runId: meta.runId,
-                agentId: meta.agentId,
-                executionMode: meta.executionMode,
-                adapterKind: meta.adapterKind ?? meta.executionMode,
-                createdAt: meta.createdAt,
-                updatedAt: meta.updatedAt,
-                state: lifecycle.state,
-                checkpointRef: lifecycle.checkpointRef,
-                resumable: lifecycle.resumable,
-            };
-        }));
+        const runs = await Promise.all(runIds.map(async (runId) => this.readRunSummary(threadId, runId)));
         return runs.sort((left, right) => right.createdAt.localeCompare(left.createdAt));
     }
     async listRunEvents(threadId, runId) {

package/dist/runtime/harness.d.ts

@@ -1,4 +1,4 @@
-import type { ApprovalRecord, HarnessEvent, HarnessStreamItem, MessageContent, RunStartOptions, RestartConversationOptions, RuntimeAdapterOptions, ResumeOptions, RunOptions, RunResult, ThreadSummary, ThreadRecord, WorkspaceBundle } from "../contracts/types.js";
+import type { ApprovalRecord, HarnessEvent, HarnessStreamItem, MessageContent, RunRecord, RunStartOptions, RestartConversationOptions, RuntimeAdapterOptions, ResumeOptions, RunOptions, RunResult, RunSummary, ThreadSummary, ThreadRecord, WorkspaceBundle } from "../contracts/types.js";
 import { type ToolMcpServerOptions } from "../mcp.js";
 import { type InventoryAgentRecord, type InventorySkillRecord } from "./inventory.js";
 import type { RequirementAssessmentOptions } from "./skill-requirements.js";
@@ -49,6 +49,12 @@ export declare class AgentHarnessRuntime {
     listThreads(filter?: {
         agentId?: string;
     }): Promise<ThreadSummary[]>;
+    listRuns(filter?: {
+        agentId?: string;
+        threadId?: string;
+        state?: RunSummary["state"];
+    }): Promise<RunSummary[]>;
+    getRun(runId: string): Promise<RunRecord | null>;
     private getSession;
     getThread(threadId: string): Promise<ThreadRecord | null>;
     listApprovals(filter?: {

package/dist/runtime/harness.js

@@ -234,6 +234,24 @@ export class AgentHarnessRuntime {
         }
         return threadSummaries.filter((thread) => thread.agentId === filter.agentId);
     }
+    async listRuns(filter) {
+        const runs = await this.persistence.listRuns();
+        return runs.filter((run) => {
+            if (filter?.agentId && run.agentId !== filter.agentId) {
+                return false;
+            }
+            if (filter?.threadId && run.threadId !== filter.threadId) {
+                return false;
+            }
+            if (filter?.state && run.state !== filter.state) {
+                return false;
+            }
+            return true;
+        });
+    }
+    async getRun(runId) {
+        return this.persistence.getRun(runId);
+    }
     async getSession(threadId) {
         return this.persistence.getSession(threadId);
     }

package/package.json

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