@botbotgo/agent-harness 0.0.64 → 0.0.66

package/README.md

@@ -69,6 +69,7 @@ Boundary documents live in:
 - `docs/product-boundary.md`
 - `docs/feature-checklist.md`
 - `docs/long-term-memory.md`
+- `docs/app-task-pattern.md`
 
 ## Why This Exists
 
@@ -206,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
@@ -560,6 +563,7 @@ For backend-specific options, prefer the upstream concept directly inside `spec.
 - upstream LangChain v1 and DeepAgents concepts should be expressed as directly as possible in YAML
 - when a feature can be expressed in YAML, prefer YAML over expanding the public API
 - recovery, approvals, threads, runs, and events are runtime concepts, not backend escape hatches
+- application task centers should be built on the existing store plus runtime ids instead of expanding the public runtime contract
 - new LangChain v1 or DeepAgents config should land in YAML mapping and tests before adding public runtime APIs
 
 In short, the product model stays stable while the execution semantics remain upstream-owned.
@@ -573,6 +577,8 @@ Primary exports:
 - `run`
 - `resolveApproval`
 - `subscribe`
+- `listRuns`
+- `getRun`
 - `listThreads`
 - `getThread`
 - `deleteThread`

package/README.zh.md

@@ -68,6 +68,8 @@
 - `docs/upstream-feature-matrix.md`
 - `docs/product-boundary.md`
 - `docs/feature-checklist.md`
+- `docs/long-term-memory.md`
+- `docs/app-task-pattern.md`
 
 ## 为何需要它
 
@@ -204,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`：请求级执行上下文
@@ -551,6 +555,7 @@ spec:
 - 应尽量在 YAML 中直接表达 LangChain v1 与 DeepAgents 的概念
 - 能用 YAML 表达的能力，优先 YAML 而非扩张公共 API
 - 恢复、审批、线程、运行与事件是运行时概念，不是后端逃生舱
+- 应用里的 task center 应基于现有 store 与 runtime id 建模，而不是把 task 扩成公共运行时契约
 - 新的 LangChain v1 或 DeepAgents 配置应先落在 YAML 映射与测试中，再考虑公共运行时 API
 
 简言之：产品模型稳定，执行语义仍归上游。
@@ -564,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.63";
+export declare const AGENT_HARNESS_VERSION = "0.0.65";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.63";
+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.64",
+  "version": "0.0.66",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",