intentdna 1.8.6 → 1.8.7

package/dist/runtime/handoff-resolver.js

@@ -0,0 +1,167 @@
+export class HandoffResolutionError extends Error {
+    code;
+    binding_id;
+    result_id;
+    constructor(code, message, bindingId, resultId, options) {
+        super(message, options);
+        this.name = "HandoffResolutionError";
+        this.code = code;
+        this.binding_id = bindingId;
+        this.result_id = resultId;
+    }
+}
+function noHandoff(request, reason) {
+    return {
+        binding_id: request.binding_id,
+        input_name: request.input_name,
+        required: false,
+        description: request.description,
+        mode: "none",
+        reason,
+    };
+}
+function requireRequestIdentity(request) {
+    const sourceIsInvalid = request.mode !== "none" &&
+        (!request.source.result_id ||
+            !request.source.step_id ||
+            !request.source.output_name);
+    if (!request.binding_id || !request.input_name || sourceIsInvalid) {
+        throw new HandoffResolutionError("invalid_request", "binding_id, input_name, and any declared source identities must be non-empty", request.binding_id, request.mode === "none" ? null : request.source.result_id);
+    }
+}
+function findOutput(outputs, source) {
+    return outputs.find((output) => output.name === source.output_name) ?? null;
+}
+/**
+ * Resolves only declared values from immutable committed results. It has no
+ * provider-session, transcript, Hook-state, filesystem, or summarization input.
+ */
+export class HandoffResolver {
+    results;
+    structuredValidator;
+    constructor(results, options = {}) {
+        this.results = results;
+        this.structuredValidator = options.validate_structured_value;
+    }
+    async resolve(runId, request) {
+        requireRequestIdentity(request);
+        if (request.mode === "none") {
+            return noHandoff(request, request.reason);
+        }
+        const result = await this.results.read(runId, request.source.result_id);
+        if (!result) {
+            if (!request.required) {
+                return noHandoff(request, "optional upstream result is not committed");
+            }
+            throw new HandoffResolutionError("required_input_uncommitted", `required input ${request.input_name} needs committed result ${request.source.result_id}`, request.binding_id, request.source.result_id);
+        }
+        if (result.step_id !== request.source.step_id) {
+            throw new HandoffResolutionError("source_identity_mismatch", `result ${result.result_id} belongs to step ${result.step_id}, not ${request.source.step_id}`, request.binding_id, request.source.result_id);
+        }
+        const output = findOutput(result.outputs, request.source);
+        if (!output) {
+            if (!request.required) {
+                return noHandoff(request, "optional upstream output is absent");
+            }
+            throw new HandoffResolutionError("source_output_missing", `required output ${request.source.output_name} is absent from result ${result.result_id}`, request.binding_id, request.source.result_id);
+        }
+        if (request.mode === "reference") {
+            if (output.kind !== "reference") {
+                throw this.kindMismatch(request, output);
+            }
+            return {
+                binding_id: request.binding_id,
+                input_name: request.input_name,
+                required: request.required,
+                description: request.description,
+                mode: "reference",
+                source: request.source,
+                reference: output.reference,
+            };
+        }
+        if (request.mode === "quote") {
+            if (output.kind !== "text") {
+                throw this.kindMismatch(request, output);
+            }
+            const selection = request.selection;
+            if (selection === null) {
+                return {
+                    binding_id: request.binding_id,
+                    input_name: request.input_name,
+                    required: request.required,
+                    description: request.description,
+                    mode: "quote",
+                    source: request.source,
+                    exact_text: output.text,
+                    selection: { start: null, end: null, selector: null },
+                };
+            }
+            if (!Number.isSafeInteger(selection.start) ||
+                !Number.isSafeInteger(selection.end) ||
+                selection.start < 0 ||
+                selection.end < selection.start ||
+                selection.end > output.text.length) {
+                throw new HandoffResolutionError("invalid_quote_selection", `quote range ${selection.start}:${selection.end} is invalid for output length ${output.text.length}`, request.binding_id, request.source.result_id);
+            }
+            return {
+                binding_id: request.binding_id,
+                input_name: request.input_name,
+                required: request.required,
+                description: request.description,
+                mode: "quote",
+                source: request.source,
+                exact_text: output.text.slice(selection.start, selection.end),
+                selection,
+            };
+        }
+        if (output.kind !== "structured") {
+            throw this.kindMismatch(request, output);
+        }
+        if (request.schema_ref !== null &&
+            output.schema_ref !== request.schema_ref) {
+            throw new HandoffResolutionError("structured_schema_mismatch", `output schema ${String(output.schema_ref)} does not match input schema ${request.schema_ref}`, request.binding_id, request.source.result_id);
+        }
+        const schemaRef = request.schema_ref ?? output.schema_ref;
+        if (schemaRef !== null) {
+            if (!this.structuredValidator) {
+                throw new HandoffResolutionError("structured_schema_validator_missing", `structured handoff ${request.binding_id} requires validator ${schemaRef}`, request.binding_id, request.source.result_id);
+            }
+            try {
+                await this.structuredValidator(schemaRef, output.value);
+            }
+            catch (error) {
+                throw new HandoffResolutionError("structured_value_invalid", `structured output ${request.source.output_name} failed schema ${schemaRef}`, request.binding_id, request.source.result_id, { cause: error });
+            }
+        }
+        return {
+            binding_id: request.binding_id,
+            input_name: request.input_name,
+            required: request.required,
+            description: request.description,
+            mode: "structured",
+            source: request.source,
+            value: output.value,
+            schema_ref: schemaRef,
+        };
+    }
+    async resolveAll(runId, requests) {
+        const bindingIds = new Set();
+        const inputNames = new Set();
+        for (const request of requests) {
+            if (bindingIds.has(request.binding_id) ||
+                inputNames.has(request.input_name)) {
+                throw new HandoffResolutionError("duplicate_binding", `duplicate binding_id or input_name for ${request.binding_id}`, request.binding_id, request.mode === "none" ? null : request.source.result_id);
+            }
+            bindingIds.add(request.binding_id);
+            inputNames.add(request.input_name);
+        }
+        const bindings = [];
+        for (const request of requests) {
+            bindings.push(await this.resolve(runId, request));
+        }
+        return bindings;
+    }
+    kindMismatch(request, output) {
+        return new HandoffResolutionError("source_output_kind_mismatch", `handoff ${request.binding_id} requested ${request.mode}, but output ${output.name} is ${output.kind}`, request.binding_id, request.source.result_id);
+    }
+}

