@botbotgo/agent-harness 0.0.39 → 0.0.41

package/README.md

@@ -111,11 +111,23 @@ import { run } from "@botbotgo/agent-harness";
 const result = await run(runtime, {
   agentId: "orchestra",
   input: "Explain the available agents in this workspace.",
+  context: {
+    requestId: "req-123",
+  },
+  state: {
+    visitCount: 1,
+  },
 });
 ```
 
 Each run creates or continues a persisted thread. The result includes `threadId`, `runId`, `state`, and `output`.
 
+When the underlying LangChain or DeepAgents graph expects extra invocation data, `run(...)` can pass it through without inventing a parallel harness abstraction:
+
+- `context`: forwarded as LangChain v1 runtime context
+- `state`: merged into the agent invocation input for stateful graphs
+- `files`: merged into the agent invocation input so DeepAgents state-backed skills or memories can be provided at call time
+
 ### Let The Runtime Route
 
 ```ts

package/dist/config/workspace.yaml

@@ -58,7 +58,7 @@ spec:
     #     regex:
     #       - "\\b(create|build|implement|fix|review|debug|inspect|analy[sz]e|download|clone)\\b"
     rules:
-      - agentId: research-lite
+      - agentId: orchestra
         contains: ["latest", "recent", "today", "current", "news", "最新", "最近", "今天", "当前", "新闻", "头条", "研究", "调研"]
       - agentId: orchestra
         regex:
@@ -102,3 +102,17 @@ spec:
   #     sqlite:
   #       sweepBatchSize: 200
   #       vacuum: false
+
+  # agent-harness feature: runtime-managed recovery policy for interrupted runs.
+  # This keeps checkpoint resume as an internal lifecycle concern instead of a primary user-facing API concept.
+  #
+  # Current support:
+  # - startup recovery of runs already in `resuming` state
+  # - persisted approval-decision intent for cross-restart resume continuation
+  # - bounded retry attempts to avoid infinite restart loops
+  #
+  # Example:
+  # recovery:
+  #   enabled: true
+  #   resumeResumingRunsOnStartup: true
+  #   maxRecoveryAttempts: 3

package/dist/contracts/types.d.ts

