@botbotgo/agent-harness 0.0.101 → 0.0.102

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

@@ -3,7 +3,7 @@ import { Command, MemorySaver } from "@langchain/langgraph";
 import { HumanMessage } from "@langchain/core/messages";
 import { DEFAULT_SUBAGENT_PROMPT, createDeepAgent, createMemoryMiddleware, createPatchToolCallsMiddleware, createSkillsMiddleware, createSummarizationMiddleware, createSubAgentMiddleware, FilesystemBackend, StateBackend, } from "deepagents";
 import { createAgent, humanInTheLoopMiddleware } from "langchain";
-import { extractToolFallbackContext, extractVisibleOutput, isToolCallParseFailure, STRICT_TOOL_JSON_INSTRUCTION, sanitizeVisibleText, wrapResolvedModel, } from "./parsing/output-parsing.js";
+import { extractToolFallbackContext, extractVisibleOutput, isToolCallParseFailure, STRICT_TOOL_JSON_INSTRUCTION, wrapResolvedModel, } from "./parsing/output-parsing.js";
 import { readStreamDelta, } from "./parsing/stream-event-parsing.js";
 import { wrapToolForExecution } from "./adapter/tool/tool-hitl.js";
 import { resolveDeclaredMiddleware } from "./adapter/tool/declared-middleware.js";
