specrails-core 6.0.0 → 6.1.0

package/dist/agent-runtime/engine/runs.js

@@ -0,0 +1,247 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { Command } from '@langchain/langgraph';
+import { pipelineStateDirectory } from '../../pipeline/pipeline-state.js';
+import { coreRuntimeIdentity } from '../core-host.js';
+import { sameRuntimeIdentity } from '../runtime-identity.js';
+import { appendRunEvent, RunDatabase } from './checkpoint/database.js';
+import { RunLedger } from './checkpoint/ledger.js';
+import { RunLease } from './checkpoint/lease.js';
+import { EngineError } from './contracts.js';
+import { EngineEventStream } from './events.js';
+import { initialDefinitionState } from './state.js';
+import { preflightDefinition } from './preflight.js';
+import { observeLedger, projectRunStatus } from './run-status.js';
+import { ControlInbox } from './steering/inbox.js';
+import { ledgerBudget } from './invocation-context.js';
+import { composeDefinitionRuntime } from './composition.js';
+import { createEngineTelemetry } from './otel.js';
+import { describeDefinition } from './graph-description.js';
+export const definitionRunDirectory = (context) => path.join(pipelineStateDirectory(context), 'agent-workflow');
+/** Frozen request shared with the legacy runtime (contracts.md section 9); `workflow.engine` selects the resume engine. */
+export const frozenRequestFile = (context) => path.join(pipelineStateDirectory(context), 'agent-runtime-request.json');
+/** A request without the workflow block predates the contract and belongs to the legacy engine. */
+export function frozenRequestEngine(request) {
+    const workflow = request && typeof request === 'object' ? request.workflow : undefined;
+    const engine = workflow && typeof workflow === 'object' ? workflow.engine : undefined;
+    return engine === 1 || engine === 2 ? engine : undefined;
+}
+/** Same no-overwrite discipline as the legacy writer: identical bytes are idempotent, anything else is another run. */
+function freezeRequest(file, request) {
+    const serialized = JSON.stringify(request, null, 2) + '\n';
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    try {
+        writeFileSync(file, serialized, { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        if (readFileSync(file, 'utf8') !== serialized)
+            throw new EngineError('run_exists', 'A different frozen request already uses this run ID; choose a new run ID');
+    }
+}
+/** Materializes the frozen request of an existing definition run (fork destinations) so hosts recognize a programmatic run. */
+export async function freezeRunRequest(directory) {
+    const database = await RunDatabase.open(path.join(directory, 'run.sqlite'), { readOnly: true });
+    try {
+        const row = observeLedger(database).run(), request = JSON.parse(String(row.request_json));
+        const file = frozenRequestFile(request.context);
+        freezeRequest(file, { ...(request.change ? { change: request.change } : {}), config: request.config, runtimeIdentity: JSON.parse(String(row.runtime_identity_json)),
+            workflow: { id: String(row.workflow_id), version: String(row.definition_hash), source: 'definition', definitionHash: String(row.definition_hash), engine: 2 } });
+        return file;
+    }
+    finally {
+        database.close();
+    }
+}
+export async function createRun(input) {
+    const admitted = await preflightDefinition(input);
+    // The request is frozen before the database exists so a crash between the two leaves a
+    // request that a repeated identical `run` completes and a different one cannot reuse.
+    freezeRequest(frozenRequestFile(admitted.request.context), { ...(admitted.request.change ? { change: admitted.request.change } : {}), config: admitted.request.config, runtimeIdentity: coreRuntimeIdentity(),
+        workflow: { id: admitted.definition.id, version: admitted.definition.version, source: 'definition', definitionHash: admitted.definition.version, engine: 2 } });
+    const database = await RunDatabase.open(path.join(definitionRunDirectory(admitted.request.context), 'run.sqlite'), { create: true });
+    try {
+        RunLedger.initialize(database, { runId: admitted.request.context.runId, workflowId: admitted.definition.id,
+            definitionHash: admitted.definition.version, definition: admitted.definition, request: admitted.request,
+            runtimeIdentity: coreRuntimeIdentity(), source: 'definition', budget: admitted.budget });
+        const result = await execute(database, admitted, { ...input, context: admitted.request.context }, false);
+        return { ...projectRunStatus(observeLedger(database)), ...('error' in result ? { error: result.error } : {}) };
+    }
+    finally {
+        database.close();
+    }
+}
+export async function resumeRun(directory, options = {}) {
+    const database = await RunDatabase.open(path.join(directory, 'run.sqlite'));
+    try {
+        const view = observeLedger(database), row = view.run();
+        if (!sameRuntimeIdentity(JSON.parse(String(row.runtime_identity_json)), coreRuntimeIdentity()))
+            throw new EngineError('resume_incompatible', 'Resume requires the retained original Core package');
+        const request = JSON.parse(String(row.request_json));
+        if (options.answers && Object.keys(options.answers).length)
+            validateAnswers(view, options.answers);
+        if (options.context && JSON.stringify(options.context) !== JSON.stringify(request.context)) {
+            const { contentDigest } = await import('./canonical-json.js');
+            if (contentDigest(options.context) !== contentDigest(request.context))
+                throw new EngineError('scope_mismatch', 'Host context differs from the frozen run');
+        }
+        if (row.completion_json || row.status === 'cancelled') {
+            new EngineEventStream(cursor => view.events(cursor), options.onEvent ?? (() => { })).send(describeDefinition(view.runId, JSON.parse(String(row.definition_json))));
+            return projectRunStatus(view);
+        }
+        const admitted = await preflightDefinition({ ...request, definition: JSON.parse(String(row.definition_json)), registry: options.registry });
+        const result = await execute(database, admitted, options, true);
+        return { ...projectRunStatus(observeLedger(database)), ...('error' in result ? { error: result.error } : {}) };
+    }
+    finally {
+        database.close();
+    }
+}
+/** Every effect runs under one lease and cancellation domain; the saver owns settlement. */
+async function execute(database, admitted, options, resume) {
+    const runId = admitted.request.context.runId, lease = new RunLease(database, runId), token = lease.acquire(randomUUID());
+    const ledger = new RunLedger(database, token, { maxTransitions: admitted.definition.maxTransitions, failFast: admitted.definition.policies?.failFast });
+    const controller = new AbortController(), abort = () => controller.abort(options.signal?.reason ?? new EngineError('aborted', 'Execution cancelled'));
+    if (options.signal?.aborted)
+        abort();
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const stopHeartbeat = lease.heartbeat(token, error => controller.abort(error)), inbox = new ControlInbox(database, runId);
+    const telemetry = createEngineTelemetry();
+    const stream = new EngineEventStream(cursor => ledger.events(cursor), options.onEvent ?? (() => { }), options.afterEvent, undefined, event => telemetry?.observe(event));
+    let runtime;
+    const config = { configurable: { thread_id: String(ledger.run().checkpoint_thread_id) }, durability: 'sync',
+        recursionLimit: admitted.definition.maxTransitions * 4 + 20 };
+    const controlTimer = setInterval(() => {
+        try {
+            if (inbox.cancellationRequested())
+                controller.abort(new EngineError('aborted', 'Cancellation requested'));
+            const limit = ledgerBudget(ledger).maxDurationMs;
+            if (limit !== undefined && ledger.activeDurationMs() >= limit)
+                controller.abort(new EngineError('timeout', 'Workflow active-duration budget exhausted'));
+        }
+        catch (error) {
+            controller.abort(error);
+        }
+    }, 250);
+    controlTimer.unref();
+    try {
+        ledger.settleAbandonedInvocations();
+        stream.send(describeDefinition(runId, admitted.definition));
+        runtime = await composeDefinitionRuntime(database, ledger, admitted, stream, controller.signal);
+        const { graph, saver, deps } = runtime;
+        deps.initializeCandidate();
+        if (options.answers && Object.keys(options.answers).length) {
+            validateAnswers(ledger, options.answers);
+            ledger.answerInterrupts(options.answers);
+        }
+        for (const target of options.recover ?? []) {
+            const rows = database.sqlite.prepare("SELECT a.attempt_id FROM attempts a JOIN visits v ON a.visit_id=v.visit_id JOIN steps s ON s.last_attempt_id=a.attempt_id WHERE a.run_id=? AND (a.attempt_id=? OR a.node_path=?) AND a.terminal_digest IS NULL AND a.status IN ('running','interrupted') AND v.effect='write'").all(runId, target, target);
+            if (rows.length !== 1)
+                throw new EngineError('recovery_ambiguous', 'Recovery must identify exactly one interrupted write attempt');
+            ledger.authorizeRecovery(String(rows[0].attempt_id));
+        }
+        if (resume)
+            database.transaction('workflow-resumed', () => {
+                lease.assert(token);
+                appendRunEvent(database, runId, 'workflow_resumed', {});
+            });
+        stream.flush();
+        const snapshot = await graph.getState(config, { subgraphs: true });
+        const activeInterrupts = new Set(snapshot.tasks.flatMap(task => task.interrupts).map(value => value.id));
+        const answers = Object.fromEntries(ledger.interrupts().filter(value => value.answer !== undefined && activeInterrupts.has(value.id)).map(value => [value.id, value.answer]));
+        const checkpoint = await saver.getTuple(config);
+        const hasInterrupts = snapshot.tasks.some(task => task.interrupts.length > 0);
+        if (hasInterrupts && !Object.keys(answers).length)
+            return projectRunStatus(ledger);
+        await graph.invoke(!checkpoint ? initialDefinitionState(admitted.request.change ? { changeId: admitted.request.change } : {}) : Object.keys(answers).length && hasInterrupts ? new Command({ resume: answers }) : null, { ...config, signal: controller.signal });
+        ledger.settlePause();
+        const row = ledger.run();
+        if (!row.completion_json && !ledger.pendingInterrupts().length && !['interrupted', 'failed', 'blocked'].includes(String(row.status))) {
+            throw new EngineError('completion_missing', 'Graph stopped without a durable completion or pending interruption');
+        }
+        return projectRunStatus(ledger);
+    }
+    catch (error) {
+        // A lost owner may observe, but can never settle effects after a newer epoch.
+        if (controller.signal.reason instanceof EngineError && controller.signal.reason.code === 'lease_lost')
+            throw controller.signal.reason;
+        const reason = controller.signal.aborted ? controller.signal.reason : error;
+        const code = reason instanceof EngineError || reason && typeof reason === 'object' && 'code' in reason ? String(reason.code) : 'execution_failed';
+        const message = reason instanceof Error ? reason.message : String(reason);
+        database.transaction('execution-stopped', () => {
+            lease.assert(token);
+            const row = ledger.run();
+            if (row.completion_json)
+                return;
+            const status = code === 'aborted' ? 'cancelled' : row.status === 'interrupted' || code === 'recover_required' ? 'interrupted' : 'failed';
+            database.put('runs', { ...row, status, active_duration_ms: ledger.activeDurationMs(), active_started_at: null, updated_at: new Date().toISOString() });
+            appendRunEvent(database, runId, status === 'cancelled' ? 'workflow_cancelled' : 'workflow_failed', { error: { code, message } });
+        });
+        if (inbox.cancellationRequested())
+            inbox.acknowledgeCancellation(token);
+        const status = projectRunStatus(ledger);
+        return { ...status, error: { code, message } };
+    }
+    finally {
+        clearInterval(controlTimer);
+        stopHeartbeat();
+        options.signal?.removeEventListener('abort', abort);
+        runtime?.close();
+        stream.flush();
+        lease.release(token);
+        await telemetry?.close();
+    }
+}
+function validateAnswers(ledger, answers) {
+    const known = new Map(ledger.interrupts().map(value => [value.id, value]));
+    for (const [id, value] of Object.entries(answers)) {
+        const request = known.get(id);
+        if (!request)
+            throw new EngineError('interrupt_not_found', 'Unknown interrupt ID');
+        const object = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+        if (request.kind === 'question' ? typeof object.answer !== 'string' || !object.answer.trim() : object.approved !== true)
+            throw new EngineError('invalid_resume', 'Resume requires a matching nonempty answer or explicit approval');
+    }
+}
+export async function signalRun(directory, text, requestId) {
+    const database = await RunDatabase.open(path.join(directory, 'run.sqlite'));
+    try {
+        return new ControlInbox(database, observeLedger(database).runId).append(text, { requestId });
+    }
+    finally {
+        database.close();
+    }
+}
+export async function cancelRun(directory, requestId) {
+    const database = await RunDatabase.open(path.join(directory, 'run.sqlite'));
+    try {
+        const runId = observeLedger(database).runId, inbox = new ControlInbox(database, runId), accepted = inbox.cancel(requestId);
+        const lease = new RunLease(database, runId);
+        if ((lease.current()?.expiresAt ?? 0) > Date.now())
+            return accepted;
+        const token = lease.acquire(randomUUID());
+        try {
+            const ledger = new RunLedger(database, token, { maxTransitions: 1 });
+            database.transaction('workflow-cancelled', () => {
+                lease.assert(token);
+                const run = ledger.run();
+                // An idempotent retry or a run finishing between inbox admission and
+                // lease acquisition must not rewrite terminal truth or duplicate it.
+                if (run.status === 'cancelled' || run.status === 'succeeded' || run.completion_json)
+                    return;
+                database.put('runs', { ...run, status: 'cancelled', active_duration_ms: ledger.activeDurationMs(), active_started_at: null });
+                appendRunEvent(database, runId, 'workflow_cancelled', {});
+            });
+            inbox.acknowledgeCancellation(token);
+        }
+        finally {
+            lease.release(token);
+        }
+        return accepted;
+    }
+    finally {
+        database.close();
+    }
+}

package/dist/agent-runtime/engine/state.d.ts

@@ -0,0 +1,64 @@
+import { EphemeralValue } from '@langchain/langgraph/channels';
+import { type BranchState, type CandidateState, type CoreDefinitionState, type EngineAnswer, type EngineUsage, type ExecutionScope, type HistoryEntry, type JsonValue, type TerminalCommit, type VerifiedState } from './contracts.js';
+export declare function emptyUsage(): EngineUsage;
+export declare function mergeRevision<T extends {
+    revision: number;
+}>(previous: T, update: T): T;
+type OrderedRecord = {
+    id: string;
+    transition: number;
+    attempt: number;
+    ordinal: number;
+};
+export declare function mergeOrdered<T extends OrderedRecord>(previous: T[], update: T[]): T[];
+export declare function mergeHistory(previous: HistoryEntry[], update: HistoryEntry[], maxChars: number): HistoryEntry[];
+/** Private commit markers reach each task's saver writes and expire after a superstep. */
+export declare function definitionStateSchema(historyMaxChars?: number, scope?: ExecutionScope | null): import("@langchain/langgraph").AnnotationRoot<{
+    $outputs: import("@langchain/langgraph").BaseChannel<Record<string, JsonValue>, Record<string, JsonValue> | import("@langchain/langgraph").OverwriteValue<Record<string, JsonValue>>, unknown>;
+    $vars: import("@langchain/langgraph").BaseChannel<Record<string, JsonValue>, Record<string, JsonValue> | import("@langchain/langgraph").OverwriteValue<Record<string, JsonValue>>, unknown>;
+    $history: import("@langchain/langgraph").BaseChannel<HistoryEntry[], HistoryEntry[] | import("@langchain/langgraph").OverwriteValue<HistoryEntry[]>, unknown>;
+    $sessions: import("@langchain/langgraph").BaseChannel<Record<string, {
+        sessionId: string;
+        identity: string;
+    }>, Record<string, {
+        sessionId: string;
+        identity: string;
+    }> | import("@langchain/langgraph").OverwriteValue<Record<string, {
+        sessionId: string;
+        identity: string;
+    }>>, unknown>;
+    $usage: import("@langchain/langgraph").BaseChannel<EngineUsage, EngineUsage | import("@langchain/langgraph").OverwriteValue<EngineUsage>, unknown>;
+    $attempts: import("@langchain/langgraph").BaseChannel<Record<string, number>, Record<string, number> | import("@langchain/langgraph").OverwriteValue<Record<string, number>>, unknown>;
+    $consecutiveFailures: import("@langchain/langgraph").BaseChannel<{
+        revision: number;
+        count: number;
+    }, {
+        revision: number;
+        count: number;
+    } | import("@langchain/langgraph").OverwriteValue<{
+        revision: number;
+        count: number;
+    }>, unknown>;
+    $candidate: import("@langchain/langgraph").BaseChannel<CandidateState | null, CandidateState | import("@langchain/langgraph").OverwriteValue<CandidateState | null> | null, unknown>;
+    $verified: import("@langchain/langgraph").BaseChannel<VerifiedState | null, VerifiedState | import("@langchain/langgraph").OverwriteValue<VerifiedState | null> | null, unknown>;
+    $answers: import("@langchain/langgraph").BaseChannel<EngineAnswer[], EngineAnswer[] | import("@langchain/langgraph").OverwriteValue<EngineAnswer[]>, unknown>;
+    $branches: import("@langchain/langgraph").BaseChannel<Record<string, BranchState>, Record<string, BranchState> | import("@langchain/langgraph").OverwriteValue<Record<string, BranchState>>, unknown>;
+    $maps: import("@langchain/langgraph").BaseChannel<Record<string, import("./contracts.js").MapPlan>, Record<string, import("./contracts.js").MapPlan> | import("@langchain/langgraph").OverwriteValue<Record<string, import("./contracts.js").MapPlan>>, unknown>;
+    $transitions: import("@langchain/langgraph").BaseChannel<number, number | import("@langchain/langgraph").OverwriteValue<number>, unknown>;
+    $lastOutcome: import("@langchain/langgraph").BaseChannel<Record<string, string>, Record<string, string> | import("@langchain/langgraph").OverwriteValue<Record<string, string>>, unknown>;
+    $item: import("@langchain/langgraph").BaseChannel<{
+        index: number;
+        value: JsonValue;
+    } | null, {
+        index: number;
+        value: JsonValue;
+    } | import("@langchain/langgraph").OverwriteValue<{
+        index: number;
+        value: JsonValue;
+    } | null> | null, unknown>;
+    $scope: import("@langchain/langgraph").BaseChannel<ExecutionScope, ExecutionScope | import("@langchain/langgraph").OverwriteValue<ExecutionScope>, unknown>;
+    $exit: import("@langchain/langgraph").BaseChannel<import("./contracts.js").ComponentExit | null, import("./contracts.js").ComponentExit | import("@langchain/langgraph").OverwriteValue<import("./contracts.js").ComponentExit | null> | null, unknown>;
+    $commit: EphemeralValue<TerminalCommit>;
+}>;
+export declare function initialDefinitionState(vars?: Record<string, JsonValue>, scope?: ExecutionScope): CoreDefinitionState;
+export {};

package/dist/agent-runtime/engine/state.js

@@ -0,0 +1,98 @@
+import { Annotation } from '@langchain/langgraph';
+import { EphemeralValue } from '@langchain/langgraph/channels';
+import { canonicalJson } from './canonical-json.js';
+import { EngineError } from './contracts.js';
+export function emptyUsage() {
+    return { revision: 0, invocations: 0, costUsd: 0, inputTokens: 0, outputTokens: 0, knownCostUsd: 0, knownInputTokens: 0, knownOutputTokens: 0 };
+}
+function mergeKeys(previous, update) {
+    return Object.assign(Object.create(null), previous, update);
+}
+export function mergeRevision(previous, update) {
+    if (update.revision < previous.revision)
+        return previous;
+    if (update.revision === previous.revision && canonicalJson(update) !== canonicalJson(previous))
+        throw new EngineError('state_revision_conflict', 'Two different values have the same durable revision');
+    return update;
+}
+export function mergeOrdered(previous, update) {
+    const entries = new Map(previous.map(value => [value.id, value]));
+    for (const value of update) {
+        const existing = entries.get(value.id);
+        if (existing && canonicalJson(existing) !== canonicalJson(value))
+            throw new EngineError('state_record_conflict', `Record ${value.id} has conflicting content`);
+        entries.set(value.id, value);
+    }
+    return [...entries.values()].sort((a, b) => a.transition - b.transition || a.attempt - b.attempt || a.ordinal - b.ordinal || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+export function mergeHistory(previous, update, maxChars) {
+    const bounded = update.flatMap(entry => {
+        if (JSON.stringify(entry).length <= maxChars - 2)
+            return [entry];
+        let low = 0;
+        let high = Math.min(entry.text.length, maxChars);
+        while (low < high) {
+            const middle = Math.ceil((low + high) / 2);
+            if (JSON.stringify({ ...entry, text: entry.text.slice(0, middle), truncated: true }).length <= maxChars - 2)
+                low = middle;
+            else
+                high = middle - 1;
+        }
+        const trimmed = { ...entry, text: entry.text.slice(0, low).replace(/[\uD800-\uDBFF]$/, ''), truncated: true };
+        return JSON.stringify(trimmed).length <= maxChars - 2 ? [trimmed] : [];
+    });
+    const entries = mergeOrdered(previous, bounded);
+    let total = 2 + Math.max(0, entries.length - 1) + entries.reduce((sum, entry) => sum + JSON.stringify(entry).length, 0);
+    while (entries.length && total > maxChars)
+        total -= JSON.stringify(entries.shift()).length + (entries.length ? 1 : 0);
+    return entries;
+}
+function mergeBranches(previous, update) {
+    const merged = mergeKeys(previous, {});
+    for (const [id, branch] of Object.entries(update)) {
+        const existing = merged[id];
+        if (existing?.visitId !== branch.visitId && existing?.visitId && branch.visitId) {
+            if ((branch.transition ?? 0) <= (existing.transition ?? 0))
+                continue;
+            merged[id] = { ...branch, done: branch.results.length };
+            continue;
+        }
+        if (existing && existing.total !== branch.total)
+            throw new EngineError('state_record_conflict', `Branch count changed for ${id}`);
+        const results = mergeOrdered(existing?.results ?? [], branch.results);
+        merged[id] = { ...branch, results, done: results.length };
+    }
+    return merged;
+}
+/** Private commit markers reach each task's saver writes and expire after a superstep. */
+export function definitionStateSchema(historyMaxChars = 1500, scope = { id: 'root', nodePathPrefix: '' }) {
+    return Annotation.Root({
+        $outputs: Annotation({ reducer: mergeKeys, default: () => ({}) }),
+        $vars: Annotation({ reducer: mergeKeys, default: () => ({}) }),
+        $history: Annotation({ reducer: (a, b) => mergeHistory(a, b, historyMaxChars), default: () => [] }),
+        $sessions: Annotation({ reducer: mergeKeys, default: () => ({}) }),
+        $usage: Annotation({ reducer: mergeRevision, default: emptyUsage }),
+        $attempts: Annotation({ reducer: (a, b) => { const result = mergeKeys(a, {}); for (const [id, count] of Object.entries(b))
+                result[id] = Math.max(result[id] ?? 0, count); return result; }, default: () => ({}) }),
+        $consecutiveFailures: Annotation({ reducer: mergeRevision, default: () => ({ revision: 0, count: 0 }) }),
+        $candidate: Annotation({ reducer: (a, b) => b === null ? a : a === null ? b : mergeRevision(a, b), default: () => null }),
+        // Only the exclusive writer emits this channel. Read branches never publish stale receipts.
+        $verified: Annotation({ reducer: (a, b) => b === null ? null : a === null ? b : mergeRevision(a, b), default: () => null }),
+        $answers: Annotation({ reducer: mergeOrdered, default: () => [] }),
+        $branches: Annotation({ reducer: mergeBranches, default: () => ({}) }),
+        $maps: Annotation({ reducer: mergeKeys, default: () => ({}) }),
+        $transitions: Annotation({ reducer: Math.max, default: () => 0 }),
+        $lastOutcome: Annotation({ reducer: mergeKeys, default: () => ({}) }),
+        $item: Annotation({ reducer: (_a, b) => b, default: () => null }),
+        $scope: Annotation({ reducer: (a, b) => { if (!a.id)
+                return b; if (canonicalJson(a) !== canonicalJson(b))
+                throw new EngineError('state_scope_conflict', 'Execution scope is immutable'); return a; }, default: () => structuredClone(scope ?? { id: '', nodePathPrefix: '' }) }),
+        $exit: Annotation({ reducer: (a, b) => b && (!a || b.transition >= a.transition) ? b : a, default: () => null }),
+        $commit: new EphemeralValue(false),
+    });
+}
+export function initialDefinitionState(vars = {}, scope = { id: 'root', nodePathPrefix: '' }) {
+    return { $outputs: {}, $vars: structuredClone(vars), $history: [], $sessions: {}, $usage: emptyUsage(), $attempts: {},
+        $consecutiveFailures: { revision: 0, count: 0 }, $candidate: null, $verified: null, $answers: [], $branches: {}, $maps: {},
+        $transitions: 0, $lastOutcome: {}, $item: null, $scope: structuredClone(scope), $exit: null };
+}

package/dist/agent-runtime/engine/steering/inbox.d.ts

@@ -0,0 +1,54 @@
+import { type AttemptFrame, type ExecutionLease } from '../contracts.js';
+import { RunDatabase } from '../checkpoint/database.js';
+export declare const MAX_STEERING_CHARACTERS = 20000;
+export declare const MAX_STEERING_BYTES = 80000;
+export declare const MAX_PENDING_STEERING = 128;
+export declare const MAX_PENDING_STEERING_BYTES: number;
+export interface SteeringMessage {
+    id: string;
+    text: string;
+    sender: string;
+    createdAt: string;
+    consumedByAttemptId?: string;
+    consumedAt?: string;
+}
+export interface SteeringReceipt {
+    id: string;
+    acceptedAt: string;
+    preview: string;
+    length: number;
+    status: 'pending' | 'consumed';
+    consumedAttemptId?: string;
+    consumedAt?: string;
+}
+/** A second process can append controls without acquiring or replacing the execution lease. */
+export declare class ControlInbox {
+    readonly database: RunDatabase;
+    readonly runId: string;
+    constructor(database: RunDatabase, runId: string);
+    append(text: string, options?: {
+        requestId?: string;
+        sender?: string;
+    }): SteeringMessage;
+    cancel(requestId?: string): {
+        requestId: string;
+        createdAt: string;
+    };
+    private appendControl;
+    pending(): SteeringMessage[];
+    /** Bounded read-only projection. Counts cover the whole inbox, previews never expose full prompts. */
+    status(): {
+        receipts: SteeringReceipt[];
+        pending: number;
+        consumed: number;
+        truncated: boolean;
+        consumptionReported: true;
+    };
+    assigned(frame: AttemptFrame): SteeringMessage[];
+    /** Called inside attempt admission, after the attempt row exists and the lease was fenced. */
+    claimForAttempt(frame: AttemptFrame): SteeringMessage[];
+    cancellationRequested(): boolean;
+    acknowledgeCancellation(token: ExecutionLease): void;
+}
+/** Operator text is delimited and cannot replace frozen acceptance obligations/instructions. */
+export declare function renderOperatorSteering(messages: readonly SteeringMessage[]): string;

package/dist/agent-runtime/engine/steering/inbox.js

@@ -0,0 +1,113 @@
+import { randomUUID } from 'node:crypto';
+import { canonicalJson } from '../canonical-json.js';
+import { EngineError } from '../contracts.js';
+import { appendRunEvent } from '../checkpoint/database.js';
+import { RunLease } from '../checkpoint/lease.js';
+export const MAX_STEERING_CHARACTERS = 20_000;
+export const MAX_STEERING_BYTES = 80_000;
+export const MAX_PENDING_STEERING = 128;
+export const MAX_PENDING_STEERING_BYTES = 512 * 1024;
+const project = (row) => {
+    const value = JSON.parse(String(row.payload_json));
+    return { id: String(row.request_id), ...value, createdAt: String(row.created_at),
+        ...(row.consumed_by_attempt_id ? { consumedByAttemptId: String(row.consumed_by_attempt_id) } : {}), ...(row.consumed_at ? { consumedAt: String(row.consumed_at) } : {}) };
+};
+/** A second process can append controls without acquiring or replacing the execution lease. */
+export class ControlInbox {
+    database;
+    runId;
+    constructor(database, runId) {
+        this.database = database;
+        this.runId = runId;
+    }
+    append(text, options = {}) {
+        if (typeof text !== 'string' || !text.trim() || text.length > MAX_STEERING_CHARACTERS || Buffer.byteLength(text, 'utf8') > MAX_STEERING_BYTES)
+            throw new EngineError('invalid_arguments', `Steering must contain 1–${MAX_STEERING_CHARACTERS} characters, within ${MAX_STEERING_BYTES} UTF-8 bytes`);
+        const sender = options.sender ?? 'operator';
+        if (!sender || sender.length > 128)
+            throw new EngineError('invalid_arguments', 'Steering sender must contain 1–128 characters');
+        const row = this.appendControl('steer', { text, sender }, options.requestId ?? randomUUID());
+        return project(row);
+    }
+    cancel(requestId = randomUUID()) {
+        const row = this.appendControl('cancel', {}, requestId);
+        return { requestId: String(row.request_id), createdAt: String(row.created_at) };
+    }
+    appendControl(kind, payload, requestId) {
+        if (!requestId || requestId.length > 256)
+            throw new EngineError('invalid_arguments', 'Control request ID must contain 1–256 characters');
+        const encoded = canonicalJson(payload);
+        return this.database.transaction('control-appended', () => {
+            const run = this.database.get('runs', { run_id: this.runId });
+            if (!run)
+                throw new EngineError('run_not_found', 'Run does not exist');
+            const existing = this.database.get('control_inbox', { request_id: requestId });
+            if (existing) {
+                if (existing.run_id !== this.runId || existing.kind !== kind || existing.payload_json !== encoded)
+                    throw new EngineError('control_conflict', 'An idempotency key cannot change its control payload');
+                return existing;
+            }
+            if (run.completion_json || run.status === 'succeeded' || run.status === 'cancelled')
+                throw new EngineError('run_terminal', 'Completed runs cannot receive new controls');
+            if (kind === 'steer') {
+                const pending = this.database.sqlite.prepare("SELECT COUNT(*) count,COALESCE(SUM(length(CAST(payload_json AS BLOB))),0) bytes FROM control_inbox WHERE run_id=? AND kind='steer' AND consumed_at IS NULL").get(this.runId);
+                if (Number(pending.count) >= MAX_PENDING_STEERING || Number(pending.bytes) + Buffer.byteLength(encoded) > MAX_PENDING_STEERING_BYTES)
+                    throw new EngineError('inbox_full', 'Pending operator steering reached its bounded capacity');
+            }
+            const at = new Date().toISOString();
+            this.database.put('control_inbox', { request_id: requestId, run_id: this.runId, kind, payload_json: encoded, created_at: at, received_sequence: run.next_event_sequence });
+            appendRunEvent(this.database, this.runId, kind === 'steer' ? 'steering_received' : 'cancellation_requested', { requestId }, {}, at);
+            return this.database.get('control_inbox', { request_id: requestId });
+        });
+    }
+    pending() {
+        return this.database.sqlite.prepare("SELECT * FROM control_inbox WHERE run_id=? AND kind='steer' AND consumed_at IS NULL ORDER BY received_sequence,request_id").all(this.runId).map(project);
+    }
+    /** Bounded read-only projection. Counts cover the whole inbox, previews never expose full prompts. */
+    status() {
+        const counts = this.database.sqlite.prepare("SELECT COUNT(*) total,COALESCE(SUM(consumed_at IS NULL),0) pending FROM control_inbox WHERE run_id=? AND kind='steer'").get(this.runId);
+        const rows = this.database.sqlite.prepare("SELECT * FROM control_inbox WHERE run_id=? AND kind='steer' ORDER BY consumed_at IS NULL DESC,received_sequence DESC,request_id DESC LIMIT 512").all(this.runId);
+        const receipts = rows.map(row => {
+            const message = project(row);
+            return { id: message.id, acceptedAt: message.createdAt, preview: message.text.slice(0, 240), length: message.text.length,
+                status: message.consumedAt ? 'consumed' : 'pending',
+                ...(message.consumedByAttemptId ? { consumedAttemptId: message.consumedByAttemptId } : {}),
+                ...(message.consumedAt ? { consumedAt: message.consumedAt } : {}) };
+        });
+        return { receipts, pending: Number(counts.pending), consumed: Number(counts.total) - Number(counts.pending),
+            truncated: Number(counts.total) > rows.length, consumptionReported: true };
+    }
+    assigned(frame) {
+        return this.database.sqlite.prepare("SELECT * FROM control_inbox WHERE run_id=? AND kind='steer' AND consumed_by_attempt_id=? ORDER BY received_sequence,request_id").all(this.runId, frame.attemptId).map(project);
+    }
+    /** Called inside attempt admission, after the attempt row exists and the lease was fenced. */
+    claimForAttempt(frame) {
+        void this.database.transactionRevision;
+        const attempt = this.database.get('attempts', { attempt_id: frame.attemptId });
+        if (!attempt || attempt.run_id !== this.runId || attempt.status !== 'running' || attempt.lease_epoch !== frame.leaseEpoch)
+            throw new EngineError('attempt_mismatch', 'Steering can only be claimed by the admitted attempt');
+        const now = new Date().toISOString();
+        for (const row of this.database.sqlite.prepare("SELECT * FROM control_inbox WHERE run_id=? AND kind='steer' AND consumed_at IS NULL ORDER BY received_sequence,request_id").all(this.runId)) {
+            this.database.put('control_inbox', { ...row, consumed_by_attempt_id: frame.attemptId, consumed_at: now });
+        }
+        return this.assigned(frame);
+    }
+    cancellationRequested() {
+        return !!this.database.sqlite.prepare("SELECT 1 FROM control_inbox WHERE run_id=? AND kind='cancel' AND consumed_at IS NULL").get(this.runId);
+    }
+    acknowledgeCancellation(token) {
+        this.database.transaction('cancellation-consumed', () => {
+            new RunLease(this.database, this.runId).assert(token);
+            for (const row of this.database.sqlite.prepare("SELECT * FROM control_inbox WHERE run_id=? AND kind='cancel' AND consumed_at IS NULL").all(this.runId)) {
+                this.database.put('control_inbox', { ...row, consumed_at: new Date().toISOString() });
+            }
+        });
+    }
+}
+/** Operator text is delimited and cannot replace frozen acceptance obligations/instructions. */
+export function renderOperatorSteering(messages) {
+    if (!messages.length)
+        return '';
+    return '\n\n## Operator steering\n\nApply these operator messages within the frozen workflow and its acceptance requirements.\n\n' +
+        messages.map(message => `### Message ${JSON.stringify(message.id)} from ${JSON.stringify(message.sender)}\n${JSON.stringify(message.text)}`).join('\n\n');
+}

package/dist/agent-runtime/engine/storage/fork-allocation.d.ts

@@ -0,0 +1,21 @@
+/** SQLite holds the construction lock across awaits and releases it on process
+ * death. The separate, flushed manifest survives that rollback. Directories are
+ * recorded by inode before their atomic rename, so recovery never removes a
+ * replacement directory or a child already published by Core.
+ */
+export declare class ForkAllocation {
+    private readonly lock;
+    private readonly directory;
+    private readonly parents;
+    private manifest;
+    private constructor();
+    static open(target: string, artifactRoot: string, requestId: string | undefined, digest: string): Promise<ForkAllocation>;
+    /** Call only after ruling out a published child. No request ID means no retry. */
+    recover(): void;
+    /** Reserve an empty directory before any journal/artifact writes occur. */
+    reserve(target: string): void;
+    cleanup(): void;
+    close(): void;
+    private validate;
+    private save;
+}