@@ -86,9 +86,13 @@ export type LangChainAgentParams = {
     model: CompiledModel;
     tools: CompiledTool[];
     systemPrompt?: string;
+    stateSchema?: unknown;
     responseFormat?: unknown;
     contextSchema?: unknown;
     middleware?: Array<Record<string, unknown>>;
+    includeAgentName?: "inline";
+    version?: "v1" | "v2";
+    name?: string;
     description: string;
 };
 export type CompiledSubAgent = {
@@ -119,6 +123,8 @@ export type DeepAgentParams = {
     name: string;
     memory: string[];
     skills: string[];
+    generalPurposeAgent?: boolean;
+    taskDescription?: string;
 };
 export type CompiledModel = {
     id: string;
@@ -262,6 +268,9 @@ export type RunStartOptions = {
     agentId?: string;
     input: MessageContent;
     threadId?: string;
+    context?: Record<string, unknown>;
+    state?: Record<string, unknown>;
+    files?: Record<string, unknown>;
     listeners?: RunListeners;
 };
 export type RunDecisionOptions = {

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.38";
+export declare const AGENT_HARNESS_VERSION = "0.0.40";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.38";
+export const AGENT_HARNESS_VERSION = "0.0.40";

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

@@ -8,6 +8,36 @@ type ThreadMeta = {
     status: RunState;
     latestRunId: string;
 };
+type RunMeta = {
+    runId: string;
+    threadId: string;
+    agentId: string;
+    executionMode: string;
+    createdAt: string;
+    updatedAt: string;
+};
+type Lifecycle = {
+    state: RunState;
+    previousState: RunState | null;
+    stateEnteredAt: string;
+    lastTransitionAt: string;
+    resumable: boolean;
+    checkpointRef: string | null;
+};
+type RunIndexRecord = {
+    runId: string;
+    threadId: string;
+    state: RunState;
+    resumable: boolean;
+    updatedAt: string;
+};
+type RecoveryIntent = {
+    kind: "approval-decision";
+    savedAt: string;
+    checkpointRef: string | null;
+    resumePayload: unknown;
+    attempts: number;
+};
 export declare class FilePersistence {
     private readonly runRoot;
     constructor(runRoot: string);
@@ -31,6 +61,7 @@ export declare class FilePersistence {
     setRunState(threadId: string, runId: string, state: RunState, checkpointRef?: string | null): Promise<void>;
     appendEvent(event: HarnessEvent): Promise<void>;
     listSessions(): Promise<ThreadSummary[]>;
+    listRunIndexes(): Promise<RunIndexRecord[]>;
     getSession(threadId: string): Promise<ThreadSummary | null>;
     getThreadMeta(threadId: string): Promise<ThreadMeta | null>;
     listThreadRuns(threadId: string): Promise<ThreadRunRecord[]>;
@@ -38,6 +69,8 @@ export declare class FilePersistence {
     listApprovals(): Promise<ApprovalRecord[]>;
     getApproval(approvalId: string): Promise<ApprovalRecord | null>;
     getRunApprovals(threadId: string, runId: string): Promise<ApprovalRecord[]>;
+    getRunMeta(threadId: string, runId: string): Promise<RunMeta>;
+    getRunLifecycle(threadId: string, runId: string): Promise<Lifecycle>;
     listDelegations(): Promise<DelegationRecord[]>;
     createApproval(record: ApprovalRecord): Promise<void>;
     resolveApproval(threadId: string, runId: string, approvalId: string, status: ApprovalRecord["status"]): Promise<ApprovalRecord>;
@@ -47,5 +80,8 @@ export declare class FilePersistence {
     listArtifacts(threadId: string, runId: string): Promise<ArtifactListing>;
     appendThreadMessage(threadId: string, message: TranscriptMessage): Promise<void>;
     listThreadMessages(threadId: string, limit?: number): Promise<TranscriptMessage[]>;
+    saveRecoveryIntent(threadId: string, runId: string, intent: RecoveryIntent): Promise<void>;
+    getRecoveryIntent(threadId: string, runId: string): Promise<RecoveryIntent | null>;
+    clearRecoveryIntent(threadId: string, runId: string): Promise<void>;
 }
 export {};

package/dist/persistence/file-store.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { rm } from "node:fs/promises";
 import { readdir } from "node:fs/promises";
 import { ensureDir, fileExists, readJson, writeJson } from "../utils/fs.js";
 export class FilePersistence {
@@ -168,6 +169,14 @@ export class FilePersistence {
         }));
         return records.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
     }
+    async listRunIndexes() {
+        const runIndexDir = path.join(this.runRoot, "indexes", "runs");
+        if (!(await fileExists(runIndexDir))) {
+            return [];
+        }
+        const entries = (await readdir(runIndexDir)).sort();
+        return Promise.all(entries.map((entry) => readJson(path.join(runIndexDir, entry))));
+    }
     async getSession(threadId) {
         const filePath = path.join(this.runRoot, "indexes", "threads", `${threadId}.json`);
         if (!(await fileExists(filePath))) {
@@ -249,6 +258,12 @@ export class FilePersistence {
         const entries = (await readdir(approvalsDir)).sort();
         return Promise.all(entries.map((entry) => readJson(path.join(approvalsDir, entry))));
     }
+    async getRunMeta(threadId, runId) {
+        return readJson(path.join(this.runDir(threadId, runId), "meta.json"));
+    }
+    async getRunLifecycle(threadId, runId) {
+        return readJson(path.join(this.runDir(threadId, runId), "lifecycle.json"));
+    }
     async listDelegations() {
         const delegationsDir = path.join(this.runRoot, "indexes", "delegations");
         if (!(await fileExists(delegationsDir))) {
@@ -321,4 +336,21 @@ export class FilePersistence {
         const current = await readJson(messagesPath);
         return current.items.slice(-limit);
     }
+    async saveRecoveryIntent(threadId, runId, intent) {
+        await writeJson(path.join(this.runDir(threadId, runId), "recovery-intent.json"), intent);
+    }
+    async getRecoveryIntent(threadId, runId) {
+        const intentPath = path.join(this.runDir(threadId, runId), "recovery-intent.json");
+        if (!(await fileExists(intentPath))) {
+            return null;
+        }
+        return readJson(intentPath);
+    }
+    async clearRecoveryIntent(threadId, runId) {
+        const intentPath = path.join(this.runDir(threadId, runId), "recovery-intent.json");
+        if (!(await fileExists(intentPath))) {
+            return;
+        }
+        await rm(intentPath, { force: true });
+    }
 }

package/dist/runtime/agent-runtime-adapter.d.ts

@@ -27,6 +27,7 @@ export declare class AgentRuntimeAdapter {
     private resolveModel;
     private buildToolNameMapping;
     private buildAgentMessages;
+    private buildInvocationRequest;
     private buildRawModelMessages;
     private resolveTools;
     private normalizeInterruptPolicy;
@@ -40,7 +41,15 @@ export declare class AgentRuntimeAdapter {
     route(input: MessageContent, primaryBinding: CompiledAgentBinding, secondaryBinding: CompiledAgentBinding, options?: {
         systemPrompt?: string;
     }): Promise<string>;
-    invoke(binding: CompiledAgentBinding, input: MessageContent, threadId: string, runId: string, resumePayload?: unknown, history?: TranscriptMessage[]): Promise<RunResult>;
-    stream(binding: CompiledAgentBinding, input: MessageContent, threadId: string, history?: TranscriptMessage[]): AsyncGenerator<RuntimeStreamChunk | string>;
+    invoke(binding: CompiledAgentBinding, input: MessageContent, threadId: string, runId: string, resumePayload?: unknown, history?: TranscriptMessage[], options?: {
+        context?: Record<string, unknown>;
+        state?: Record<string, unknown>;
+        files?: Record<string, unknown>;
+    }): Promise<RunResult>;
+    stream(binding: CompiledAgentBinding, input: MessageContent, threadId: string, history?: TranscriptMessage[], options?: {
+        context?: Record<string, unknown>;
+        state?: Record<string, unknown>;
+        files?: Record<string, unknown>;
+    }): AsyncGenerator<RuntimeStreamChunk | string>;
 }
 export { AgentRuntimeAdapter as RuntimeAdapter, AGENT_INTERRUPT_SENTINEL_PREFIX, AGENT_INTERRUPT_SENTINEL_PREFIX as INTERRUPT_SENTINEL_PREFIX, RuntimeOperationTimeoutError, };

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

@@ -377,6 +377,13 @@ export class AgentRuntimeAdapter {
             { role: "user", content: normalizeMessageContent(input) },
         ];
     }
+    buildInvocationRequest(history, input, options = {}) {
+        return {
+            ...(options.state ?? {}),
+            ...(options.files ? { files: options.files } : {}),
+            messages: this.buildAgentMessages(history, input),
+        };
+    }
     buildRawModelMessages(systemPrompt, history, input) {
         const messages = [];
         if (systemPrompt) {
@@ -503,10 +510,16 @@ export class AgentRuntimeAdapter {
                 model: model,
                 tools: tools,
                 systemPrompt: binding.langchainAgentParams.systemPrompt,
+                stateSchema: binding.langchainAgentParams.stateSchema,
                 responseFormat: binding.langchainAgentParams.responseFormat,
                 contextSchema: binding.langchainAgentParams.contextSchema,
                 middleware: (await this.resolveMiddleware(binding, interruptOn)),
                 checkpointer: this.resolveCheckpointer(binding),
+                store: this.options.storeResolver?.(binding),
+                includeAgentName: binding.langchainAgentParams.includeAgentName,
+                version: binding.langchainAgentParams.version,
+                name: binding.langchainAgentParams.name,
+                description: binding.langchainAgentParams.description,
             });
         }
         const params = binding.deepAgentParams;
@@ -545,6 +558,8 @@ export class AgentRuntimeAdapter {
             name: params.name,
             memory: params.memory,
             skills: params.skills,
+            generalPurposeAgent: params.generalPurposeAgent,
+            taskDescription: params.taskDescription,
         };
         return createDeepAgent(deepAgentConfig);
     }
@@ -577,14 +592,14 @@ export class AgentRuntimeAdapter {
             ? secondaryBinding.agent.id
             : primaryBinding.agent.id;
     }
-    async invoke(binding, input, threadId, runId, resumePayload, history = []) {
+    async invoke(binding, input, threadId, runId, resumePayload, history = [], options = {}) {
         const request = resumePayload === undefined
-            ? { messages: this.buildAgentMessages(history, input) }
+            ? this.buildInvocationRequest(history, input, options)
             : new Command({ resume: resumePayload });
         let result;
         try {
             const runnable = await this.create(binding);
-            result = (await this.withTimeout(() => runnable.invoke(request, { configurable: { thread_id: threadId } }), this.resolveBindingTimeout(binding), "agent invoke", "invoke"));
+            result = (await this.withTimeout(() => runnable.invoke(request, { configurable: { thread_id: threadId }, ...(options.context ? { context: options.context } : {}) }), this.resolveBindingTimeout(binding), "agent invoke", "invoke"));
         }
         catch (error) {
             if (resumePayload !== undefined || !isToolCallParseFailure(error)) {
@@ -592,7 +607,7 @@ export class AgentRuntimeAdapter {
             }
             const retriedBinding = this.applyStrictToolJsonInstruction(binding);
             const runnable = await this.create(retriedBinding);
-            result = (await this.withTimeout(() => runnable.invoke({ messages: this.buildAgentMessages(history, input) }, { configurable: { thread_id: threadId } }), this.resolveBindingTimeout(retriedBinding), "agent invoke", "invoke"));
+            result = (await this.withTimeout(() => runnable.invoke(this.buildInvocationRequest(history, input, options), { configurable: { thread_id: threadId }, ...(options.context ? { context: options.context } : {}) }), this.resolveBindingTimeout(retriedBinding), "agent invoke", "invoke"));
         }
         const interruptContent = Array.isArray(result.__interrupt__) && result.__interrupt__.length > 0 ? JSON.stringify(result.__interrupt__) : undefined;
         const extractedOutput = extractVisibleOutput(result);
@@ -613,7 +628,7 @@ export class AgentRuntimeAdapter {
             output: sanitizeVisibleText(output),
         };
     }
-    async *stream(binding, input, threadId, history = []) {
+    async *stream(binding, input, threadId, history = [], options = {}) {
         try {
             const invokeTimeoutMs = this.resolveBindingTimeout(binding);
             const streamIdleTimeoutMs = this.resolveStreamIdleTimeout(binding);
@@ -651,9 +666,9 @@ export class AgentRuntimeAdapter {
                 }
             }
             const runnable = await this.create(binding);
-            const request = { messages: this.buildAgentMessages(history, input) };
+            const request = this.buildInvocationRequest(history, input, options);
             if (typeof runnable.streamEvents === "function") {
-                const events = await this.withTimeout(() => runnable.streamEvents(request, { configurable: { thread_id: threadId }, version: "v2" }), computeRemainingTimeoutMs(streamDeadlineAt, invokeTimeoutMs), "agent streamEvents start", "stream");
+                const events = await this.withTimeout(() => runnable.streamEvents(request, { configurable: { thread_id: threadId }, version: "v2", ...(options.context ? { context: options.context } : {}) }), computeRemainingTimeoutMs(streamDeadlineAt, invokeTimeoutMs), "agent streamEvents start", "stream");
                 const allowVisibleStreamDeltas = Boolean(binding.langchainAgentParams);
                 let emittedOutput = "";
                 let emittedToolError = false;

package/dist/runtime/declared-middleware.js

@@ -1,4 +1,4 @@
-import { modelCallLimitMiddleware, modelRetryMiddleware, summarizationMiddleware, todoListMiddleware, toolCallLimitMiddleware, toolRetryMiddleware, } from "langchain";
+import { anthropicPromptCachingMiddleware, contextEditingMiddleware, llmToolSelectorMiddleware, modelCallLimitMiddleware, modelFallbackMiddleware, modelRetryMiddleware, openAIModerationMiddleware, summarizationMiddleware, todoListMiddleware, toolCallLimitMiddleware, toolEmulatorMiddleware, toolRetryMiddleware, } from "langchain";
 function asMiddlewareConfig(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value) ? { ...value } : null;
 }
@@ -13,6 +13,18 @@ function omitKind(config) {
     const { kind: _kind, ...rest } = config;
     return rest;
 }
+async function resolveReferencedModel(value, options) {
+    if (value && typeof value === "object" && "id" in value) {
+        return options.resolveModel(value);
+    }
+    return value;
+}
+async function resolveReferencedModelList(values, options) {
+    if (!Array.isArray(values)) {
+        return undefined;
+    }
+    return Promise.all(values.map((value) => resolveReferencedModel(value, options)));
+}
 export async function resolveDeclaredMiddleware(middlewareConfigs, options) {
     const resolved = [];
     for (const rawConfig of middlewareConfigs ?? []) {
@@ -24,18 +36,29 @@ export async function resolveDeclaredMiddleware(middlewareConfigs, options) {
         const runtimeConfig = omitKind(config);
         switch (kind) {
             case "summarization": {
-                if (runtimeConfig.model && typeof runtimeConfig.model === "object" && runtimeConfig.model !== null && "id" in runtimeConfig.model) {
-                    runtimeConfig.model = await options.resolveModel(runtimeConfig.model);
-                }
+                runtimeConfig.model = await resolveReferencedModel(runtimeConfig.model, options);
                 if (runtimeConfig.model === undefined) {
                     throw new Error("summarization middleware requires model or modelRef");
                 }
                 resolved.push(summarizationMiddleware(runtimeConfig));
                 break;
             }
+            case "llmToolSelector":
+                runtimeConfig.model = await resolveReferencedModel(runtimeConfig.model, options);
+                resolved.push(llmToolSelectorMiddleware(runtimeConfig));
+                break;
             case "modelRetry":
                 resolved.push(modelRetryMiddleware(runtimeConfig));
                 break;
+            case "modelFallback": {
+                const fallbackModels = (await resolveReferencedModelList(runtimeConfig.fallbackModels, options)) ??
+                    (await resolveReferencedModelList(runtimeConfig.models, options));
+                if (!fallbackModels || fallbackModels.length === 0) {
+                    throw new Error("modelFallback middleware requires fallbackModels or models");
+                }
+                resolved.push(modelFallbackMiddleware(...fallbackModels));
+                break;
+            }
             case "toolRetry":
                 resolved.push(toolRetryMiddleware(runtimeConfig));
                 break;
@@ -48,6 +71,18 @@ export async function resolveDeclaredMiddleware(middlewareConfigs, options) {
             case "todoList":
                 resolved.push(todoListMiddleware(runtimeConfig));
                 break;
+            case "contextEditing":
+                resolved.push(contextEditingMiddleware(runtimeConfig));
+                break;
+            case "toolEmulator":
+                resolved.push(toolEmulatorMiddleware(runtimeConfig));
+                break;
+            case "openAIModeration":
+                resolved.push(openAIModerationMiddleware(runtimeConfig));
+                break;
+            case "anthropicPromptCaching":
+                resolved.push(anthropicPromptCachingMiddleware(runtimeConfig));
+                break;
             default:
                 throw new Error(`Unsupported declarative middleware kind ${kind}`);
         }

package/dist/runtime/harness.d.ts

@@ -20,6 +20,7 @@ export declare class AgentHarnessRuntime {
     private readonly unregisterThreadMemorySync;
     private readonly resolvedRuntimeAdapterOptions;
     private readonly checkpointMaintenance;
+    private readonly recoveryConfig;
     private listHostBindings;
     private defaultRunRoot;
     private heuristicRoute;
@@ -53,8 +54,11 @@ export declare class AgentHarnessRuntime {
     private emit;
     private ensureThreadStarted;
     private loadPriorHistory;
+    private loadRunInput;
     private appendAssistantMessage;
     private invokeWithHistory;
+    private checkpointRefForState;
+    private finalizeContinuedRun;
     private emitOutputDeltaAndCreateItem;
     private emitRunCreated;
     private setRunStateAndEmit;
@@ -73,5 +77,6 @@ export declare class AgentHarnessRuntime {
     }>;
     close(): Promise<void>;
     stop(): Promise<void>;
+    private recoverStartupRuns;
 }
 export { AgentHarnessRuntime as AgentHarness };

package/dist/runtime/harness.js

@@ -5,7 +5,7 @@ import { AGENT_INTERRUPT_SENTINEL_PREFIX, AgentRuntimeAdapter, RuntimeOperationT
 import { createResourceBackendResolver, createResourceToolResolver } from "../resource/resource.js";
 import { EventBus } from "./event-bus.js";
 import { PolicyEngine } from "./policy-engine.js";
-import { getRoutingDefaultAgentId, getRoutingRules, getRoutingSystemPrompt, isModelRoutingEnabled, matchRoutingRule, } from "../workspace/support/workspace-ref-utils.js";
+import { getRecoveryConfig, getRoutingDefaultAgentId, getRoutingRules, getRoutingSystemPrompt, isModelRoutingEnabled, matchRoutingRule, } from "../workspace/support/workspace-ref-utils.js";
 import { createHarnessEvent, createPendingApproval, heuristicRoute, inferRoutingBindings, renderRuntimeFailure, renderToolFailure, } from "./support/harness-support.js";
 import { createCheckpointerForConfig, createStoreForConfig } from "./support/runtime-factories.js";
 import { resolveCompiledEmbeddingModel, resolveCompiledEmbeddingModelRef } from "./support/embedding-models.js";
@@ -35,6 +35,7 @@ export class AgentHarnessRuntime {
     unregisterThreadMemorySync;
     resolvedRuntimeAdapterOptions;
     checkpointMaintenance;
+    recoveryConfig;
     listHostBindings() {
         return inferRoutingBindings(this.workspace).hostBindings;
     }
@@ -157,10 +158,12 @@ export class AgentHarnessRuntime {
         this.checkpointMaintenance = checkpointMaintenanceConfig
             ? new CheckpointMaintenanceLoop(discoverCheckpointMaintenanceTargets(workspace), checkpointMaintenanceConfig)
             : null;
+        this.recoveryConfig = getRecoveryConfig(workspace.refs);
     }
     async initialize() {
         await this.persistence.initialize();
         await this.checkpointMaintenance?.start();
+        await this.recoverStartupRuns();
     }
     subscribe(listener) {
         return this.eventBus.subscribe(listener);
@@ -338,6 +341,11 @@ export class AgentHarnessRuntime {
         const history = await this.persistence.listThreadMessages(threadId);
         return history.filter((message) => message.runId !== runId);
     }
+    async loadRunInput(threadId, runId) {
+        const history = await this.persistence.listThreadMessages(threadId, 100);
+        const userTurn = history.find((message) => message.runId === runId && message.role === "user");
+        return userTurn?.content ?? "";
+    }
     async appendAssistantMessage(threadId, runId, content) {
         if (!content) {
             return;
@@ -349,9 +357,31 @@ export class AgentHarnessRuntime {
             createdAt: new Date().toISOString(),
         });
     }
-    async invokeWithHistory(binding, input, threadId, runId, resumePayload) {
+    async invokeWithHistory(binding, input, threadId, runId, resumePayload, options = {}) {
         const priorHistory = await this.loadPriorHistory(threadId, runId);
-        return this.runtimeAdapter.invoke(binding, input, threadId, runId, resumePayload, priorHistory);
+        return this.runtimeAdapter.invoke(binding, input, threadId, runId, resumePayload, priorHistory, options);
+    }
+    checkpointRefForState(threadId, runId, state) {
+        return state === "waiting_for_approval" ? `checkpoints/${threadId}/${runId}/cp-1` : null;
+    }
+    async finalizeContinuedRun(threadId, runId, input, actual, options) {
+        let approval;
+        await this.appendAssistantMessage(threadId, runId, actual.output);
+        const checkpointRef = this.checkpointRefForState(threadId, runId, actual.state);
+        await this.setRunStateAndEmit(threadId, runId, options.stateSequence, actual.state, {
+            previousState: options.previousState,
+            checkpointRef,
+        });
+        if (actual.state === "waiting_for_approval" && options.approvalSequence) {
+            approval = (await this.requestApprovalAndEmit(threadId, runId, input, actual.interruptContent, checkpointRef, options.approvalSequence)).approval;
+        }
+        return {
+            ...actual,
+            threadId,
+            runId,
+            approvalId: approval?.approvalId ?? actual.approvalId,
+            pendingActionId: approval?.pendingActionId ?? actual.pendingActionId,
+        };
     }
     async emitOutputDeltaAndCreateItem(threadId, runId, agentId, content) {
         await this.emit(threadId, runId, 3, "output.delta", {
@@ -516,24 +546,19 @@ export class AgentHarnessRuntime {
             executionMode: binding.agent.executionMode,
         });
         try {
-            const actual = await this.invokeWithHistory(binding, options.input, threadId, runId);
-            let approval;
-            await this.appendAssistantMessage(threadId, runId, actual.output);
-            const checkpointRef = actual.state === "waiting_for_approval" ? `checkpoints/${threadId}/${runId}/cp-1` : null;
-            await this.setRunStateAndEmit(threadId, runId, 3, actual.state, {
+            const actual = await this.invokeWithHistory(binding, options.input, threadId, runId, undefined, {
+                context: options.context,
+                state: options.state,
+                files: options.files,
+            });
+            const finalized = await this.finalizeContinuedRun(threadId, runId, options.input, actual, {
                 previousState: null,
-                checkpointRef,
+                stateSequence: 3,
+                approvalSequence: 4,
             });
-            if (actual.state === "waiting_for_approval") {
-                approval = (await this.requestApprovalAndEmit(threadId, runId, options.input, actual.interruptContent, checkpointRef, 4)).approval;
-            }
             return {
-                ...actual,
-                threadId,
-                runId,
+                ...finalized,
                 agentId: selectedAgentId,
-                approvalId: approval?.approvalId ?? actual.approvalId,
-                pendingActionId: approval?.pendingActionId ?? actual.pendingActionId,
             };
         }
         catch (error) {
@@ -580,7 +605,11 @@ export class AgentHarnessRuntime {
             const priorHistory = await this.loadPriorHistory(threadId, runId);
             let assistantOutput = "";
             const toolErrors = [];
-            for await (const chunk of this.runtimeAdapter.stream(binding, options.input, threadId, priorHistory)) {
+            for await (const chunk of this.runtimeAdapter.stream(binding, options.input, threadId, priorHistory, {
+                context: options.context,
+                state: options.state,
+                files: options.files,
+            })) {
                 if (chunk) {
                     const normalizedChunk = typeof chunk === "string"
                         ? chunk.startsWith(AGENT_INTERRUPT_SENTINEL_PREFIX)
@@ -734,6 +763,15 @@ export class AgentHarnessRuntime {
             throw new Error(`Unknown agent ${thread.agentId}`);
         }
         await this.persistence.setRunState(threadId, runId, "resuming", `checkpoints/${threadId}/${runId}/cp-1`);
+        await this.persistence.saveRecoveryIntent(threadId, runId, {
+            kind: "approval-decision",
+            savedAt: new Date().toISOString(),
+            checkpointRef: `checkpoints/${threadId}/${runId}/cp-1`,
+            resumePayload: options.decision === "edit" && options.editedInput
+                ? { decision: "edit", editedInput: options.editedInput }
+                : (options.decision ?? "approve"),
+            attempts: 0,
+        });
         await this.emit(threadId, runId, 5, "run.resumed", {
             resumeKind: "cross-restart",
             checkpointRef: `checkpoints/${threadId}/${runId}/cp-1`,
@@ -750,24 +788,27 @@ export class AgentHarnessRuntime {
         });
         const history = await this.persistence.listThreadMessages(threadId);
         const priorHistory = history.filter((message) => message.runId !== runId);
+        const runInput = await this.loadRunInput(threadId, runId);
         const resumeDecision = options.decision === "edit" && options.editedInput
             ? { decision: "edit", editedInput: options.editedInput }
             : (options.decision ?? "approve");
-        const actual = await this.runtimeAdapter.invoke(binding, "", threadId, runId, resumeDecision, priorHistory);
-        await this.appendAssistantMessage(threadId, runId, actual.output);
-        await this.persistence.setRunState(threadId, runId, actual.state, actual.state === "waiting_for_approval" ? `checkpoints/${threadId}/${runId}/cp-1` : null);
-        await this.emit(threadId, runId, 7, "run.state.changed", {
-            previousState: "resuming",
-            state: actual.state,
-            checkpointRef: actual.state === "waiting_for_approval" ? `checkpoints/${threadId}/${runId}/cp-1` : null,
-        });
-        return {
-            ...actual,
-            threadId,
-            runId,
-            approvalId: approval.approvalId,
-            pendingActionId: approval.pendingActionId,
-        };
+        try {
+            const actual = await this.runtimeAdapter.invoke(binding, "", threadId, runId, resumeDecision, priorHistory);
+            await this.persistence.clearRecoveryIntent(threadId, runId);
+            const finalized = await this.finalizeContinuedRun(threadId, runId, runInput, actual, {
+                previousState: "resuming",
+                stateSequence: 7,
+                approvalSequence: 8,
+            });
+            return {
+                ...finalized,
+                approvalId: finalized.approvalId ?? approval.approvalId,
+                pendingActionId: finalized.pendingActionId ?? approval.pendingActionId,
+            };
+        }
+        catch (error) {
+            throw error;
+        }
     }
     async restartConversation(options) {
         const thread = await this.getSession(options.threadId);
@@ -802,5 +843,62 @@ export class AgentHarnessRuntime {
     async stop() {
         await this.close();
     }
+    async recoverStartupRuns() {
+        if (!this.recoveryConfig.enabled || !this.recoveryConfig.resumeResumingRunsOnStartup) {
+            return;
+        }
+        const threads = await this.persistence.listSessions();
+        for (const thread of threads) {
+            if (thread.status !== "resuming") {
+                continue;
+            }
+            const binding = this.workspace.bindings.get(thread.agentId);
+            if (!binding) {
+                continue;
+            }
+            const recoveryIntent = await this.persistence.getRecoveryIntent(thread.threadId, thread.latestRunId);
+            if (!recoveryIntent || recoveryIntent.kind !== "approval-decision") {
+                continue;
+            }
+            if (recoveryIntent.attempts >= this.recoveryConfig.maxRecoveryAttempts) {
+                await this.persistence.setRunState(thread.threadId, thread.latestRunId, "failed", recoveryIntent.checkpointRef);
+                await this.persistence.clearRecoveryIntent(thread.threadId, thread.latestRunId);
+                continue;
+            }
+            await this.persistence.saveRecoveryIntent(thread.threadId, thread.latestRunId, {
+                ...recoveryIntent,
+                attempts: recoveryIntent.attempts + 1,
+            });
+            await this.emit(thread.threadId, thread.latestRunId, 100, "run.resumed", {
+                resumeKind: "startup-recovery",
+                checkpointRef: recoveryIntent.checkpointRef,
+                state: "resuming",
+            });
+            const history = await this.persistence.listThreadMessages(thread.threadId);
+            const priorHistory = history.filter((message) => message.runId !== thread.latestRunId);
+            const runInput = await this.loadRunInput(thread.threadId, thread.latestRunId);
+            try {
+                const actual = await this.runtimeAdapter.invoke(binding, "", thread.threadId, thread.latestRunId, recoveryIntent.resumePayload, priorHistory);
+                await this.persistence.clearRecoveryIntent(thread.threadId, thread.latestRunId);
+                await this.finalizeContinuedRun(thread.threadId, thread.latestRunId, runInput, actual, {
+                    previousState: "resuming",
+                    stateSequence: 101,
+                    approvalSequence: 102,
+                });
+            }
+            catch (error) {
+                if (recoveryIntent.attempts + 1 >= this.recoveryConfig.maxRecoveryAttempts) {
+                    await this.persistence.setRunState(thread.threadId, thread.latestRunId, "failed", recoveryIntent.checkpointRef);
+                    await this.persistence.clearRecoveryIntent(thread.threadId, thread.latestRunId);
+                    await this.emit(thread.threadId, thread.latestRunId, 101, "run.state.changed", {
+                        previousState: "resuming",
+                        state: "failed",
+                        checkpointRef: recoveryIntent.checkpointRef,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        }
+    }
 }
 export { AgentHarnessRuntime as AgentHarness };

package/dist/workspace/agent-binding-compiler.js

@@ -43,6 +43,22 @@ function compileMiddlewareConfigs(middleware, models, ownerId) {
             compiled.model = requireModel(models, compiled.modelRef, ownerId);
             delete compiled.modelRef;
         }
+        if (compiled.kind === "llmToolSelector" && typeof compiled.modelRef === "string") {
+            compiled.model = requireModel(models, compiled.modelRef, ownerId);
+            delete compiled.modelRef;
+        }
+        if (compiled.kind === "modelFallback") {
+            const fallbackModelRefs = Array.isArray(compiled.fallbackModelRefs)
+                ? compiled.fallbackModelRefs
+                : Array.isArray(compiled.modelRefs)
+                    ? compiled.modelRefs
+                    : [];
+            if (fallbackModelRefs.length > 0) {
+                compiled.fallbackModels = fallbackModelRefs.map((modelRef) => requireModel(models, String(modelRef), ownerId));
+                delete compiled.fallbackModelRefs;
+                delete compiled.modelRefs;
+            }
+        }
         return compiled;
     });
 }
@@ -162,9 +178,15 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
             model: compiledAgentModel,
             tools: requireTools(tools, agent.toolRefs, agent.id),
             systemPrompt: resolveSystemPrompt(agent),
+            stateSchema: agent.langchainAgentConfig?.stateSchema,
             responseFormat: agent.langchainAgentConfig?.responseFormat,
             contextSchema: agent.langchainAgentConfig?.contextSchema,
             middleware: compileMiddlewareConfigs(agent.langchainAgentConfig?.middleware, models, agent.id),
+            includeAgentName: agent.langchainAgentConfig?.includeAgentName === "inline" ? "inline" : undefined,
+            version: agent.langchainAgentConfig?.version === "v1" || agent.langchainAgentConfig?.version === "v2"
+                ? agent.langchainAgentConfig.version
+                : undefined,
+            name: resolveAgentRuntimeName(agent),
             description: agent.description,
         };
         return {
@@ -196,6 +218,10 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
             name: resolveAgentRuntimeName(agent),
             memory: compiledAgentMemory,
             skills: compiledAgentSkills,
+            generalPurposeAgent: typeof agent.deepAgentConfig?.generalPurposeAgent === "boolean" ? agent.deepAgentConfig.generalPurposeAgent : undefined,
+            taskDescription: typeof agent.deepAgentConfig?.taskDescription === "string" && agent.deepAgentConfig.taskDescription.trim()
+                ? agent.deepAgentConfig.taskDescription
+                : undefined,
         },
     };
 }

package/dist/workspace/compile.js

@@ -5,7 +5,7 @@ import { validateAgent, validateTopology } from "./validate.js";
 import { compileBinding } from "./agent-binding-compiler.js";
 import { discoverSubagents, ensureDiscoverySources } from "./support/discovery.js";
 import { collectAgentDiscoverySourceRefs, collectToolSourceRefs } from "./support/source-collectors.js";
-import { resolveRefId } from "./support/workspace-ref-utils.js";
+import { getRoutingDefaultAgentId, getRoutingRules, resolveRefId, } from "./support/workspace-ref-utils.js";
 import { hydrateAgentMcpTools, hydrateResourceAndExternalTools } from "./tool-hydration.js";
 function collectParsedResources(refs) {
     const embeddings = new Map();
@@ -70,6 +70,20 @@ function compileBindings(workspaceRoot, refs, agentsList, models, tools) {
     }
     return bindings;
 }
+function validateRoutingTargets(refs, agentsList) {
+    const hostFacingAgentIds = new Set(agentsList
+        .filter((agent) => !agentsList.some((owner) => owner.subagentRefs.some((ref) => resolveRefId(ref) === agent.id)))
+        .map((agent) => agent.id));
+    const defaultAgentId = getRoutingDefaultAgentId(refs);
+    if (defaultAgentId && !hostFacingAgentIds.has(defaultAgentId)) {
+        throw new Error(`Runtime routing.defaultAgentId references unknown host-facing agent ${defaultAgentId}`);
+    }
+    for (const rule of getRoutingRules(refs)) {
+        if (!hostFacingAgentIds.has(rule.agentId)) {
+            throw new Error(`Runtime routing.rules references unknown host-facing agent ${rule.agentId}`);
+        }
+    }
+}
 export async function loadWorkspace(workspaceRoot, options = {}) {
     const loaded = await loadWorkspaceObjects(workspaceRoot, options);
     loaded.agents = await discoverSubagents(loaded.agents, workspaceRoot);
@@ -84,6 +98,7 @@ export async function loadWorkspace(workspaceRoot, options = {}) {
     await ensureResourceSources(toolSourceRefs, workspaceRoot);
     await hydrateResourceAndExternalTools(tools, toolSourceRefs, workspaceRoot);
     validateWorkspaceResources(embeddings, mcpServers, models, vectorStores, tools, loaded.agents);
+    validateRoutingTargets(loaded.refs, loaded.agents);
     return {
         workspaceRoot,
         resourceSources: [...toolSourceRefs],

package/dist/workspace/object-loader.js

@@ -215,8 +215,11 @@ function readSharedAgentConfig(item) {
         ...(typeof item.systemPrompt === "string" ? { systemPrompt: item.systemPrompt } : {}),
         ...(typeof item.checkpointer === "object" && item.checkpointer ? { checkpointer: item.checkpointer } : {}),
         ...(typeof item.interruptOn === "object" && item.interruptOn ? { interruptOn: item.interruptOn } : {}),
+        ...(item.stateSchema !== undefined ? { stateSchema: item.stateSchema } : {}),
         ...(item.responseFormat !== undefined ? { responseFormat: item.responseFormat } : {}),
         ...(item.contextSchema !== undefined ? { contextSchema: item.contextSchema } : {}),
+        ...(item.includeAgentName === "inline" ? { includeAgentName: "inline" } : {}),
+        ...(item.version === "v1" || item.version === "v2" ? { version: item.version } : {}),
         ...(middleware ? { middleware } : {}),
     };
 }
@@ -228,6 +231,8 @@ function readDeepAgentConfig(item) {
         ...readSharedAgentConfig(item),
         ...(typeof item.backend === "object" && item.backend ? { backend: item.backend } : {}),
         ...(typeof item.store === "object" && item.store ? { store: item.store } : {}),
+        ...(typeof item.taskDescription === "string" && item.taskDescription.trim() ? { taskDescription: item.taskDescription } : {}),
+        ...(typeof item.generalPurposeAgent === "boolean" ? { generalPurposeAgent: item.generalPurposeAgent } : {}),
     };
 }
 export function parseAgentItem(item, sourcePath) {

package/dist/workspace/support/workspace-ref-utils.d.ts

@@ -12,8 +12,19 @@ export type RoutingRule = {
     hasThreadId?: boolean;
     caseSensitive?: boolean;
 };
+export type RuntimeRecoveryConfig = {
+    enabled: boolean;
+    resumeOnStartup: boolean;
+};
+export type RecoveryConfig = {
+    enabled: boolean;
+    resumeResumingRunsOnStartup: boolean;
+    maxRecoveryAttempts: number;
+};
 export declare function getWorkspaceObject(refs: Map<string, WorkspaceObject | ParsedAgentObject>, ref: string | undefined): WorkspaceObject | undefined;
 export declare function getRuntimeDefaults(refs: Map<string, WorkspaceObject | ParsedAgentObject>): Record<string, unknown> | undefined;
+export declare function getRuntimeRecoveryConfig(refs: Map<string, WorkspaceObject | ParsedAgentObject>): RuntimeRecoveryConfig;
+export declare function getRecoveryConfig(refs: Map<string, WorkspaceObject | ParsedAgentObject>): RecoveryConfig;
 export declare function getRoutingSystemPrompt(refs: Map<string, WorkspaceObject | ParsedAgentObject>): string | undefined;
 export declare function getRoutingDefaultAgentId(refs: Map<string, WorkspaceObject | ParsedAgentObject>): string | undefined;
 export declare function isModelRoutingEnabled(refs: Map<string, WorkspaceObject | ParsedAgentObject>): boolean;

package/dist/workspace/support/workspace-ref-utils.js

@@ -25,6 +25,32 @@ export function getRuntimeDefaults(refs) {
     }
     return runtimes[0].value;
 }
+export function getRuntimeRecoveryConfig(refs) {
+    const runtimeDefaults = getRuntimeDefaults(refs);
+    const recovery = typeof runtimeDefaults?.recovery === "object" && runtimeDefaults.recovery
+        ? runtimeDefaults.recovery
+        : undefined;
+    return {
+        enabled: recovery?.enabled !== false,
+        resumeOnStartup: recovery?.resumeOnStartup !== false,
+    };
+}
+export function getRecoveryConfig(refs) {
+    const runtimeDefaults = getRuntimeDefaults(refs);
+    const recovery = typeof runtimeDefaults?.recovery === "object" && runtimeDefaults.recovery
+        ? runtimeDefaults.recovery
+        : {};
+    const maxRecoveryAttempts = typeof recovery.maxRecoveryAttempts === "number" &&
+        Number.isFinite(recovery.maxRecoveryAttempts) &&
+        recovery.maxRecoveryAttempts > 0
+        ? Math.floor(recovery.maxRecoveryAttempts)
+        : 3;
+    return {
+        enabled: recovery.enabled !== false,
+        resumeResumingRunsOnStartup: recovery.resumeResumingRunsOnStartup !== false,
+        maxRecoveryAttempts,
+    };
+}
 export function getRoutingSystemPrompt(refs) {
     const routing = getRoutingObject(refs);
     return typeof routing?.systemPrompt === "string" && routing.systemPrompt.trim() ? routing.systemPrompt : undefined;

package/dist/workspace/validate.js

@@ -1,12 +1,4 @@
 const allowedExecutionModes = new Set(["deepagent", "langchain-v1"]);
-const allowedMiddlewareKinds = new Set([
-    "summarization",
-    "modelRetry",
-    "toolRetry",
-    "toolCallLimit",
-    "modelCallLimit",
-    "todoList",
-]);
 function hasPromptContent(value) {
     return typeof value === "string" && value.trim().length > 0;
 }
@@ -33,13 +25,16 @@ function validateMiddlewareConfig(agent) {
             throw new Error(`Agent ${agent.id} middleware entries must be objects`);
         }
         const typed = config;
-        const kind = typeof typed.kind === "string" ? typed.kind : "";
-        if (!allowedMiddlewareKinds.has(kind)) {
-            throw new Error(`Agent ${agent.id} middleware kind ${kind || "(missing)"} is not supported`);
+        const kind = typeof typed.kind === "string" ? typed.kind.trim() : "";
+        if (!kind) {
+            throw new Error(`Agent ${agent.id} middleware kind is required`);
         }
         if (kind === "summarization" && typed.model === undefined && typeof typed.modelRef !== "string") {
             throw new Error(`Agent ${agent.id} summarization middleware requires model or modelRef`);
         }
+        if (kind === "modelFallback" && !Array.isArray(typed.fallbackModels) && !Array.isArray(typed.models)) {
+            throw new Error(`Agent ${agent.id} modelFallback middleware requires fallbackModels or models`);
+        }
     }
 }
 export function validateAgent(agent) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -50,7 +50,7 @@
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && cp -R config dist/",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run test/public-api.test.ts test/resource-optional-provider.test.ts test/resource-isolation.test.ts test/stock-research-app-load-harness.test.ts test/stock-research-app-run.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts test/readme.test.ts test/runtime-adapter-regressions.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts test/skill-standard.test.ts test/routing-config.test.ts test/workspace-compat-regressions.test.ts",
+    "test": "vitest run test/public-api.test.ts test/resource-optional-provider.test.ts test/resource-isolation.test.ts test/stock-research-app-load-harness.test.ts test/stock-research-app-run.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts test/readme.test.ts test/runtime-adapter-regressions.test.ts test/runtime-recovery.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts test/skill-standard.test.ts test/routing-config.test.ts test/workspace-compat-regressions.test.ts",
     "test:real-providers": "vitest run test/real-provider-harness.test.ts",
     "release:prepare": "npm version patch --no-git-tag-version && node ./scripts/sync-example-version.mjs",
     "release:pack": "npm pack --dry-run",