@@ -11,16 +11,14 @@ import { applyDeepAgentDelegationPromptCompatibility, materializeDeepAgentSkillS
 import { buildToolNameMapping, } from "./adapter/tool/tool-name-mapping.js";
 import { createBuiltinMiddlewareTools } from "./adapter/tool/builtin-middleware-tools.js";
 import { finalizeInvocationResult } from "./adapter/invocation-result.js";
-import { runLocalToolInvocationLoop } from "./adapter/local-tool-invocation.js";
-import { createStreamEventProjectionState, projectRuntimeStreamEvent } from "./adapter/stream-event-projection.js";
-import { projectTextStreamChunks } from "./adapter/stream-text-consumption.js";
+import { invokeRuntimeWithLocalTools } from "./adapter/invoke-runtime.js";
+import { streamRuntimeExecution } from "./adapter/stream-runtime.js";
 import { buildDeepAgentRunnableConfig } from "./adapter/deepagent-runnable-config.js";
 import { buildLangChainRunnableConfig } from "./adapter/langchain-runnable-config.js";
 import { computeRemainingTimeoutMs, isRetryableProviderError, resolveBindingTimeout, resolveProviderRetryPolicy, resolveStreamIdleTimeout, } from "./adapter/resilience.js";
 import { createResolvedModel } from "./adapter/model/model-providers.js";
 import { buildInvocationRequest, } from "./adapter/model/invocation-request.js";
 import { compileInterruptOn } from "./adapter/tool/interrupt-policy.js";
-import { buildRawModelMessages } from "./adapter/model/message-assembly.js";
 import { asStructuredExecutableTool, hasCallableToolHandler, normalizeResolvedToolSchema, wrapResolvedToolWithModelFacingName, } from "./adapter/tool/resolved-tool.js";
 import { instantiateProviderTool } from "./adapter/tool/provider-tool.js";
 import { countConfiguredTools, hasConfiguredMiddlewareKind, hasConfiguredSubagentSupport, isObject, isRecord, sleep, } from "./adapter/runtime-adapter-support.js";
@@ -512,7 +510,6 @@ export class AgentRuntimeAdapter {
         const request = resumePayload === undefined
             ? buildInvocationRequest(binding, history, input, options)
             : new Command({ resume: resumePayload });
-        let result;
         const callRuntime = async (activeBinding, activeRequest) => {
             return this.invokeWithProviderRetry(activeBinding, async () => {
                 const runnable = await this.create(activeBinding);
@@ -530,64 +527,54 @@ export class AgentRuntimeAdapter {
                 return callRuntime(this.applyStrictToolJsonInstruction(binding), activeRequest);
             }
         };
-        const executedToolResults = [];
-        if (resumePayload !== undefined) {
-            result = await callRuntimeWithToolParseRecovery(request);
-        }
-        else {
-            const primaryTools = getBindingPrimaryTools(binding);
-            const defersToUpstreamHitlExecution = primaryTools.some((tool) => tool.hitl?.enabled === true);
-            if (defersToUpstreamHitlExecution) {
-                result = await callRuntimeWithToolParseRecovery(request);
+        const primaryTools = getBindingPrimaryTools(binding);
+        const resolvedTools = this.resolveTools(primaryTools, binding);
+        const toolNameMapping = buildToolNameMapping(primaryTools);
+        const executableTools = new Map();
+        for (let index = 0; index < primaryTools.length; index += 1) {
+            const compiledTool = primaryTools[index];
+            const resolvedTool = resolvedTools[index];
+            if (!compiledTool || !resolvedTool || !hasCallableToolHandler(resolvedTool)) {
+                continue;
             }
-            else {
-                const resolvedTools = this.resolveTools(primaryTools, binding);
-                const toolNameMapping = buildToolNameMapping(primaryTools);
-                const executableTools = new Map();
-                const builtinExecutableTools = await this.resolveBuiltinMiddlewareTools(binding, options);
-                for (let index = 0; index < primaryTools.length; index += 1) {
-                    const compiledTool = primaryTools[index];
-                    const resolvedTool = resolvedTools[index];
-                    if (!compiledTool || !resolvedTool || !hasCallableToolHandler(resolvedTool)) {
-                        continue;
-                    }
-                    const handler = async (toolInput) => {
-                        const callable = typeof resolvedTool.invoke === "function"
-                            ? resolvedTool.invoke
-                            : typeof resolvedTool.call === "function"
-                                ? resolvedTool.call
-                                : resolvedTool.func;
-                        if (!callable) {
-                            throw new Error(`Tool ${compiledTool.name} has no callable handler.`);
-                        }
-                        return Promise.resolve(callable.call(resolvedTool, toolInput, options.context ? { context: options.context } : undefined));
-                    };
-                    const modelFacingName = toolNameMapping.originalToModelFacing.get(compiledTool.name) ?? compiledTool.name;
-                    const normalizedSchema = normalizeResolvedToolSchema(resolvedTool);
-                    executableTools.set(modelFacingName, {
-                        name: compiledTool.name,
-                        schema: normalizedSchema,
-                        invoke: handler,
-                    });
-                    executableTools.set(compiledTool.name, {
-                        name: compiledTool.name,
-                        schema: normalizedSchema,
-                        invoke: handler,
-                    });
+            const handler = async (toolInput) => {
+                const callable = typeof resolvedTool.invoke === "function"
+                    ? resolvedTool.invoke
+                    : typeof resolvedTool.call === "function"
+                        ? resolvedTool.call
+                        : resolvedTool.func;
+                if (!callable) {
+                    throw new Error(`Tool ${compiledTool.name} has no callable handler.`);
                 }
-                const localInvocation = await runLocalToolInvocationLoop({
-                    binding,
-                    request,
-                    primaryTools,
-                    toolNameMapping,
-                    executableTools: executableTools,
-                    builtinExecutableTools: builtinExecutableTools,
-                    callRuntimeWithToolParseRecovery,
-                });
-                result = localInvocation.result;
-                executedToolResults.push(...localInvocation.executedToolResults);
-            }
+                return Promise.resolve(callable.call(resolvedTool, toolInput, options.context ? { context: options.context } : undefined));
+            };
+            const modelFacingName = toolNameMapping.originalToModelFacing.get(compiledTool.name) ?? compiledTool.name;
+            const normalizedSchema = normalizeResolvedToolSchema(resolvedTool);
+            executableTools.set(modelFacingName, {
+                name: compiledTool.name,
+                schema: normalizedSchema,
+                invoke: handler,
+            });
+            executableTools.set(compiledTool.name, {
+                name: compiledTool.name,
+                schema: normalizedSchema,
+                invoke: handler,
+            });
         }
+        const builtinExecutableTools = await this.resolveBuiltinMiddlewareTools(binding, options);
+        const localOrUpstreamInvocation = await invokeRuntimeWithLocalTools({
+            binding,
+            request,
+            resumePayload,
+            primaryTools,
+            defersToUpstreamHitlExecution: primaryTools.some((tool) => tool.hitl?.enabled === true),
+            toolNameMapping,
+            executableTools,
+            builtinExecutableTools: builtinExecutableTools,
+            callRuntimeWithToolParseRecovery,
+        });
+        const result = localOrUpstreamInvocation.result;
+        const executedToolResults = [...localOrUpstreamInvocation.executedToolResults];
         if (!result) {
             throw new Error("Agent invocation returned no result");
         }
@@ -600,113 +587,51 @@ export class AgentRuntimeAdapter {
         });
     }
     async *stream(binding, input, threadId, history = [], options = {}) {
-        try {
-            const invokeTimeoutMs = resolveBindingTimeout(binding);
-            const streamIdleTimeoutMs = resolveStreamIdleTimeout(binding);
-            const streamDeadlineAt = invokeTimeoutMs ? Date.now() + invokeTimeoutMs : undefined;
-            const primaryTools = getBindingPrimaryTools(binding);
-            const toolNameMapping = buildToolNameMapping(primaryTools);
-            const primaryModel = getBindingPrimaryModel(binding);
-            const forceInvokeFallback = isLangChainBinding(binding) &&
-                primaryTools.length > 0 &&
-                primaryModel?.provider === "openai-compatible";
-            if (isLangChainBinding(binding)) {
-                const langchainParams = getBindingLangChainParams(binding);
-                const resolvedModel = (await this.resolveModel(langchainParams.model));
-                const tools = this.resolveTools(langchainParams.tools, binding);
-                const canUseDirectModelStream = tools.length === 0 || typeof resolvedModel.bindTools !== "function";
-                const model = canUseDirectModelStream
-                    ? resolvedModel
-                    : typeof resolvedModel.bindTools === "function" && tools.length > 0
-                        ? resolvedModel.bindTools(tools)
-                        : resolvedModel;
-                // For tool-using langchain agents, a raw model.stream pass cannot execute the
-                // agent loop and only adds an extra model round-trip before the runnable path.
-                if (canUseDirectModelStream && typeof model.stream === "function") {
-                    const stream = await this.withTimeout(() => model.stream(buildRawModelMessages(binding, getBindingSystemPrompt(binding), history, input)), computeRemainingTimeoutMs(streamDeadlineAt, invokeTimeoutMs), "model stream start", "stream");
-                    let emitted = false;
-                    const projected = projectTextStreamChunks(this.iterateWithTimeout(stream, streamIdleTimeoutMs, "model stream", streamDeadlineAt, invokeTimeoutMs));
-                    let nextChunk = await projected.next();
-                    while (!nextChunk.done) {
-                        if (nextChunk.value.kind === "content") {
-                            emitted = true;
-                        }
-                        yield nextChunk.value;
-                        nextChunk = await projected.next();
-                    }
-                    if (nextChunk.value.emittedContent || emitted) {
-                        return;
-                    }
-                }
-            }
-            const runnable = await this.create(binding);
-            const request = buildInvocationRequest(binding, history, input, options);
-            if (!forceInvokeFallback && typeof runnable.streamEvents === "function") {
-                const events = await this.withTimeout(() => runnable.streamEvents(request, { configurable: { thread_id: threadId, run_id: options.runId }, version: "v2", ...(options.context ? { context: options.context } : {}) }), computeRemainingTimeoutMs(streamDeadlineAt, invokeTimeoutMs), "agent streamEvents start", "stream");
-                const projectionState = createStreamEventProjectionState();
-                for await (const event of this.iterateWithTimeout(events, streamIdleTimeoutMs, "agent streamEvents", streamDeadlineAt, invokeTimeoutMs)) {
-                    const projectedChunks = projectRuntimeStreamEvent({
-                        event,
-                        allowVisibleStreamDeltas: isLangChainBinding(binding),
-                        includeStateStreamOutput: isDeepAgentBinding(binding),
-                        toolNameMapping,
-                        primaryTools,
-                        state: projectionState,
-                    });
-                    for (const chunk of projectedChunks) {
-                        yield chunk;
-                    }
-                }
-                if (projectionState.emittedOutput || projectionState.emittedToolResult || projectionState.emittedToolError) {
-                    return;
-                }
-            }
-            if (!forceInvokeFallback && isLangChainBinding(binding) && typeof runnable.stream === "function") {
-                const stream = await this.withTimeout(() => runnable.stream(request, { configurable: { thread_id: threadId, run_id: options.runId } }), computeRemainingTimeoutMs(streamDeadlineAt, invokeTimeoutMs), "agent stream start", "stream");
-                let emitted = false;
-                const projected = projectTextStreamChunks(this.iterateWithTimeout(stream, streamIdleTimeoutMs, "agent stream", streamDeadlineAt, invokeTimeoutMs));
-                let nextChunk = await projected.next();
-                while (!nextChunk.done) {
-                    if (nextChunk.value.kind === "content") {
-                        emitted = true;
-                    }
-                    yield nextChunk.value;
-                    nextChunk = await projected.next();
-                }
-                if (nextChunk.value.emittedContent || emitted) {
-                    return;
-                }
-            }
-            const result = await this.invoke(binding, input, threadId, options.runId ?? threadId, undefined, history, options);
-            const executedToolResults = Array.isArray(result.metadata?.executedToolResults)
-                ? result.metadata.executedToolResults
-                : [];
-            for (const toolResult of executedToolResults) {
-                yield {
-                    kind: "tool-result",
-                    toolName: toolResult.toolName,
-                    output: toolResult.output,
-                    isError: toolResult.isError,
-                };
-            }
-            if (result.output) {
-                yield { kind: "content", content: sanitizeVisibleText(result.output) };
-            }
-        }
-        catch (error) {
-            if (countConfiguredTools(binding) > 0 &&
-                error instanceof Error &&
-                error.message.includes("does not support tool binding")) {
-                throw error;
-            }
-            if (!isToolCallParseFailure(error)) {
-                throw error;
-            }
-            const retried = await this.invoke(this.applyStrictToolJsonInstruction(binding), input, threadId, options.runId ?? threadId, undefined, history, options);
-            if (retried.output) {
-                yield { kind: "content", content: sanitizeVisibleText(retried.output) };
-            }
-        }
+        const invokeTimeoutMs = resolveBindingTimeout(binding);
+        const streamIdleTimeoutMs = resolveStreamIdleTimeout(binding);
+        const streamDeadlineAt = invokeTimeoutMs ? Date.now() + invokeTimeoutMs : undefined;
+        const primaryTools = getBindingPrimaryTools(binding);
+        const toolNameMapping = buildToolNameMapping(primaryTools);
+        const primaryModel = getBindingPrimaryModel(binding);
+        const forceInvokeFallback = isLangChainBinding(binding) &&
+            primaryTools.length > 0 &&
+            primaryModel?.provider === "openai-compatible";
+        const langchainParams = isLangChainBinding(binding) ? getBindingLangChainParams(binding) : undefined;
+        const resolvedLangChainModel = langchainParams
+            ? (await this.resolveModel(langchainParams.model))
+            : undefined;
+        const resolvedLangChainTools = langchainParams ? this.resolveTools(langchainParams.tools, binding) : [];
+        const canUseDirectModelStream = !!resolvedLangChainModel &&
+            (resolvedLangChainTools.length === 0 || typeof resolvedLangChainModel.bindTools !== "function");
+        const langChainStreamModel = resolvedLangChainModel && canUseDirectModelStream
+            ? resolvedLangChainModel
+            : resolvedLangChainModel && typeof resolvedLangChainModel.bindTools === "function" && resolvedLangChainTools.length > 0
+                ? resolvedLangChainModel.bindTools(resolvedLangChainTools)
+                : undefined;
+        yield* streamRuntimeExecution({
+            binding,
+            input,
+            threadId,
+            history,
+            runtimeOptions: options,
+            primaryTools,
+            toolNameMapping,
+            forceInvokeFallback,
+            canUseDirectModelStream,
+            langChainStreamModel,
+            createRunnable: () => this.create(binding),
+            withTimeout: (producer, timeoutMs, operation, stage) => this.withTimeout(producer, timeoutMs, operation, stage),
+            iterateWithTimeout: (iterable, timeoutMs, operation, deadlineAt, deadlineTimeoutMs) => this.iterateWithTimeout(iterable, timeoutMs, operation, deadlineAt, deadlineTimeoutMs),
+            invokeTimeoutMs: computeRemainingTimeoutMs(streamDeadlineAt, invokeTimeoutMs),
+            streamIdleTimeoutMs,
+            streamDeadlineAt,
+            invoke: (activeBinding, activeInput, activeThreadId, runId, resumePayload, activeHistory, invokeOptions) => this.invoke(activeBinding, activeInput, activeThreadId, runId, resumePayload, activeHistory, invokeOptions),
+            applyStrictToolJsonInstruction: (activeBinding) => this.applyStrictToolJsonInstruction(activeBinding),
+            getSystemPrompt: (activeBinding) => getBindingSystemPrompt(activeBinding),
+            isLangChainBinding,
+            isDeepAgentBinding,
+            countConfiguredTools,
+        });
     }
 }
 export { AgentRuntimeAdapter as RuntimeAdapter, AGENT_INTERRUPT_SENTINEL_PREFIX, AGENT_INTERRUPT_SENTINEL_PREFIX as INTERRUPT_SENTINEL_PREFIX, RuntimeOperationTimeoutError, };

package/dist/runtime/harness/run/run-operations.d.ts

@@ -0,0 +1,50 @@
+import type { CancelOptions, CompiledAgentBinding, InternalApprovalRecord, MessageContent, ResumeOptions, RunResult, ThreadSummary, TranscriptMessage } from "../../../contracts/types.js";
+import type { RecoveryIntent } from "../../../persistence/types.js";
+type ResumeOperationRuntime = {
+    getApprovalById: (approvalId: string) => Promise<InternalApprovalRecord | null>;
+    getSession: (threadId: string) => Promise<ThreadSummary | null>;
+    resolveApprovalRecord: (options: ResumeOptions, thread: ThreadSummary) => Promise<InternalApprovalRecord>;
+    getBinding: (agentId: string) => CompiledAgentBinding | undefined;
+    buildResumePayload: (binding: CompiledAgentBinding, approval: InternalApprovalRecord, options: ResumeOptions) => unknown;
+    getRunCancellation: (runId: string) => Promise<{
+        requested: boolean;
+        reason?: string;
+    }>;
+    finalizeCancelledRun: (threadId: string, runId: string, previousState: RunResult["state"] | null, reason?: string) => Promise<RunResult>;
+    setRunState: (threadId: string, runId: string, state: RunResult["state"], checkpointRef: string | null) => Promise<void>;
+    acquireRunSlot: (threadId?: string, runId?: string, activeState?: RunResult["state"], priority?: number) => Promise<() => Promise<void>>;
+    resolvePersistedRunPriority: (threadId: string, runId: string) => Promise<number>;
+    saveRecoveryIntent: (threadId: string, runId: string, payload: RecoveryIntent) => Promise<unknown>;
+    emit: (threadId: string, runId: string, sequence: number, eventType: string, payload: Record<string, unknown>) => Promise<unknown>;
+    resolveApproval: (threadId: string, runId: string, approvalId: string, resolution: "approved" | "edited" | "rejected" | "expired") => Promise<unknown>;
+    listThreadMessages: (threadId: string) => Promise<TranscriptMessage[]>;
+    loadRunInput: (threadId: string, runId: string) => Promise<MessageContent>;
+    invoke: (binding: CompiledAgentBinding, input: MessageContent, threadId: string, runId: string, resumePayload: unknown, priorHistory: TranscriptMessage[]) => Promise<RunResult>;
+    recordLlmSuccess: (startedAt: number) => void;
+    recordLlmFailure: (startedAt: number) => void;
+    clearRecoveryIntent: (threadId: string, runId: string) => Promise<void>;
+    finalizeContinuedRun: (binding: CompiledAgentBinding, threadId: string, runId: string, input: MessageContent, actual: RunResult, options: {
+        previousState: RunResult["state"] | null;
+        stateSequence: number;
+        approvalSequence?: number;
+    }) => Promise<RunResult>;
+};
+type CancelOperationRuntime = {
+    getRun: (runId: string) => Promise<{
+        threadId: string;
+        runId: string;
+        agentId: string;
+        state: RunResult["state"];
+    } | null>;
+    requestRunCancel: (runId: string, reason?: string) => Promise<unknown>;
+    dropPendingRunSlot: (runId: string) => boolean;
+    finalizeCancelledRun: (threadId: string, runId: string, previousState: RunResult["state"] | null, reason?: string) => Promise<RunResult>;
+    setRunStateAndEmit: (threadId: string, runId: string, sequence: number, state: RunResult["state"], options: {
+        previousState: string | null;
+        checkpointRef?: string | null;
+        error?: string;
+    }) => Promise<unknown>;
+};
+export declare function resumeRun(runtime: ResumeOperationRuntime, options: ResumeOptions): Promise<RunResult>;
+export declare function cancelRunOperation(runtime: CancelOperationRuntime, options: CancelOptions): Promise<RunResult>;
+export {};

package/dist/runtime/harness/run/run-operations.js

@@ -0,0 +1,113 @@
+import { isTerminalRunState } from "./helpers.js";
+export async function resumeRun(runtime, options) {
+    const approvalById = options.approvalId ? await runtime.getApprovalById(options.approvalId) : null;
+    const thread = options.threadId
+        ? await runtime.getSession(options.threadId)
+        : approvalById
+            ? await runtime.getSession(approvalById.threadId)
+            : null;
+    if (!thread) {
+        throw new Error("resume requires either threadId or approvalId");
+    }
+    const approval = approvalById ?? await runtime.resolveApprovalRecord(options, thread);
+    const threadId = approval.threadId;
+    const runId = approval.runId;
+    const binding = runtime.getBinding(thread.agentId);
+    if (!binding) {
+        throw new Error(`Unknown agent ${thread.agentId}`);
+    }
+    const resumePayload = runtime.buildResumePayload(binding, approval, options);
+    const cancellation = await runtime.getRunCancellation(runId);
+    if (cancellation.requested) {
+        return runtime.finalizeCancelledRun(threadId, runId, thread.status, cancellation.reason);
+    }
+    const checkpointRef = `checkpoints/${threadId}/${runId}/cp-1`;
+    await runtime.setRunState(threadId, runId, "resuming", checkpointRef);
+    const releaseRunSlot = await runtime.acquireRunSlot(threadId, runId, "resuming", await runtime.resolvePersistedRunPriority(threadId, runId));
+    try {
+        await runtime.saveRecoveryIntent(threadId, runId, {
+            kind: "approval-decision",
+            savedAt: new Date().toISOString(),
+            checkpointRef,
+            resumePayload,
+            attempts: 0,
+        });
+        await runtime.emit(threadId, runId, 5, "run.resumed", {
+            resumeKind: "cross-restart",
+            checkpointRef,
+            state: "resuming",
+            approvalId: approval.approvalId,
+            pendingActionId: approval.pendingActionId,
+        });
+        await runtime.resolveApproval(threadId, runId, approval.approvalId, options.decision === "reject" ? "rejected" : options.decision === "edit" ? "edited" : "approved");
+        await runtime.emit(threadId, runId, 6, "approval.resolved", {
+            approvalId: approval.approvalId,
+            pendingActionId: approval.pendingActionId,
+            decision: options.decision ?? "approve",
+            toolName: approval.toolName,
+        });
+        const history = await runtime.listThreadMessages(threadId);
+        const priorHistory = history.filter((message) => message.runId !== runId);
+        const runInput = await runtime.loadRunInput(threadId, runId);
+        const startedAt = Date.now();
+        try {
+            const actual = await runtime.invoke(binding, "", threadId, runId, resumePayload, priorHistory);
+            runtime.recordLlmSuccess(startedAt);
+            const cancelledAfterInvoke = await runtime.getRunCancellation(runId);
+            if (cancelledAfterInvoke.requested) {
+                return runtime.finalizeCancelledRun(threadId, runId, "resuming", cancelledAfterInvoke.reason);
+            }
+            await runtime.clearRecoveryIntent(threadId, runId);
+            const finalized = await runtime.finalizeContinuedRun(binding, threadId, runId, runInput, actual, {
+                previousState: "resuming",
+                stateSequence: 7,
+                approvalSequence: 8,
+            });
+            return {
+                ...finalized,
+                approvalId: finalized.approvalId ?? approval.approvalId,
+                pendingActionId: finalized.pendingActionId ?? approval.pendingActionId,
+            };
+        }
+        catch (error) {
+            runtime.recordLlmFailure(startedAt);
+            throw error;
+        }
+    }
+    finally {
+        await releaseRunSlot();
+    }
+}
+export async function cancelRunOperation(runtime, options) {
+    const run = await runtime.getRun(options.runId);
+    if (!run) {
+        throw new Error(`Unknown run ${options.runId}`);
+    }
+    if (isTerminalRunState(run.state)) {
+        return {
+            threadId: run.threadId,
+            runId: run.runId,
+            agentId: run.agentId,
+            state: run.state,
+            output: run.state,
+        };
+    }
+    await runtime.requestRunCancel(run.runId, options.reason);
+    if (run.state === "queued" || run.state === "waiting_for_approval" || run.state === "claimed") {
+        if (run.state === "queued") {
+            runtime.dropPendingRunSlot(run.runId);
+        }
+        return runtime.finalizeCancelledRun(run.threadId, run.runId, run.state, options.reason);
+    }
+    await runtime.setRunStateAndEmit(run.threadId, run.runId, 103, "cancelling", {
+        previousState: run.state,
+        ...(options.reason ? { error: options.reason } : {}),
+    });
+    return {
+        threadId: run.threadId,
+        runId: run.runId,
+        agentId: run.agentId,
+        state: "cancelling",
+        output: options.reason ? `cancelling: ${options.reason}` : "cancelling",
+    };
+}

package/dist/runtime/harness/run/run-slot-acquisition.d.ts

@@ -0,0 +1,64 @@
+import type { RunResult } from "../../../contracts/types.js";
+import { type PendingRunSlot } from "./run-queue.js";
+export type RunSlotConcurrencyConfig = {
+    maxConcurrentRuns?: number;
+    leaseMs: number;
+    heartbeatIntervalMs: number;
+};
+type RunClaimPersistence = {
+    claimQueuedRun(payload: {
+        threadId: string;
+        runId: string;
+        workerId: string;
+        claimedAt: string;
+        leaseExpiresAt: string;
+    }): Promise<unknown>;
+    renewRunLease(payload: {
+        runId: string;
+        workerId: string;
+        heartbeatAt: string;
+        leaseExpiresAt: string;
+    }): Promise<unknown>;
+    releaseRunClaim(runId: string): Promise<unknown>;
+    enqueueRun(payload: {
+        threadId: string;
+        runId: string;
+        priority: number;
+    }): Promise<unknown>;
+    getRun(runId: string): Promise<{
+        state: RunResult["state"];
+    } | null>;
+};
+type RunSlotRuntime = {
+    persistence: RunClaimPersistence;
+    workerId: string;
+    concurrencyConfig: RunSlotConcurrencyConfig;
+    pendingRunSlots: PendingRunSlot[];
+    getActiveRunSlots: () => number;
+    setActiveRunSlots: (count: number) => void;
+    enqueuePendingRunSlot: (entry: {
+        threadId?: string;
+        runId?: string;
+        priority: number;
+        activate: () => void | Promise<void>;
+        abort: () => void;
+    }) => Array<{
+        threadId: string;
+        runId: string;
+        priority: number;
+        queuePosition: number;
+    }>;
+    emit: (threadId: string, runId: string, sequence: number, eventType: string, payload: Record<string, unknown>) => Promise<unknown>;
+    setRunStateAndEmit: (threadId: string, runId: string, sequence: number, state: RunResult["state"], options: {
+        previousState: string | null;
+        checkpointRef?: string | null;
+        error?: string;
+    }) => Promise<unknown>;
+};
+export declare function acquireRunSlot(runtime: RunSlotRuntime, options?: {
+    threadId?: string;
+    runId?: string;
+    activeState?: RunResult["state"];
+    priority?: number;
+}): Promise<() => Promise<void>>;
+export {};