@botbotgo/agent-harness 0.0.5 → 0.0.7

package/dist/api.d.ts

@@ -1,22 +1,14 @@
-import type { ArtifactListing, RestartConversationOptions, ResumeOptions, RunOptions, RuntimeAdapterOptions, SessionRecord, WorkspaceLoadOptions, WorkspaceBundle } from "./contracts/types.js";
+import type { AgentHarnessHandle, RunOptions, RuntimeAdapterOptions, ThreadRecord, WorkspaceLoadOptions, WorkspaceBundle } from "./contracts/types.js";
 import { AgentHarness } from "./runtime/harness.js";
-export declare function loadWorkspaceBundle(workspaceRoot: string, options?: WorkspaceLoadOptions): Promise<WorkspaceBundle>;
-export declare function createHarness(workspace: WorkspaceBundle, adapterOptions?: RuntimeAdapterOptions): AgentHarness;
-export declare function listHarnessSessions(harness: AgentHarness, filter?: {
-    agentId?: string;
-}): Promise<SessionRecord[]>;
-export declare function getHarnessApproval(harness: AgentHarness, approvalId: string): Promise<import("./contracts/types.js").ApprovalRecord | null>;
-export declare function runHarness(harness: AgentHarness, options: RunOptions): Promise<import("./contracts/types.js").RunResult>;
-export declare function streamHarness(harness: AgentHarness, options: RunOptions): Promise<AsyncGenerator<string, any, any>>;
-export declare function streamHarnessEvents(harness: AgentHarness, options: RunOptions): Promise<AsyncGenerator<import("./contracts/types.js").HarnessStreamItem, any, any>>;
-export declare function resumeHarness(harness: AgentHarness, options: ResumeOptions): Promise<import("./contracts/types.js").RunResult>;
-export declare function submitHarnessDecision(harness: AgentHarness, options: ResumeOptions): Promise<import("./contracts/types.js").RunResult>;
-export declare function approveHarnessRun(harness: AgentHarness, threadId: string, runId?: string): Promise<import("./contracts/types.js").RunResult>;
-export declare function rejectHarnessRun(harness: AgentHarness, threadId: string, runId?: string): Promise<import("./contracts/types.js").RunResult>;
-export declare function restartHarnessConversation(harness: AgentHarness, options: RestartConversationOptions): Promise<import("./contracts/types.js").RunResult & {
-    restart: Record<string, string>;
-}>;
-export declare function listHarnessArtifacts(harness: AgentHarness, threadId: string, runId?: string): Promise<ArtifactListing>;
-export declare function subscribeHarness(harness: AgentHarness, listener: Parameters<AgentHarness["subscribe"]>[0]): () => void;
-export declare function closeHarness(harness: AgentHarness): Promise<void>;
-export { loadWorkspaceBundle as loadWorkspaceFacade, listHarnessSessions as listSessionsFacade, getHarnessApproval as getApprovalFacade, runHarness as runFacade, streamHarness as streamFacade, streamHarnessEvents as streamEventsFacade, resumeHarness as resumeFacade, submitHarnessDecision as submitDecisionFacade, approveHarnessRun as approveFacade, rejectHarnessRun as rejectFacade, restartHarnessConversation as restartConversationFacade, listHarnessArtifacts as artifactsFacade, subscribeHarness as subscribeFacade, closeHarness as closeFacade, };
+type CreateAgentHarnessOptions = {
+    load?: WorkspaceLoadOptions;
+    adapter?: RuntimeAdapterOptions;
+};
+export declare function createAgentHarness(): Promise<AgentHarnessHandle>;
+export declare function createAgentHarness(workspaceRoot: string, options?: CreateAgentHarnessOptions): Promise<AgentHarnessHandle>;
+export declare function createAgentHarness(workspace: WorkspaceBundle, options?: CreateAgentHarnessOptions): Promise<AgentHarnessHandle>;
+export declare function run(harness: AgentHarnessHandle, options: RunOptions): Promise<import("./contracts/types.js").RunResult>;
+export declare function subscribe(harness: AgentHarnessHandle, listener: Parameters<AgentHarness["subscribe"]>[0]): () => void;
+export declare function getThread(harness: AgentHarnessHandle, threadId: string): Promise<ThreadRecord | null>;
+export declare function stop(harness: AgentHarnessHandle): Promise<void>;
+export {};

package/dist/api.js

@@ -1,48 +1,47 @@
 import { AgentHarness } from "./runtime/harness.js";
 import { loadWorkspace } from "./workspace/compile.js";