package/dist/runtime/index.d.ts

@@ -15,3 +15,27 @@ export { createClaudeCoreSyncTargetPlan, executeClaudeCoreSyncTargetPlan, format
 export type { ClaudeCoreAdapterCapabilityReport, ClaudeCoreCapabilityReportEntry, ClaudeCorePlannedArtifact, ClaudeCoreSyncTargetPlan, ClaudeCoreSyncTargetPlanOptions, ClaudeSettingsHookRegistration, ClaudeSyncMode, ExecuteClaudeCoreSyncTargetPlanResult, } from "./claude-sync-target.js";
 export type { AdapterCapabilityReport, CapabilityReportEntry, CapabilitySupportStatus, EvidenceClassification, EvidencePlan, PlannedArtifact, SyncTarget, SyncTargetMode, SyncTargetPlan, } from "./sync-target-plan.js";
 export { formatSyncTargetPlanDiagnostics, trackedOutputsForSyncTargetPlan, } from "./sync-target-plan.js";
+export { TASK_STATE_VALUES, TASK_STATE_TRANSITIONS, RETRY_BACKOFF_VALUES as RUNTIME_RETRY_BACKOFF_VALUES, TERMINAL_OUTCOME_KIND_VALUES, RUNTIME_EVENT_TYPE_VALUES, } from "./run-contracts.js";
+export type { RuntimeId, RunId, StepId, AttemptId, WorkerSessionId, ResultId, EventId, ClaimToken, JsonValue, TaskKey, AttemptIdentity, TaskState, TerminalTaskState, TaskRecord, TaskLease, TaskClaim, RetryBackoff as RuntimeRetryBackoff, RetryPolicy as RuntimeRetryPolicy, RetryDecision, AttemptPhase, AttemptRecord, HandoffSource, ReferenceHandoffBinding, QuoteHandoffBinding, StructuredHandoffBinding, NoHandoffBinding, HandoffBinding, StepOutputKind, DeclaredStepOutput, StepOutput, StepPacket, TerminalOutcomeKind, TerminalOutcome, ProviderEvent, ProviderExecutionResult, CommittedStepResult, RuntimeEventType, RuntimeEvent, } from "./run-contracts.js";
+export { RUN_STORE_SCHEMA_VERSION, RUN_STATUS_VALUES, RunStoreError, DurableRunStore, } from "./run-store.js";
+export type { RunStatus, TerminalRunStatus, RunCancellationIntent, RunTerminalRecord, RunRecord, StoredTaskClaim, RunStoreSnapshot, CreateRunStoreRecord, RunStoreUpdate, RunStoreUpdateResult, DurableRunStoreOptions, RunStoreErrorCode, } from "./run-store.js";
+export { ResultStoreError, ImmutableResultStore, } from "./result-store.js";
+export type { ResultStoreErrorCode, CommitStepResultRequest, CommitStepResultResponse, } from "./result-store.js";
+export { HandoffResolutionError, HandoffResolver, } from "./handoff-resolver.js";
+export type { ReferenceHandoffRequest, QuoteHandoffRequest, StructuredHandoffRequest, NoHandoffRequest, HandoffRequest, StructuredValueValidator, HandoffResolverOptions, HandoffResolutionErrorCode, } from "./handoff-resolver.js";
+export { MalformedProviderResultError, decodeDeclaredOutputs, } from "./execution-provider.js";
+export type { ProviderLaunchSpec, ProviderParseContext, ParsedProviderResult, ExecutionProvider, WorkerExecution, } from "./execution-provider.js";
+export { createClaudeExecutionProvider } from "./providers/claude.js";
+export type { ClaudeExecutionProviderOptions, } from "./providers/claude.js";
+export { createCodexExecutionProvider } from "./providers/codex.js";
+export type { CodexExecutionProviderOptions, } from "./providers/codex.js";
+export { runProcessTree, runProcessTreeWithTimeout, } from "./process-tree.js";
+export type { ProcessTerminationReason, ProcessTreeRunOptions, ProcessTreeRunResult, } from "./process-tree.js";
+export { executeWorkerAttempt } from "./worker-executor.js";
+export type { WorkerExecutorOptions, WorkerExecutionWithEvents, } from "./worker-executor.js";
+export { RunControllerError, RunController, } from "./run-controller.js";
+export type { ControllerReferenceHandoff, ControllerQuoteHandoff, ControllerStructuredHandoff, ControllerNoHandoff, ControllerHandoffDeclaration, MaterializeStepPacketInput, ControllerStepDefinition, ReconciledAttemptState, AttemptReconciler, RunControllerOptions, CreateControllerRunInput, ClaimedStep, RunControllerErrorCode, } from "./run-controller.js";
+export { WorkflowPlanAdapterError, adaptWorkflowPlan, } from "./workflow-plan-adapter.js";
+export type { WorkflowPlanAdapterErrorCode, WorkflowPlanAdapterOptions, } from "./workflow-plan-adapter.js";
+export { WorkspaceIsolationError, planAttemptWorkspace, allocateAttemptWorkspace, inspectAttemptWorkspace, applyWorkspaceLifecycleDecision, defaultWorktreeRoot, describeWorkspace, } from "./workspace-isolation.js";
+export type { WorkspaceIsolation, WorkspaceIsolationErrorCode, AttemptWorkspaceRequest, SharedWorkspacePlan, IsolatedWorkspacePlan, AttemptWorkspacePlan, SharedWorkspaceAllocation, IsolatedWorkspaceAllocation, AttemptWorkspaceAllocation, WorkspaceInspection, WorkspacePreservationReason, WorkspaceLifecycleDecision, WorkspaceLifecycleResult, } from "./workspace-isolation.js";

package/dist/runtime/index.js

@@ -7,3 +7,16 @@ export { CODEX_ADAPTER_MINIMUM_VERSION, CODEX_NATIVE_HOOK_EVENTS, appendCodexRun
 export { codexSyncDispatcherCommand, createCodexSyncTargetPlan, executeCodexSyncTargetPlan, formatCodexSyncTargetPlanSummary, removeCodexSyncTargetArtifacts, } from "./codex-sync-target.js";
 export { createClaudeCoreSyncTargetPlan, executeClaudeCoreSyncTargetPlan, formatClaudeCoreSyncTargetPlanDryRun, removeLegacyBashHooks, } from "./claude-sync-target.js";
 export { formatSyncTargetPlanDiagnostics, trackedOutputsForSyncTargetPlan, } from "./sync-target-plan.js";
+// Foundation Runtime canonical execution surface.
+export { TASK_STATE_VALUES, TASK_STATE_TRANSITIONS, RETRY_BACKOFF_VALUES as RUNTIME_RETRY_BACKOFF_VALUES, TERMINAL_OUTCOME_KIND_VALUES, RUNTIME_EVENT_TYPE_VALUES, } from "./run-contracts.js";
+export { RUN_STORE_SCHEMA_VERSION, RUN_STATUS_VALUES, RunStoreError, DurableRunStore, } from "./run-store.js";
+export { ResultStoreError, ImmutableResultStore, } from "./result-store.js";
+export { HandoffResolutionError, HandoffResolver, } from "./handoff-resolver.js";
+export { MalformedProviderResultError, decodeDeclaredOutputs, } from "./execution-provider.js";
+export { createClaudeExecutionProvider } from "./providers/claude.js";
+export { createCodexExecutionProvider } from "./providers/codex.js";
+export { runProcessTree, runProcessTreeWithTimeout, } from "./process-tree.js";
+export { executeWorkerAttempt } from "./worker-executor.js";
+export { RunControllerError, RunController, } from "./run-controller.js";
+export { WorkflowPlanAdapterError, adaptWorkflowPlan, } from "./workflow-plan-adapter.js";
+export { WorkspaceIsolationError, planAttemptWorkspace, allocateAttemptWorkspace, inspectAttemptWorkspace, applyWorkspaceLifecycleDecision, defaultWorktreeRoot, describeWorkspace, } from "./workspace-isolation.js";

package/dist/runtime/process-tree.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Bounded adaptation of oh-my-codex v0.20.3 process-tree behavior.
+ *
+ * The local delta adds external cancellation, distinct termination reasons,
+ * explicit cancellation grace, stdin, and observation callbacks. Process-group
+ * ownership, timeout escalation, parent-exit cleanup, output/process limits, and
+ * residual descendant cleanup remain centralized here.
+ */
+import { spawn } from "node:child_process";
+export type ProcessTerminationReason = "timeout" | "cancellation" | "process_limit" | "output_limit";
+export interface ProcessTreeRunOptions {
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly stdin?: string;
+    readonly encoding?: BufferEncoding;
+    readonly timeoutMs?: number;
+    readonly cancellationSignal?: AbortSignal;
+    readonly cancellationReason?: string | null;
+    readonly killSignal?: NodeJS.Signals;
+    readonly sigkillGraceMs?: number;
+    readonly cancellationGraceMs?: number;
+    readonly maxOutputBytes?: number;
+    readonly maxProcessCount?: number;
+    readonly processLimitPollMs?: number;
+    readonly cleanupOnParentExit?: boolean;
+    readonly platform?: NodeJS.Platform;
+    readonly spawnImpl?: typeof spawn;
+    readonly onProcessStart?: (processId: number) => void;
+    readonly onStdout?: (text: string) => void;
+    readonly onStderr?: (text: string) => void;
+    readonly onTerminationRequested?: (reason: ProcessTerminationReason) => void;
+}
+export interface ProcessTreeRunResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly status: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly timedOut: boolean;
+    readonly cancelled: boolean;
+    readonly cancellationReason: string | null;
+    readonly processLimitExceeded: boolean;
+    readonly outputLimitExceeded: boolean;
+    readonly terminationReason: ProcessTerminationReason | null;
+    readonly error?: NodeJS.ErrnoException;
+}
+export declare function runProcessTree(command: string, args: readonly string[], options?: ProcessTreeRunOptions): Promise<ProcessTreeRunResult>;
+export declare const runProcessTreeWithTimeout: typeof runProcessTree;

package/dist/runtime/process-tree.js

@@ -0,0 +1,402 @@
+/**
+ * Bounded adaptation of oh-my-codex v0.20.3 process-tree behavior.
+ *
+ * The local delta adds external cancellation, distinct termination reasons,
+ * explicit cancellation grace, stdin, and observation callbacks. Process-group
+ * ownership, timeout escalation, parent-exit cleanup, output/process limits, and
+ * residual descendant cleanup remain centralized here.
+ */
+import { spawn, spawnSync, } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, delimiter, extname, join, } from "node:path";
+const DEFAULT_TERMINATION_GRACE_MS = 1_000;
+const DEFAULT_PROCESS_LIMIT_POLL_MS = 100;
+const WINDOWS_DIRECT_EXTENSIONS = new Set([".com", ".exe"]);
+const WINDOWS_CMD_EXTENSIONS = new Set([".bat", ".cmd"]);
+const WINDOWS_DEFAULT_PATHEXT = [".exe", ".com", ".cmd", ".bat", ".ps1"];
+function positiveInteger(value) {
+    if (value === undefined || !Number.isFinite(value) || value <= 0)
+        return undefined;
+    return Math.floor(value);
+}
+function cancellationReason(signal, configured) {
+    if (configured !== undefined && configured !== null)
+        return configured;
+    const reason = signal?.reason;
+    if (typeof reason === "string")
+        return reason;
+    if (reason instanceof Error)
+        return reason.message;
+    return reason === undefined || reason === null ? null : String(reason);
+}
+function nonNegativeInteger(value) {
+    if (value === undefined || !Number.isFinite(value) || value < 0)
+        return undefined;
+    return Math.floor(value);
+}
+function fileExists(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function resolveWindowsCommand(command, env) {
+    const hasPath = /^[A-Za-z]:/.test(command) || /[\\/]/.test(command);
+    const rawExtensions = String(env.PATHEXT ?? "").trim();
+    const extensions = rawExtensions === ""
+        ? WINDOWS_DEFAULT_PATHEXT
+        : [...new Set([
+                ...WINDOWS_DEFAULT_PATHEXT,
+                ...rawExtensions.split(";").map((value) => value.trim().toLowerCase()).filter(Boolean),
+            ])];
+    const directories = hasPath
+        ? [""]
+        : String(env.Path ?? env.PATH ?? "").split(delimiter).filter(Boolean);
+    const extension = extname(command);
+    for (const directory of directories) {
+        const base = directory === "" ? command : join(directory, command);
+        const candidates = extension ? [base] : [...extensions.map((item) => `${base}${item}`), base];
+        for (const candidate of candidates) {
+            if (fileExists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+function commandSpec(command, args, platform, env) {
+    if (platform !== "win32")
+        return { command, args: [...args] };
+    const resolved = resolveWindowsCommand(command, env);
+    if (!resolved)
+        return { command, args: [...args] };
+    const extension = extname(resolved).toLowerCase();
+    if (WINDOWS_CMD_EXTENSIONS.has(extension)) {
+        const quote = (value) => `"${value.replace(/"/g, "\"\"")}"`;
+        const commandLine = [resolved, ...args].map(quote).join(" ");
+        return {
+            command: env.ComSpec || "cmd.exe",
+            args: ["/d", "/s", "/c", `"${commandLine}"`],
+            windowsVerbatimArguments: true,
+        };
+    }
+    if (extension === ".ps1") {
+        return {
+            command: "powershell.exe",
+            args: [
+                "-NoLogo",
+                "-NoProfile",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                resolved,
+                ...args,
+            ],
+        };
+    }
+    if (WINDOWS_DIRECT_EXTENSIONS.has(extension) || basename(resolved) !== "") {
+        return { command: resolved, args: [...args] };
+    }
+    return { command, args: [...args] };
+}
+function terminateProcessTree(child, platform, signal) {
+    if (child.pid === undefined)
+        return;
+    if (platform === "win32") {
+        const force = signal === "SIGKILL" ? ["/F"] : [];
+        const result = spawnSync("taskkill", ["/PID", String(child.pid), "/T", ...force], { windowsHide: true, stdio: "ignore" });
+        if (!result.error && result.status === 0)
+            return;
+    }
+    try {
+        if (platform === "win32") {
+            child.kill(signal);
+        }
+        else {
+            process.kill(-child.pid, signal);
+        }
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ESRCH")
+            return;
+        try {
+            child.kill(signal);
+        }
+        catch (fallbackError) {
+            if (fallbackError.code !== "ESRCH") {
+                throw fallbackError;
+            }
+        }
+    }
+}
+function readLinuxProcessTable() {
+    try {
+        const table = new Map();
+        for (const entry of readdirSync("/proc", { withFileTypes: true })) {
+            if (!entry.isDirectory() || !/^\d+$/.test(entry.name))
+                continue;
+            let stat;
+            try {
+                stat = readFileSync(`/proc/${entry.name}/stat`, "utf-8");
+            }
+            catch {
+                continue;
+            }
+            const closeParen = stat.lastIndexOf(")");
+            if (closeParen < 0)
+                continue;
+            const fields = stat.slice(closeParen + 2).split(" ");
+            const pid = Number.parseInt(entry.name, 10);
+            const parentPid = Number.parseInt(fields[1] ?? "", 10);
+            if (Number.isFinite(parentPid))
+                table.set(pid, parentPid);
+        }
+        return table;
+    }
+    catch {
+        return undefined;
+    }
+}
+function countLinuxDescendants(rootPid) {
+    const table = readLinuxProcessTable();
+    if (!table)
+        return undefined;
+    const children = new Map();
+    for (const [pid, parentPid] of table) {
+        const values = children.get(parentPid) ?? [];
+        values.push(pid);
+        children.set(parentPid, values);
+    }
+    let count = 0;
+    const pending = [...(children.get(rootPid) ?? [])];
+    while (pending.length > 0) {
+        const pid = pending.pop();
+        if (pid === undefined)
+            continue;
+        count += 1;
+        pending.push(...(children.get(pid) ?? []));
+    }
+    return count;
+}
+export function runProcessTree(command, args, options = {}) {
+    const cancellationSignal = options.cancellationSignal;
+    if (cancellationSignal?.aborted) {
+        options.onTerminationRequested?.("cancellation");
+        return Promise.resolve({
+            stdout: "",
+            stderr: "",
+            status: null,
+            signal: null,
+            timedOut: false,
+            cancelled: true,
+            cancellationReason: cancellationReason(cancellationSignal, options.cancellationReason),
+            processLimitExceeded: false,
+            outputLimitExceeded: false,
+            terminationReason: "cancellation",
+        });
+    }
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const spec = commandSpec(command, args, platform, env);
+    const spawnImpl = options.spawnImpl ?? spawn;
+    const timeoutMs = positiveInteger(options.timeoutMs);
+    const killSignal = options.killSignal ?? "SIGTERM";
+    const timeoutGraceMs = nonNegativeInteger(options.sigkillGraceMs)
+        ?? DEFAULT_TERMINATION_GRACE_MS;
+    const cancellationGraceMs = nonNegativeInteger(options.cancellationGraceMs)
+        ?? DEFAULT_TERMINATION_GRACE_MS;
+    const processLimitPollMs = positiveInteger(options.processLimitPollMs)
+        ?? DEFAULT_PROCESS_LIMIT_POLL_MS;
+    const maxOutputBytes = positiveInteger(options.maxOutputBytes);
+    const maxProcessCount = positiveInteger(options.maxProcessCount);
+    const encoding = options.encoding ?? "utf-8";
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let cancelled = false;
+        let processLimitExceeded = false;
+        let outputLimitExceeded = false;
+        let terminationReason = null;
+        let settled = false;
+        let timeoutTimer;
+        let forceKillTimer;
+        let processLimitTimer;
+        const spawnOptions = {
+            cwd: options.cwd,
+            env,
+            detached: platform !== "win32",
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+            windowsVerbatimArguments: spec.windowsVerbatimArguments,
+        };
+        let child;
+        try {
+            child = spawnImpl(spec.command, [...spec.args], spawnOptions);
+        }
+        catch (error) {
+            resolve({
+                stdout,
+                stderr,
+                status: null,
+                signal: null,
+                timedOut: false,
+                cancelled: false,
+                cancellationReason: null,
+                processLimitExceeded: false,
+                outputLimitExceeded: false,
+                terminationReason: null,
+                error: error,
+            });
+            return;
+        }
+        const requestTermination = (reason, graceMs) => {
+            if (settled || terminationReason !== null)
+                return;
+            terminationReason = reason;
+            options.onTerminationRequested?.(reason);
+            terminateProcessTree(child, platform, killSignal);
+            if (killSignal !== "SIGKILL") {
+                forceKillTimer = setTimeout(() => {
+                    if (!settled)
+                        terminateProcessTree(child, platform, "SIGKILL");
+                }, graceMs);
+                forceKillTimer.unref?.();
+            }
+        };
+        const parentCleanupHandler = (signal) => {
+            const parentSignal = typeof signal === "string"
+                ? signal
+                : killSignal;
+            terminateProcessTree(child, platform, parentSignal);
+        };
+        const cleanupSignals = ["SIGINT", "SIGTERM", "SIGHUP"];
+        if (options.cleanupOnParentExit) {
+            for (const signal of cleanupSignals)
+                process.once(signal, parentCleanupHandler);
+            process.once("beforeExit", parentCleanupHandler);
+            process.once("exit", parentCleanupHandler);
+        }
+        const removeParentHandlers = () => {
+            if (!options.cleanupOnParentExit)
+                return;
+            for (const signal of cleanupSignals)
+                process.off(signal, parentCleanupHandler);
+            process.off("beforeExit", parentCleanupHandler);
+            process.off("exit", parentCleanupHandler);
+        };
+        const cancellationHandler = () => {
+            if (settled || terminationReason !== null)
+                return;
+            cancelled = true;
+            requestTermination("cancellation", cancellationGraceMs);
+        };
+        cancellationSignal?.addEventListener("abort", cancellationHandler, { once: true });
+        const finish = (status, signal, error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+            if (forceKillTimer)
+                clearTimeout(forceKillTimer);
+            if (processLimitTimer)
+                clearInterval(processLimitTimer);
+            cancellationSignal?.removeEventListener("abort", cancellationHandler);
+            removeParentHandlers();
+            resolve({
+                stdout,
+                stderr,
+                status,
+                signal,
+                timedOut,
+                cancelled,
+                cancellationReason: cancelled
+                    ? cancellationReason(cancellationSignal, options.cancellationReason)
+                    : null,
+                processLimitExceeded,
+                outputLimitExceeded,
+                terminationReason,
+                ...(error ? { error } : {}),
+            });
+        };
+        const appendOutput = (current, chunk, observer) => {
+            if (outputLimitExceeded)
+                return current;
+            let accepted = chunk;
+            if (maxOutputBytes !== undefined) {
+                const currentBytes = Buffer.byteLength(current, encoding);
+                const remaining = Math.max(0, maxOutputBytes - currentBytes);
+                if (Buffer.byteLength(chunk, encoding) > remaining) {
+                    outputLimitExceeded = true;
+                    accepted = Buffer.from(chunk, encoding)
+                        .subarray(0, remaining)
+                        .toString(encoding);
+                    requestTermination("output_limit", timeoutGraceMs);
+                }
+            }
+            if (accepted !== "")
+                observer?.(accepted);
+            return current + accepted;
+        };
+        if (child.pid !== undefined)
+            options.onProcessStart?.(child.pid);
+        child.stdout?.setEncoding(encoding);
+        child.stderr?.setEncoding(encoding);
+        child.stdout?.on("data", (chunk) => {
+            stdout = appendOutput(stdout, chunk, options.onStdout);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr = appendOutput(stderr, chunk, options.onStderr);
+        });
+        child.stdin?.on("error", () => {
+            // EPIPE is expected when a provider exits before consuming its prompt.
+        });
+        child.stdin?.end(options.stdin);
+        child.on("error", (error) => {
+            finish(null, null, error);
+        });
+        child.on("exit", () => {
+            if (platform === "win32")
+                return;
+            terminateProcessTree(child, platform, killSignal);
+            const residualGraceMs = terminationReason === "cancellation"
+                ? cancellationGraceMs
+                : timeoutGraceMs;
+            const residualTimer = setTimeout(() => {
+                terminateProcessTree(child, platform, "SIGKILL");
+            }, residualGraceMs);
+            residualTimer.unref?.();
+        });
+        child.on("close", (status, signal) => {
+            finish(status, signal);
+        });
+        if (cancellationSignal?.aborted)
+            cancellationHandler();
+        if (timeoutMs !== undefined) {
+            timeoutTimer = setTimeout(() => {
+                if (settled || terminationReason !== null)
+                    return;
+                timedOut = true;
+                requestTermination("timeout", timeoutGraceMs);
+            }, timeoutMs);
+            timeoutTimer.unref?.();
+        }
+        if (platform === "linux" && maxProcessCount !== undefined) {
+            processLimitTimer = setInterval(() => {
+                if (settled || terminationReason !== null || child.pid === undefined)
+                    return;
+                const descendantCount = countLinuxDescendants(child.pid);
+                if (descendantCount !== undefined
+                    && descendantCount + 1 > maxProcessCount) {
+                    processLimitExceeded = true;
+                    requestTermination("process_limit", timeoutGraceMs);
+                }
+            }, processLimitPollMs);
+            processLimitTimer.unref?.();
+        }
+    });
+}
+export const runProcessTreeWithTimeout = runProcessTree;

package/dist/runtime/providers/claude.d.ts

@@ -0,0 +1,9 @@
+import type { ExecutionProvider } from "../execution-provider.js";
+import type { StepPacket } from "../run-contracts.js";
+export interface ClaudeExecutionProviderOptions {
+    readonly executable?: string;
+    readonly agentName?: (packet: StepPacket) => string;
+    readonly extraArgs?: readonly string[];
+    readonly env?: NodeJS.ProcessEnv;
+}
+export declare function createClaudeExecutionProvider(options?: ClaudeExecutionProviderOptions): ExecutionProvider;