@botbotgo/agent-harness 0.0.80 → 0.0.82

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import type { ApprovalRecord, RunRecord, RunOptions, RunSummary, ResumeOptions, RuntimeHealthSnapshot, RuntimeAdapterOptions, ThreadSummary, ThreadRecord, WorkspaceLoadOptions } from "./contracts/types.js";
+import type { ApprovalRecord, CancelOptions, RunRecord, RunOptions, RunSummary, ResumeOptions, RuntimeHealthSnapshot, 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";
@@ -30,6 +30,7 @@ export declare function describeInventory(runtime: AgentHarnessRuntime, options?
     agents: InventoryAgentRecord[];
 };
 export declare function resolveApproval(runtime: AgentHarnessRuntime, options: ResumeOptions): Promise<import("./contracts/types.js").RunResult>;
+export declare function cancelRun(runtime: AgentHarnessRuntime, options: CancelOptions): Promise<import("./contracts/types.js").RunResult>;
 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

@@ -46,6 +46,9 @@ export function describeInventory(runtime, options) {
 export async function resolveApproval(runtime, options) {
     return runtime.resume(options);
 }
+export async function cancelRun(runtime, options) {
+    return runtime.cancelRun(options);
+}
 export async function stop(runtime) {
     return runtime.stop();
 }

package/dist/contracts/types.d.ts

@@ -4,7 +4,7 @@ export type RuntimeCapabilities = {
     delegation?: boolean;
     memory?: boolean;
 };
-export type RunState = "queued" | "running" | "waiting_for_approval" | "resuming" | "completed" | "failed";
+export type RunState = "queued" | "claimed" | "running" | "waiting_for_approval" | "resuming" | "cancelling" | "cancelled" | "completed" | "failed";
 export type ParsedAgentObject = {
     id: string;
     executionMode: ExecutionMode;
@@ -440,6 +440,10 @@ export type ResumeOptions = {
     decision?: "approve" | "edit" | "reject";
     editedInput?: Record<string, unknown>;
 };
+export type CancelOptions = {
+    runId: string;
+    reason?: string;
+};
 export type RestartConversationOptions = {
     threadId: string;
     mode: "restart-in-thread" | "restart-new-thread";

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, describeInventory, getApproval, getHealth, getRun, getThread, listAgentSkills, listApprovals, listRuns, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, cancelRun, createAgentHarness, createToolMcpServer, deleteThread, describeInventory, getApproval, getHealth, 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, getHealth, getRun, getThread, listAgentSkills, listApprovals, listRuns, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, cancelRun, createAgentHarness, createToolMcpServer, deleteThread, describeInventory, getApproval, getHealth, 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.79";
+export declare const AGENT_HARNESS_VERSION = "0.0.81";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.79";
+export const AGENT_HARNESS_VERSION = "0.0.81";

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

@@ -1,5 +1,5 @@
 import type { ArtifactListing, ArtifactRecord, DelegationRecord, HarnessEvent, InternalApprovalRecord, RunSummary, RunState, ThreadSummary, ThreadRunRecord, TranscriptMessage } from "../contracts/types.js";
-import type { PersistedRunRequest, PersistenceLifecycle as Lifecycle, RuntimePersistence, RecoveryIntent, PersistenceRunMeta as RunMeta, PersistenceThreadMeta as ThreadMeta } from "./types.js";
+import type { ApprovalFilter, PersistedRunRequest, PersistedRunControlRecord, PersistedRunQueueRecord, PersistenceLifecycle as Lifecycle, RuntimePersistence, RecoveryIntent, PersistenceRunMeta as RunMeta, RunSummaryFilter, ThreadSummaryFilter, PersistenceThreadMeta as ThreadMeta } from "./types.js";
 type RunIndexRecord = {
     runId: string;
     threadId: string;
@@ -14,6 +14,8 @@ export declare class FilePersistence implements RuntimePersistence {
     private runIndexPath;
     private approvalIndexPath;
     private delegationIndexPath;
+    private runQueuePath;
+    private runControlPath;
     initialize(): Promise<void>;
     threadDir(threadId: string): string;
     runDir(threadId: string, runId: string): string;
@@ -34,16 +36,16 @@ export declare class FilePersistence implements RuntimePersistence {
     }): Promise<void>;
     setRunState(threadId: string, runId: string, state: RunState, checkpointRef?: string | null): Promise<void>;
     appendEvent(event: HarnessEvent): Promise<void>;
-    listSessions(): Promise<ThreadSummary[]>;
+    listSessions(filter?: ThreadSummaryFilter): Promise<ThreadSummary[]>;
     listRunIndexes(): Promise<RunIndexRecord[]>;
     private readRunSummary;
-    listRuns(): Promise<RunSummary[]>;
+    listRuns(filter?: RunSummaryFilter): 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[]>;
     listRunEvents(threadId: string, runId: string): Promise<HarnessEvent[]>;
-    listApprovals(): Promise<InternalApprovalRecord[]>;
+    listApprovals(filter?: ApprovalFilter): Promise<InternalApprovalRecord[]>;
     getApproval(approvalId: string): Promise<InternalApprovalRecord | null>;
     getRunApprovals(threadId: string, runId: string): Promise<InternalApprovalRecord[]>;
     getRunMeta(threadId: string, runId: string): Promise<RunMeta>;
@@ -64,5 +66,31 @@ export declare class FilePersistence implements RuntimePersistence {
     saveRecoveryIntent(threadId: string, runId: string, intent: RecoveryIntent): Promise<void>;
     getRecoveryIntent(threadId: string, runId: string): Promise<RecoveryIntent | null>;
     clearRecoveryIntent(threadId: string, runId: string): Promise<void>;
+    enqueueRun(input: {
+        threadId: string;
+        runId: string;
+        priority?: number;
+        queueKey?: string | null;
+        availableAt?: string;
+    }): Promise<void>;
+    getQueuedRun(runId: string): Promise<PersistedRunQueueRecord | null>;
+    claimQueuedRun(input: {
+        threadId: string;
+        runId: string;
+        workerId: string;
+        claimedAt?: string;
+        leaseExpiresAt: string;
+    }): Promise<PersistedRunQueueRecord>;
+    renewRunLease(input: {
+        runId: string;
+        workerId: string;
+        heartbeatAt?: string;
+        leaseExpiresAt: string;
+    }): Promise<void>;
+    releaseRunClaim(runId: string): Promise<void>;
+    listExpiredClaimedRuns(cutoffIso: string): Promise<PersistedRunQueueRecord[]>;
+    getRunControl(runId: string): Promise<PersistedRunControlRecord | null>;
+    requestRunCancel(runId: string, reason?: string): Promise<PersistedRunControlRecord>;
+    clearRunCancel(runId: string): Promise<void>;
 }
 export {};

package/dist/persistence/file-store.js

@@ -22,12 +22,20 @@ export class FilePersistence {
     delegationIndexPath(delegationId) {
         return path.join(this.runRoot, "indexes", "delegations", `${delegationId}.json`);
     }
+    runQueuePath(runId) {
+        return path.join(this.runRoot, "indexes", "queue", `${runId}.json`);
+    }
+    runControlPath(runId) {
+        return path.join(this.runRoot, "indexes", "run-control", `${runId}.json`);
+    }
     async initialize() {
         await Promise.all([
             "indexes/threads",
             "indexes/runs",
             "indexes/approvals",
             "indexes/delegations",
+            "indexes/queue",
+            "indexes/run-control",
             "threads",
         ].map((segment) => ensureDir(path.join(this.runRoot, segment))));
     }
@@ -107,6 +115,15 @@ export class FilePersistence {
                 resumable: false,
                 updatedAt: input.createdAt,
             }),
+            writeJson(this.runControlPath(input.runId), {
+                runId: input.runId,
+                cancelRequested: false,
+                cancelReason: null,
+                cancelRequestedAt: null,
+                heartbeatAt: null,
+                workerId: null,
+                workerStartedAt: null,
+            }),
         ]);
     }
     async setRunState(threadId, runId, state, checkpointRef) {
@@ -165,7 +182,7 @@ export class FilePersistence {
         const sequenceId = String(event.sequence).padStart(6, "0");
         await writeJson(path.join(this.runDir(event.threadId, event.runId), "events", `${sequenceId}.json`), event);
     }
-    async listSessions() {
+    async listSessions(filter = {}) {
         const threadIndexDir = path.join(this.runRoot, "indexes", "threads");
         if (!(await fileExists(threadIndexDir))) {
             return [];
@@ -183,7 +200,9 @@ export class FilePersistence {
                 status: index.status,
             };
         }));
-        return records.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        return records
+            .filter((record) => !filter.agentId || record.agentId === filter.agentId)
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
     }
     async listRunIndexes() {
         const runIndexDir = path.join(this.runRoot, "indexes", "runs");
@@ -212,10 +231,23 @@ export class FilePersistence {
             resumable: lifecycle.resumable,
         };
     }
-    async listRuns() {
+    async listRuns(filter = {}) {
         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));
+        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;
+        })
+            .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
     }
     async getRun(runId) {
         const indexPath = this.runIndexPath(runId);
@@ -267,13 +299,25 @@ export class FilePersistence {
         const entries = (await readdir(eventsDir)).sort();
         return Promise.all(entries.map((entry) => readJson(path.join(eventsDir, entry))));
     }
-    async listApprovals() {
+    async listApprovals(filter = {}) {
         const approvalsDir = path.join(this.runRoot, "indexes", "approvals");
         if (!(await fileExists(approvalsDir))) {
             return [];
         }
         const entries = (await readdir(approvalsDir)).sort();
-        return Promise.all(entries.map((entry) => readJson(path.join(approvalsDir, entry))));
+        const approvals = await Promise.all(entries.map((entry) => readJson(path.join(approvalsDir, entry))));
+        return approvals.filter((approval) => {
+            if (filter.status && approval.status !== filter.status) {
+                return false;
+            }
+            if (filter.threadId && approval.threadId !== filter.threadId) {
+                return false;
+            }
+            if (filter.runId && approval.runId !== filter.runId) {
+                return false;
+            }
+            return true;
+        });
     }
     async getApproval(approvalId) {
         const approvalPath = path.join(this.runRoot, "indexes", "approvals", `${approvalId}.json`);
@@ -314,6 +358,9 @@ export class FilePersistence {
             ...approvals
                 .filter((record) => record.threadId === threadId)
                 .map((record) => rm(this.approvalIndexPath(record.approvalId), { force: true })),
+            ...runIndexes
+                .filter((record) => record.threadId === threadId)
+                .flatMap((record) => [rm(this.runQueuePath(record.runId), { force: true }), rm(this.runControlPath(record.runId), { force: true })]),
             ...delegations
                 .filter((record) => record.threadId === threadId)
                 .map((record) => rm(this.delegationIndexPath(record.delegationId), { force: true })),
@@ -427,4 +474,148 @@ export class FilePersistence {
         }
         await rm(intentPath, { force: true });
     }
+    async enqueueRun(input) {
+        const current = (await this.getQueuedRun(input.runId)) ?? {
+            runId: input.runId,
+            threadId: input.threadId,
+            priority: input.priority ?? 0,
+            queueKey: input.queueKey ?? null,
+            enqueuedAt: nowIso(),
+            availableAt: input.availableAt ?? nowIso(),
+            claimedBy: null,
+            claimedAt: null,
+            leaseExpiresAt: null,
+            attemptCount: 0,
+            lastError: null,
+        };
+        await writeJson(this.runQueuePath(input.runId), {
+            ...current,
+            threadId: input.threadId,
+            priority: input.priority ?? current.priority,
+            queueKey: input.queueKey ?? current.queueKey,
+            availableAt: input.availableAt ?? current.availableAt,
+            claimedBy: null,
+            claimedAt: null,
+            leaseExpiresAt: null,
+            lastError: null,
+        });
+    }
+    async getQueuedRun(runId) {
+        const filePath = this.runQueuePath(runId);
+        if (!(await fileExists(filePath))) {
+            return null;
+        }
+        return readJson(filePath);
+    }
+    async claimQueuedRun(input) {
+        const current = await this.getQueuedRun(input.runId);
+        if (!current) {
+            throw new Error(`Missing queued run ${input.runId}`);
+        }
+        const claimedAt = input.claimedAt ?? nowIso();
+        const next = {
+            ...current,
+            threadId: input.threadId,
+            claimedBy: input.workerId,
+            claimedAt,
+            leaseExpiresAt: input.leaseExpiresAt,
+            attemptCount: current.attemptCount + 1,
+        };
+        await writeJson(this.runQueuePath(input.runId), next);
+        await writeJson(this.runControlPath(input.runId), {
+            ...(await this.getRunControl(input.runId) ?? {
+                runId: input.runId,
+                cancelRequested: false,
+                cancelReason: null,
+                cancelRequestedAt: null,
+                heartbeatAt: null,
+                workerId: null,
+                workerStartedAt: null,
+            }),
+            heartbeatAt: claimedAt,
+            workerId: input.workerId,
+            workerStartedAt: claimedAt,
+        });
+        return next;
+    }
+    async renewRunLease(input) {
+        const current = await this.getQueuedRun(input.runId);
+        if (current) {
+            await writeJson(this.runQueuePath(input.runId), {
+                ...current,
+                claimedBy: input.workerId,
+                claimedAt: current.claimedAt ?? input.heartbeatAt ?? nowIso(),
+                leaseExpiresAt: input.leaseExpiresAt,
+            });
+        }
+        await writeJson(this.runControlPath(input.runId), {
+            ...(await this.getRunControl(input.runId) ?? {
+                runId: input.runId,
+                cancelRequested: false,
+                cancelReason: null,
+                cancelRequestedAt: null,
+                heartbeatAt: null,
+                workerId: null,
+                workerStartedAt: null,
+            }),
+            heartbeatAt: input.heartbeatAt ?? nowIso(),
+            workerId: input.workerId,
+            workerStartedAt: (await this.getRunControl(input.runId))?.workerStartedAt ?? input.heartbeatAt ?? nowIso(),
+        });
+    }
+    async releaseRunClaim(runId) {
+        await rm(this.runQueuePath(runId), { force: true });
+        const current = await this.getRunControl(runId);
+        if (!current) {
+            return;
+        }
+        await writeJson(this.runControlPath(runId), {
+            ...current,
+            heartbeatAt: null,
+            workerId: null,
+            workerStartedAt: null,
+        });
+    }
+    async listExpiredClaimedRuns(cutoffIso) {
+        const queueDir = path.join(this.runRoot, "indexes", "queue");
+        if (!(await fileExists(queueDir))) {
+            return [];
+        }
+        const entries = (await readdir(queueDir)).sort();
+        const records = await Promise.all(entries.map((entry) => readJson(path.join(queueDir, entry))));
+        return records.filter((record) => record.claimedBy && record.leaseExpiresAt && record.leaseExpiresAt <= cutoffIso);
+    }
+    async getRunControl(runId) {
+        const filePath = this.runControlPath(runId);
+        if (!(await fileExists(filePath))) {
+            return null;
+        }
+        return readJson(filePath);
+    }
+    async requestRunCancel(runId, reason) {
+        const current = await this.getRunControl(runId);
+        if (!current) {
+            throw new Error(`Missing run control for ${runId}`);
+        }
+        const updated = {
+            ...current,
+            cancelRequested: true,
+            cancelReason: reason ?? null,
+            cancelRequestedAt: nowIso(),
+        };
+        await writeJson(this.runControlPath(runId), updated);
+        return updated;
+    }
+    async clearRunCancel(runId) {
+        const current = await this.getRunControl(runId);
+        if (!current) {
+            return;
+        }
+        await writeJson(this.runControlPath(runId), {
+            ...current,
+            cancelRequested: false,
+            cancelReason: null,
+            cancelRequestedAt: null,
+        });
+    }
 }

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

@@ -1,5 +1,5 @@
 import type { ArtifactListing, ArtifactRecord, HarnessEvent, InternalApprovalRecord, RunState, RunSummary, ThreadRunRecord, ThreadSummary, TranscriptMessage } from "../contracts/types.js";
-import type { PersistedRunRequest, PersistenceLifecycle, PersistenceRunMeta, PersistenceThreadMeta, RecoveryIntent, RuntimePersistence } from "./types.js";
+import type { PersistedRunRequest, PersistedRunControlRecord, PersistedRunQueueRecord, PersistenceLifecycle, PersistenceRunMeta, PersistenceThreadMeta, RecoveryIntent, RuntimePersistence, ApprovalFilter, RunSummaryFilter, ThreadSummaryFilter } from "./types.js";
 export declare function listProtectedCheckpointThreadIds(dbPath: string): Promise<Set<string>>;
 export declare class SqlitePersistence implements RuntimePersistence {
     private readonly runRoot;
@@ -39,14 +39,14 @@ export declare class SqlitePersistence implements RuntimePersistence {
     }): Promise<void>;
     setRunState(threadId: string, runId: string, state: RunState, checkpointRef?: string | null): Promise<void>;
     appendEvent(event: HarnessEvent): Promise<void>;
-    listSessions(): Promise<ThreadSummary[]>;
-    listRuns(): Promise<RunSummary[]>;
+    listSessions(filter?: ThreadSummaryFilter): Promise<ThreadSummary[]>;
+    listRuns(filter?: RunSummaryFilter): Promise<RunSummary[]>;
     getRun(runId: string): Promise<RunSummary | null>;
     getSession(threadId: string): Promise<ThreadSummary | null>;
     getThreadMeta(threadId: string): Promise<PersistenceThreadMeta | null>;
     listThreadRuns(threadId: string): Promise<ThreadRunRecord[]>;
     listRunEvents(threadId: string, runId: string): Promise<HarnessEvent[]>;
-    listApprovals(): Promise<InternalApprovalRecord[]>;
+    listApprovals(filter?: ApprovalFilter): Promise<InternalApprovalRecord[]>;
     getApproval(approvalId: string): Promise<InternalApprovalRecord | null>;
     getRunApprovals(threadId: string, runId: string): Promise<InternalApprovalRecord[]>;
     getRunMeta(threadId: string, runId: string): Promise<PersistenceRunMeta>;
@@ -64,5 +64,33 @@ export declare class SqlitePersistence implements RuntimePersistence {
     saveRecoveryIntent(threadId: string, runId: string, intent: RecoveryIntent): Promise<void>;
     getRecoveryIntent(threadId: string, runId: string): Promise<RecoveryIntent | null>;
     clearRecoveryIntent(threadId: string, runId: string): Promise<void>;
+    private mapQueuedRun;
+    private mapRunControl;
+    enqueueRun(input: {
+        threadId: string;
+        runId: string;
+        priority?: number;
+        queueKey?: string | null;
+        availableAt?: string;
+    }): Promise<void>;
+    getQueuedRun(runId: string): Promise<PersistedRunQueueRecord | null>;
+    claimQueuedRun(input: {
+        threadId: string;
+        runId: string;
+        workerId: string;
+        claimedAt?: string;
+        leaseExpiresAt: string;
+    }): Promise<PersistedRunQueueRecord>;
+    renewRunLease(input: {
+        runId: string;
+        workerId: string;
+        heartbeatAt?: string;
+        leaseExpiresAt: string;
+    }): Promise<void>;
+    releaseRunClaim(runId: string): Promise<void>;
+    listExpiredClaimedRuns(cutoffIso: string): Promise<PersistedRunQueueRecord[]>;
+    getRunControl(runId: string): Promise<PersistedRunControlRecord | null>;
+    requestRunCancel(runId: string, reason?: string): Promise<PersistedRunControlRecord>;
+    clearRunCancel(runId: string): Promise<void>;
     readArtifact(threadId: string, runId: string, artifactPath: string): Promise<unknown>;
 }