-export async function loadWorkspaceBundle(workspaceRoot, options = {}) {
-    return loadWorkspace(workspaceRoot, options);
+const HARNESS_INSTANCE = Symbol.for("@botbotgo/agent-harness/instance");
+function registerHarness(harness) {
+    const handle = { kind: "AgentHarnessHandle" };
+    Object.defineProperty(handle, HARNESS_INSTANCE, {
+        value: harness,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return Object.freeze(handle);
+}
+function requireHarness(handle) {
+    if (handle instanceof AgentHarness) {
+        return handle;
+    }
+    if (typeof handle === "object" && handle !== null && "run" in handle && "subscribe" in handle && "close" in handle) {
+        return handle;
+    }
+    const harness = handle[HARNESS_INSTANCE];
+    if (!harness) {
+        throw new Error("Unknown or stopped AgentHarnessHandle");
+    }
+    return harness;
+}
+export async function createAgentHarness(input = process.cwd(), options = {}) {
+    const workspace = typeof input === "string"
+        ? await loadWorkspace(input, options.load ?? {})
+        : input;
+    const harness = new AgentHarness(workspace, options.adapter ?? {});
+    await harness.initialize();
+    return registerHarness(harness);
+}
+export async function run(harness, options) {
+    return requireHarness(harness).run(options);
+}
+export function subscribe(harness, listener) {
+    return requireHarness(harness).subscribe(listener);
+}
+export async function getThread(harness, threadId) {
+    return requireHarness(harness).getThread(threadId);
+}
+export async function stop(harness) {
+    const instance = requireHarness(harness);
+    return instance.close();
 }
-export function createHarness(workspace, adapterOptions = {}) {
-    return new AgentHarness(workspace, adapterOptions);
-}
-export async function listHarnessSessions(harness, filter) {
-    return harness.listSessions(filter);
-}
-export async function getHarnessApproval(harness, approvalId) {
-    return harness.getApproval(approvalId);
-}
-export async function runHarness(harness, options) {
-    return harness.run(options);
-}
-export async function streamHarness(harness, options) {
-    return harness.stream(options);
-}
-export async function streamHarnessEvents(harness, options) {
-    return harness.streamEvents(options);
-}
-export async function resumeHarness(harness, options) {
-    return harness.resume(options);
-}
-export async function submitHarnessDecision(harness, options) {
-    return harness.submitDecision(options);
-}
-export async function approveHarnessRun(harness, threadId, runId) {
-    return harness.approve(threadId, runId);
-}
-export async function rejectHarnessRun(harness, threadId, runId) {
-    return harness.reject(threadId, runId);
-}
-export async function restartHarnessConversation(harness, options) {
-    return harness.restartConversation(options);
-}
-export async function listHarnessArtifacts(harness, threadId, runId) {
-    return harness.artifacts(threadId, runId);
-}
-export function subscribeHarness(harness, listener) {
-    return harness.subscribe(listener);
-}
-export async function closeHarness(harness) {
-    return harness.close();
-}
-export { loadWorkspaceBundle as loadWorkspaceFacade, listHarnessSessions as listSessionsFacade, getHarnessApproval as getApprovalFacade, runHarness as runFacade, streamHarness as streamFacade, streamHarnessEvents as streamEventsFacade, resumeHarness as resumeFacade, submitHarnessDecision as submitDecisionFacade, approveHarnessRun as approveFacade, rejectHarnessRun as rejectFacade, restartHarnessConversation as restartConversationFacade, listHarnessArtifacts as artifactsFacade, subscribeHarness as subscribeFacade, closeHarness as closeFacade, };

package/dist/contracts/types.d.ts

@@ -171,7 +171,7 @@ export type WorkspaceLoadOptions = {
     overlayRoots?: string[];
     builtinSources?: string[];
 };
-export type SessionRecord = {
+export type ThreadSummary = {
     agentId: string;
     threadId: string;
     latestRunId: string;
@@ -179,6 +179,7 @@ export type SessionRecord = {
     updatedAt: string;
     status: RunState;
 };
+export type SessionRecord = ThreadSummary;
 export type HarnessEvent = {
     eventId: string;
     eventType: string;
@@ -200,11 +201,31 @@ export type RunResult = {
     pendingActionId?: string;
     delegationId?: string;
 };
-export type RunOptions = {
+export type RunListeners = {
+    onChunk?: (chunk: string) => void | Promise<void>;
+    onEvent?: (event: HarnessEvent) => void | Promise<void>;
+    onReasoning?: (chunk: string) => void | Promise<void>;
+    onStep?: (step: string) => void | Promise<void>;
+    onToolResult?: (item: {
+        toolName: string;
+        output: unknown;
+    }) => void | Promise<void>;
+};
+export type RunStartOptions = {
     agentId?: string;
     input: string;
     threadId?: string;
+    listeners?: RunListeners;
 };
+export type RunDecisionOptions = {
+    threadId: string;
+    runId?: string;
+    approvalId?: string;
+    decision: "approve" | "edit" | "reject";
+    editedInput?: Record<string, unknown>;
+    listeners?: RunListeners;
+};
+export type RunOptions = RunStartOptions | RunDecisionOptions;
 export type HarnessStreamItem = {
     type: "event";
     event: HarnessEvent;
@@ -240,6 +261,33 @@ export type TranscriptMessage = {
     runId: string;
     createdAt: string;
 };
+export type ThreadRunRecord = {
+    runId: string;
+    agentId: string;
+    executionMode: string;
+    createdAt: string;
+    updatedAt: string;
+    state: RunState;
+    checkpointRef: string | null;
+    resumable: boolean;
+};
+export type ThreadRecord = {
+    threadId: string;
+    entryAgentId: string;
+    currentState: RunState;
+    latestRunId: string;
+    createdAt: string;
+    updatedAt: string;
+    messages: TranscriptMessage[];
+    runs: ThreadRunRecord[];
+    pendingDecision?: {
+        approvalId: string;
+        pendingActionId: string;
+        toolName: string;
+        allowedDecisions: Array<"approve" | "edit" | "reject">;
+        requestedAt: string;
+    };
+};
 export type ResumeOptions = {
     threadId?: string;
     runId?: string;
@@ -357,3 +405,6 @@ export type EventSubscriber = {
     kind: string;
     onEvent: (event: HarnessEvent) => void | Promise<void>;
 };
+export type AgentHarnessHandle = {
+    readonly kind: "AgentHarnessHandle";
+};

package/dist/index.d.ts

@@ -1,7 +1 @@
-export * from "./contracts/types.js";
-export * from "./extensions.js";
-export * from "./api.js";
-export * from "./presentation.js";
-export * from "./runtime/index.js";
-export * from "./workspace/index.js";
-export { createBuiltinBackendResolver, createBuiltinToolResolver } from "./vendor/builtins.js";
+export { createAgentHarness, getThread, run, subscribe, stop } from "./api.js";

package/dist/index.js

@@ -1,7 +1 @@
-export * from "./contracts/types.js";
-export * from "./extensions.js";
-export * from "./api.js";
-export * from "./presentation.js";
-export * from "./runtime/index.js";
-export * from "./workspace/index.js";
-export { createBuiltinBackendResolver, createBuiltinToolResolver } from "./vendor/builtins.js";
+export { createAgentHarness, getThread, run, subscribe, stop } from "./api.js";

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

@@ -1,4 +1,13 @@
-import type { ApprovalRecord, ArtifactListing, ArtifactRecord, DelegationRecord, HarnessEvent, RunState, SessionRecord, TranscriptMessage } from "../contracts/types.js";
+import type { ApprovalRecord, ArtifactListing, ArtifactRecord, DelegationRecord, HarnessEvent, RunState, ThreadSummary, ThreadRunRecord, TranscriptMessage } from "../contracts/types.js";
+type ThreadMeta = {
+    threadId: string;
+    workspaceId: string;
+    entryAgentId: string;
+    createdAt: string;
+    updatedAt: string;
+    status: RunState;
+    latestRunId: string;
+};
 export declare class FilePersistence {
     private readonly runRoot;
     constructor(runRoot: string);
@@ -21,8 +30,10 @@ export declare class FilePersistence {
     }): Promise<void>;
     setRunState(threadId: string, runId: string, state: RunState, checkpointRef?: string | null): Promise<void>;
     appendEvent(event: HarnessEvent): Promise<void>;
-    listSessions(): Promise<SessionRecord[]>;
-    getSession(threadId: string): Promise<SessionRecord | null>;
+    listSessions(): Promise<ThreadSummary[]>;
+    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<ApprovalRecord[]>;
     getApproval(approvalId: string): Promise<ApprovalRecord | null>;
@@ -37,3 +48,4 @@ export declare class FilePersistence {
     appendThreadMessage(threadId: string, message: TranscriptMessage): Promise<void>;
     listThreadMessages(threadId: string, limit?: number): Promise<TranscriptMessage[]>;
 }
+export {};

package/dist/persistence/file-store.js

@@ -94,7 +94,11 @@ export class FilePersistence {
     }
     async setRunState(threadId, runId, state, checkpointRef) {
         const lifecyclePath = path.join(this.runDir(threadId, runId), "lifecycle.json");
-        const lifecycle = await readJson(lifecyclePath);
+        const runMetaPath = path.join(this.runDir(threadId, runId), "meta.json");
+        const [lifecycle, runMeta] = await Promise.all([
+            readJson(lifecyclePath),
+            readJson(runMetaPath),
+        ]);
         const now = new Date().toISOString();
         const next = {
             state,
@@ -104,7 +108,13 @@ export class FilePersistence {
             resumable: state === "waiting_for_approval",
             checkpointRef: checkpointRef ?? lifecycle.checkpointRef,
         };
-        await writeJson(lifecyclePath, next);
+        await Promise.all([
+            writeJson(lifecyclePath, next),
+            writeJson(runMetaPath, {
+                ...runMeta,
+                updatedAt: now,
+            }),
+        ]);
         if (checkpointRef !== undefined) {
             await writeJson(path.join(this.runDir(threadId, runId), "checkpoint-ref.json"), {
                 threadId,
@@ -176,6 +186,38 @@ export class FilePersistence {
             status: index.status,
         };
     }
+    async getThreadMeta(threadId) {
+        const filePath = path.join(this.threadDir(threadId), "meta.json");
+        if (!(await fileExists(filePath))) {
+            return null;
+        }
+        return readJson(filePath);
+    }
+    async listThreadRuns(threadId) {
+        const runsDir = path.join(this.threadDir(threadId), "runs");
+        if (!(await fileExists(runsDir))) {
+            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,
+                createdAt: meta.createdAt,
+                updatedAt: meta.updatedAt,
+                state: lifecycle.state,
+                checkpointRef: lifecycle.checkpointRef,
+                resumable: lifecycle.resumable,
+            };
+        }));
+        return runs.sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+    }
     async listRunEvents(threadId, runId) {
         const eventsDir = path.join(this.runDir(threadId, runId), "events");
         if (!(await fileExists(eventsDir))) {

package/dist/runtime/agent-runtime-adapter.js

@@ -5,7 +5,7 @@ import { ChatGoogle } from "@langchain/google";
 import { ChatOllama } from "@langchain/ollama";
 import { ChatOpenAI } from "@langchain/openai";
 import { createAgent, humanInTheLoopMiddleware, initChatModel } from "langchain";
-import { extractReasoningText, extractToolFallbackContext, extractVisibleOutput, isLikelyToolArgsObject, isToolCallParseFailure, STRICT_TOOL_JSON_INSTRUCTION, sanitizeVisibleText, tryParseJson, wrapResolvedModel, } from "./parsing/output-parsing.js";
+import { extractEmptyAssistantMessageFailure, extractReasoningText, extractToolFallbackContext, extractVisibleOutput, isLikelyToolArgsObject, isToolCallParseFailure, STRICT_TOOL_JSON_INSTRUCTION, sanitizeVisibleText, tryParseJson, wrapResolvedModel, } from "./parsing/output-parsing.js";
 import { extractAgentStep, extractInterruptPayload, extractReasoningStreamOutput, extractTerminalStreamOutput, extractToolResult, normalizeTerminalOutputKey, readStreamDelta, } from "./parsing/stream-event-parsing.js";
 import { wrapToolForExecution } from "./tool-hitl.js";
 const AGENT_INTERRUPT_SENTINEL_PREFIX = "__agent_harness_interrupt__:";
@@ -382,8 +382,13 @@ export class AgentRuntimeAdapter {
         const interruptContent = Array.isArray(result.__interrupt__) && result.__interrupt__.length > 0 ? JSON.stringify(result.__interrupt__) : undefined;
         const extractedOutput = extractVisibleOutput(result);
         const visibleOutput = extractedOutput && !isLikelyToolArgsObject(tryParseJson(extractedOutput)) ? extractedOutput : "";
+        const emptyAssistantMessageFailure = extractEmptyAssistantMessageFailure(result);
         const toolFallback = extractToolFallbackContext(result);
-        const output = visibleOutput || (await this.synthesizeDeepAgentAnswer(binding, input, result)) || toolFallback || JSON.stringify(result, null, 2);
+        const synthesizedOutput = await this.synthesizeDeepAgentAnswer(binding, input, result);
+        if (!visibleOutput && !synthesizedOutput && !toolFallback && emptyAssistantMessageFailure) {
+            throw new Error(emptyAssistantMessageFailure);
+        }
+        const output = visibleOutput || synthesizedOutput || toolFallback || JSON.stringify(result, null, 2);
         return {
             threadId,
             runId,

package/dist/runtime/harness.d.ts

@@ -1,5 +1,4 @@
-import { Readable } from "node:stream";
-import type { ApprovalRecord, ArtifactListing, DelegationRecord, HarnessEvent, HarnessStreamItem, RestartConversationOptions, RuntimeAdapterOptions, ResumeOptions, RunOptions, RunResult, SessionRecord, WorkspaceBundle } from "../contracts/types.js";
+import type { ApprovalRecord, HarnessEvent, HarnessStreamItem, RunStartOptions, RestartConversationOptions, RuntimeAdapterOptions, ResumeOptions, RunOptions, RunResult, ThreadSummary, ThreadRecord, WorkspaceBundle } from "../contracts/types.js";
 export declare class AgentHarness {
     private readonly workspace;
     private readonly runtimeAdapterOptions;
@@ -25,31 +24,25 @@ export declare class AgentHarness {
     private resolveVectorStore;
     constructor(workspace: WorkspaceBundle, runtimeAdapterOptions?: RuntimeAdapterOptions);
     initialize(): Promise<void>;
-    subscribeEvents(listener: (event: HarnessEvent) => void): () => void;
     subscribe(listener: (event: HarnessEvent) => void): () => void;
     listSessions(filter?: {
         agentId?: string;
-    }): Promise<SessionRecord[]>;
-    getSession(threadId: string): Promise<SessionRecord | null>;
-    getEvents(threadId: string, runId?: string): Promise<HarnessEvent[]>;
+    }): Promise<ThreadSummary[]>;
+    private getSession;
+    getThread(threadId: string): Promise<ThreadRecord | null>;
     listPendingApprovals(): Promise<ApprovalRecord[]>;
-    getApproval(approvalId: string): Promise<ApprovalRecord | null>;
-    listDelegations(): Promise<DelegationRecord[]>;
     routeAgent(input: string, options?: {
         threadId?: string;
     }): Promise<string>;
-    artifacts(threadId: string, runId?: string): Promise<ArtifactListing>;
     private emit;
     private persistApproval;
     private resolveApprovalRecord;
+    private isDecisionRun;
+    private notifyListener;
+    private dispatchRunListeners;
     run(options: RunOptions): Promise<RunResult>;
-    stream(options: RunOptions): AsyncGenerator<string>;
-    streamEvents(options: RunOptions): AsyncGenerator<HarnessStreamItem>;
-    streamReadable(options: RunOptions): Promise<Readable>;
+    streamEvents(options: RunStartOptions): AsyncGenerator<HarnessStreamItem>;
     resume(options: ResumeOptions): Promise<RunResult>;
-    submitDecision(options: ResumeOptions): Promise<RunResult>;
-    approve(threadId: string, runId?: string): Promise<RunResult>;
-    reject(threadId: string, runId?: string): Promise<RunResult>;
     restartConversation(options: RestartConversationOptions): Promise<RunResult & {
         restart: Record<string, string>;
     }>;

package/dist/runtime/harness.js

@@ -1,4 +1,3 @@
-import { Readable } from "node:stream";
 import { AUTO_AGENT_ID } from "../contracts/types.js";
 import { FilePersistence } from "../persistence/file-store.js";
 import { createPersistentId } from "../utils/id.js";
@@ -147,38 +146,57 @@ export class AgentHarness {
     async initialize() {
         await this.persistence.initialize();
     }
-    subscribeEvents(listener) {
-        return this.eventBus.subscribe(listener);
-    }
     subscribe(listener) {
-        return this.subscribeEvents(listener);
+        return this.eventBus.subscribe(listener);
     }
     async listSessions(filter) {
-        const sessions = await this.persistence.listSessions();
+        const threadSummaries = await this.persistence.listSessions();
         if (!filter?.agentId) {
-            return sessions;
+            return threadSummaries;
         }
-        return sessions.filter((session) => session.agentId === filter.agentId);
+        return threadSummaries.filter((thread) => thread.agentId === filter.agentId);
     }
     async getSession(threadId) {
         return this.persistence.getSession(threadId);
     }
-    async getEvents(threadId, runId) {
-        const session = await this.getSession(threadId);
-        if (!session) {
-            throw new Error(`Unknown thread ${threadId}`);
-        }
-        return this.persistence.listRunEvents(threadId, runId ?? session.latestRunId);
+    async getThread(threadId) {
+        const [threadSummary, meta, messages, runs] = await Promise.all([
+            this.getSession(threadId),
+            this.persistence.getThreadMeta(threadId),
+            this.persistence.listThreadMessages(threadId, 200),
+            this.persistence.listThreadRuns(threadId),
+        ]);
+        if (!threadSummary || !meta) {
+            return null;
+        }
+        const latestRunId = threadSummary.latestRunId;
+        const latestApprovals = await this.persistence.getRunApprovals(threadId, latestRunId);
+        const pendingApproval = latestApprovals
+            .filter((approval) => approval.status === "pending")
+            .sort((left, right) => right.requestedAt.localeCompare(left.requestedAt))[0];
+        return {
+            threadId,
+            entryAgentId: meta.entryAgentId,
+            currentState: threadSummary.status,
+            latestRunId,
+            createdAt: meta.createdAt,
+            updatedAt: threadSummary.updatedAt,
+            messages,
+            runs,
+            pendingDecision: pendingApproval
+                ? {
+                    approvalId: pendingApproval.approvalId,
+                    pendingActionId: pendingApproval.pendingActionId,
+                    toolName: pendingApproval.toolName,
+                    allowedDecisions: pendingApproval.allowedDecisions,
+                    requestedAt: pendingApproval.requestedAt,
+                }
+                : undefined,
+        };
     }
     async listPendingApprovals() {
         return (await this.persistence.listApprovals()).filter((approval) => approval.status === "pending");
     }
-    async getApproval(approvalId) {
-        return this.persistence.getApproval(approvalId);
-    }
-    async listDelegations() {
-        return this.persistence.listDelegations();
-    }
     async routeAgent(input, options = {}) {
         const routingInput = await this.buildRoutingInput(input, options.threadId);
         const normalized = input.trim().toLowerCase();
@@ -210,13 +228,6 @@ export class AgentHarness {
             return heuristicRoute(input, primaryBinding, secondaryBinding);
         }
     }
-    async artifacts(threadId, runId) {
-        const session = await this.getSession(threadId);
-        if (!session) {
-            throw new Error(`Unknown thread ${threadId}`);
-        }
-        return this.persistence.listArtifacts(threadId, runId ?? session.latestRunId);
-    }
     async emit(threadId, runId, sequence, eventType, payload, source = "runtime") {
         const event = createHarnessEvent(threadId, runId, sequence, eventType, payload, source);
         await this.persistence.appendEvent(event);
@@ -239,7 +250,7 @@ export class AgentHarness {
         });
         return approval;
     }
-    async resolveApprovalRecord(options, session) {
+    async resolveApprovalRecord(options, thread) {
         if (options.approvalId) {
             const approval = await this.persistence.getApproval(options.approvalId);
             if (!approval) {
@@ -247,8 +258,8 @@ export class AgentHarness {
             }
             return approval;
         }
-        const runId = options.runId ?? session.latestRunId;
-        const approvals = await this.persistence.getRunApprovals(options.threadId ?? session.threadId, runId);
+        const runId = options.runId ?? thread.latestRunId;
+        const approvals = await this.persistence.getRunApprovals(options.threadId ?? thread.threadId, runId);
         const approval = approvals
             .filter((candidate) => candidate.status === "pending")
             .sort((left, right) => right.requestedAt.localeCompare(left.requestedAt))[0];
@@ -257,7 +268,75 @@ export class AgentHarness {
         }
         return approval;
     }
+    isDecisionRun(options) {
+        return "decision" in options;
+    }
+    async notifyListener(listener, value) {
+        if (!listener) {
+            return;
+        }
+        await listener(value);
+    }
+    async dispatchRunListeners(stream, listeners) {
+        let latestEvent;
+        let output = "";
+        for await (const item of stream) {
+            if (item.type === "event") {
+                latestEvent = item.event;
+                await this.notifyListener(listeners.onEvent, item.event);
+                continue;
+            }
+            if (item.type === "content") {
+                output += item.content;
+                await this.notifyListener(listeners.onChunk, item.content);
+                continue;
+            }
+            if (item.type === "reasoning") {
+                await this.notifyListener(listeners.onReasoning, item.content);
+                continue;
+            }
+            if (item.type === "step") {
+                await this.notifyListener(listeners.onStep, item.content);
+                continue;
+            }
+            if (item.type === "tool-result") {
+                await this.notifyListener(listeners.onToolResult, {
+                    toolName: item.toolName,
+                    output: item.output,
+                });
+            }
+        }
+        if (!latestEvent) {
+            throw new Error("run did not emit any events");
+        }
+        const thread = await this.getThread(latestEvent.threadId);
+        if (!thread) {
+            throw new Error(`Unknown thread ${latestEvent.threadId}`);
+        }
+        return {
+            threadId: thread.threadId,
+            runId: thread.latestRunId,
+            agentId: thread.runs[0]?.agentId ?? thread.entryAgentId,
+            state: thread.currentState,
+            output,
+            approvalId: thread.pendingDecision?.approvalId,
+            pendingActionId: thread.pendingDecision?.pendingActionId,
+        };
+    }
     async run(options) {
+        if (this.isDecisionRun(options)) {
+            const resumeOptions = {
+                threadId: options.threadId,
+                runId: options.runId,
+                approvalId: options.approvalId,
+                decision: options.decision,
+                editedInput: options.editedInput,
+            };
+            return this.resume(resumeOptions);
+        }
+        if (options.listeners) {
+            return this.dispatchRunListeners(this.streamEvents(options), options.listeners);
+        }
         const selectedAgentId = await this.resolveSelectedAgentId(options.input, options.agentId, options.threadId);
         const binding = this.workspace.bindings.get(selectedAgentId);
         if (!binding) {
@@ -359,13 +438,6 @@ export class AgentHarness {
             };
         }
     }
-    async *stream(options) {
-        for await (const item of this.streamEvents(options)) {
-            if (item.type === "content") {
-                yield item.content;
-            }
-        }
-    }
     async *streamEvents(options) {
         const selectedAgentId = await this.resolveSelectedAgentId(options.input, options.agentId, options.threadId);
         const binding = this.workspace.bindings.get(selectedAgentId);
@@ -592,25 +664,22 @@ export class AgentHarness {
             }
         }
     }
-    async streamReadable(options) {
-        return Readable.from(this.stream(options));
-    }
     async resume(options) {
         const approvalById = options.approvalId ? await this.persistence.getApproval(options.approvalId) : null;
-        const session = options.threadId
+        const thread = options.threadId
             ? await this.getSession(options.threadId)
             : approvalById
                 ? await this.getSession(approvalById.threadId)
                 : null;
-        if (!session) {
+        if (!thread) {
             throw new Error("resume requires either threadId or approvalId");
         }
-        const approval = approvalById ?? await this.resolveApprovalRecord(options, session);
+        const approval = approvalById ?? await this.resolveApprovalRecord(options, thread);
         const threadId = approval.threadId;
         const runId = approval.runId;
-        const binding = this.workspace.bindings.get(session.agentId);
+        const binding = this.workspace.bindings.get(thread.agentId);
         if (!binding) {
-            throw new Error(`Unknown agent ${session.agentId}`);
+            throw new Error(`Unknown agent ${thread.agentId}`);
         }
         await this.persistence.setRunState(threadId, runId, "resuming", `checkpoints/${threadId}/${runId}/cp-1`);
         await this.emit(threadId, runId, 5, "run.resumed", {
@@ -655,24 +724,15 @@ export class AgentHarness {
             pendingActionId: approval.pendingActionId,
         };
     }
-    async submitDecision(options) {
-        return this.resume(options);
-    }
-    async approve(threadId, runId) {
-        return this.submitDecision({ threadId, runId, decision: "approve" });
-    }
-    async reject(threadId, runId) {
-        return this.submitDecision({ threadId, runId, decision: "reject" });
-    }
     async restartConversation(options) {
-        const session = await this.getSession(options.threadId);
-        if (!session) {
+        const thread = await this.getSession(options.threadId);
+        if (!thread) {
             throw new Error(`Unknown thread ${options.threadId}`);
         }
-        const sourceRunId = session.latestRunId;
+        const sourceRunId = thread.latestRunId;
         const targetThreadId = options.mode === "restart-new-thread" ? createPersistentId() : options.threadId;
         const result = await this.run({
-            agentId: session.agentId,
+            agentId: thread.agentId,
             input: options.input,
             threadId: options.mode === "restart-new-thread" ? undefined : targetThreadId,
         });

package/dist/runtime/parsing/output-parsing.d.ts

@@ -6,6 +6,7 @@ export declare function readTextContent(value: unknown): string;
 export declare function hasToolCalls(value: unknown): boolean;
 export declare function extractToolFallbackContext(value: unknown): string;
 export declare function extractVisibleOutput(value: unknown): string;
+export declare function extractEmptyAssistantMessageFailure(value: unknown): string;
 export declare function isToolCallParseFailure(error: unknown): boolean;
 export declare const STRICT_TOOL_JSON_INSTRUCTION = "When calling tools, return only the tool call itself. The arguments must be a pure JSON object with no explanatory text before or after it.";
 export declare function wrapResolvedModel<T>(value: T): T;

package/dist/runtime/parsing/output-parsing.js

@@ -225,19 +225,56 @@ function extractAssistantTextFromMessages(messages) {
             : typeof message.getType === "function"
                 ? message.getType()
                 : undefined;
+        if (!(typeName === "AIMessage" || runtimeType === "ai"))
+            continue;
         const kwargs = typeof typed.kwargs === "object" && typed.kwargs ? typed.kwargs : undefined;
-        if (typeName === "AIMessage" || runtimeType === "ai" || kwargs?.content !== undefined) {
-            if (hasToolCalls(message))
-                continue;
-            if (Array.isArray(kwargs?.tool_calls) && kwargs.tool_calls.length > 0)
-                continue;
-            const content = extractMessageContent(message);
-            if (content)
-                return content;
-        }
+        if (hasToolCalls(message))
+            continue;
+        if (Array.isArray(kwargs?.tool_calls) && kwargs.tool_calls.length > 0)
+            continue;
+        const content = extractMessageContent(message);
+        if (content)
+            return content;
     }
     return "";
 }
+function extractEmptyAssistantMessageReason(messages) {
+    if (!Array.isArray(messages))
+        return null;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (typeof message !== "object" || !message)
+            continue;
+        const typed = message;
+        const ids = Array.isArray(typed.id) ? typed.id.filter((item) => typeof item === "string") : [];
+        const typeName = ids.at(-1);
+        const runtimeType = typeof message._getType === "function"
+            ? message._getType()
+            : typeof message.getType === "function"
+                ? message.getType()
+                : undefined;
+        const kwargs = typeof typed.kwargs === "object" && typed.kwargs ? typed.kwargs : undefined;
+        if (!(typeName === "AIMessage" || runtimeType === "ai")) {
+            continue;
+        }
+        if (hasToolCalls(message)) {
+            return null;
+        }
+        const content = extractMessageContent(message).trim();
+        if (content) {
+            return null;
+        }
+        const responseMetadata = typeof kwargs?.response_metadata === "object" && kwargs.response_metadata
+            ? kwargs.response_metadata
+            : {};
+        return {
+            finishReason: typeof responseMetadata.finish_reason === "string" ? responseMetadata.finish_reason : undefined,
+            modelProvider: typeof responseMetadata.model_provider === "string" ? responseMetadata.model_provider : undefined,
+            modelName: typeof responseMetadata.model_name === "string" ? responseMetadata.model_name : undefined,
+        };
+    }
+    return null;
+}
 function extractStructuredOutputText(value) {
     if (typeof value !== "object" || !value)
         return "";
@@ -304,6 +341,27 @@ export function extractVisibleOutput(value) {
     }
     return "";
 }
+export function extractEmptyAssistantMessageFailure(value) {
+    if (typeof value !== "object" || !value)
+        return "";
+    const typed = value;
+    const reason = extractEmptyAssistantMessageReason(typed.messages)
+        ?? (typeof typed.output === "object" && typed.output
+            ? extractEmptyAssistantMessageReason(typed.output.messages)
+            : null);
+    if (!reason) {
+        return "";
+    }
+    const detailParts = [
+        reason.finishReason ? `finish_reason=${reason.finishReason}` : "",
+        reason.modelProvider ? `model_provider=${reason.modelProvider}` : "",
+        reason.modelName ? `model_name=${reason.modelName}` : "",
+    ].filter(Boolean);
+    return [
+        "empty_final_ai_message: model returned no visible assistant content and no tool calls",
+        detailParts.length > 0 ? `(${detailParts.join(", ")})` : "",
+    ].filter(Boolean).join(" ");
+}
 function isAiMessageLike(value) {
     if (typeof value !== "object" || !value)
         return false;

package/dist/runtime/thread-memory-sync.js

@@ -5,17 +5,17 @@ function excerpt(message) {
     const normalized = message.content.replace(/\s+/g, " ").trim();
     return normalized.length > 240 ? `${normalized.slice(0, 237)}...` : normalized;
 }
-function renderStatusMarkdown(session, messages) {
+function renderStatusMarkdown(thread, messages) {
     const userMessages = messages.filter((message) => message.role === "user");
     const assistantMessages = messages.filter((message) => message.role === "assistant");
     return [
         "# Thread Status",
         "",
-        `- thread_id: ${session.threadId}`,
-        `- latest_run_id: ${session.latestRunId}`,
-        `- agent_id: ${session.agentId}`,
-        `- status: ${session.status}`,
-        `- updated_at: ${session.updatedAt}`,
+        `- thread_id: ${thread.threadId}`,
+        `- latest_run_id: ${thread.latestRunId}`,
+        `- agent_id: ${thread.agentId}`,
+        `- status: ${thread.status}`,
+        `- updated_at: ${thread.updatedAt}`,
         "",
         "## Recent User Message",
         excerpt(userMessages.at(-1)),
@@ -64,8 +64,8 @@ export class ThreadMemorySync {
         await task;
     }
     async syncThread(threadId) {
-        const session = await this.persistence.getSession(threadId);
-        if (!session) {
+        const thread = await this.persistence.getSession(threadId);
+        if (!thread) {
             return;
         }
         const [messages, approvals] = await Promise.all([
@@ -77,7 +77,7 @@ export class ThreadMemorySync {
             return;
         }
         await Promise.all([
-            this.store.put(["memories", "threads", threadId], "status.md", { content: `${renderStatusMarkdown(session, messages)}\n` }),
+            this.store.put(["memories", "threads", threadId], "status.md", { content: `${renderStatusMarkdown(thread, messages)}\n` }),
             this.store.put(["memories", "threads", threadId], "open-approvals.md", { content: `${renderOpenApprovalsMarkdown(pendingApprovals)}\n` }),
         ]);
     }

package/dist/workspace/support/discovery.js

@@ -10,13 +10,41 @@ function resolveBuiltinPath(kind, ref) {
             throw new Error(`Unsupported builtin skill discovery path ${ref}`);
         }
         const suffix = normalized.replace(/^skills\/?/, "");
-        return suffix ? path.join(builtinSkillsRoot(), suffix) : builtinSkillsRoot();
+        const root = builtinSkillsRoot();
+        if (!suffix) {
+            return root;
+        }
+        const candidate = path.join(root, suffix);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        const sourceFallback = root.includes(`${path.sep}dist${path.sep}skills`)
+            ? path.join(path.resolve(root, "..", ".."), "skills", suffix)
+            : null;
+        if (sourceFallback && existsSync(sourceFallback)) {
+            return sourceFallback;
+        }
+        return candidate;
     }
     if (!normalized.startsWith("agents")) {
         throw new Error(`Unsupported builtin subagent discovery path ${ref}`);
     }
     const suffix = normalized.replace(/^agents\/?/, "");
-    return suffix ? path.join(builtinConfigRoot(), "agents", suffix) : path.join(builtinConfigRoot(), "agents");
+    const root = path.join(builtinConfigRoot(), "agents");
+    if (!suffix) {
+        return root;
+    }
+    const candidate = path.join(root, suffix);
+    if (existsSync(candidate)) {
+        return candidate;
+    }
+    const sourceFallback = root.includes(`${path.sep}dist${path.sep}config${path.sep}agents`)
+        ? path.join(path.resolve(root, "..", "..", ".."), "config", "agents", suffix)
+        : null;
+    if (sourceFallback && existsSync(sourceFallback)) {
+        return sourceFallback;
+    }
+    return candidate;
 }
 function preferPackageConvention(root, kind) {
     const candidates = kind === "skills"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Agent Harness framework package",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,7 +25,7 @@
     }
   },
   "dependencies": {
-    "@botbotgo/agent-harness-builtin": "0.0.5"
+    "@botbotgo/agent-harness-builtin": "0.0.7"
   },
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && cp -R config dist/",