specrails-core 6.0.0 → 6.1.0

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

@@ -0,0 +1,605 @@
+import { type PipelineContext } from '../../pipeline/pipeline-state.js';
+import type { RuntimeConfig } from '../executor-types.js';
+import { type RuntimeIdentity } from '../runtime-identity.js';
+import type { ExecutorRegistry } from '../executors.js';
+import { type JsonObject, type JsonValue } from './contracts.js';
+import { type DefinitionRunInput } from './preflight.js';
+export declare const definitionRunDirectory: (context: PipelineContext) => string;
+/** Frozen request shared with the legacy runtime (contracts.md section 9); `workflow.engine` selects the resume engine. */
+export declare const frozenRequestFile: (context: PipelineContext) => string;
+export interface FrozenWorkflowIdentity {
+    id: string;
+    version: string;
+    source: 'builtin' | 'definition';
+    definitionHash: string | null;
+    engine: 1 | 2;
+}
+export interface FrozenRunRequest {
+    change?: string;
+    config: RuntimeConfig;
+    runtimeIdentity: RuntimeIdentity;
+    workflow: FrozenWorkflowIdentity;
+}
+/** A request without the workflow block predates the contract and belongs to the legacy engine. */
+export declare function frozenRequestEngine(request: unknown): 1 | 2 | undefined;
+/** Materializes the frozen request of an existing definition run (fork destinations) so hosts recognize a programmatic run. */
+export declare function freezeRunRequest(directory: string): Promise<string>;
+export interface RunObservers {
+    signal?: AbortSignal;
+    onEvent?: (value: JsonObject) => void;
+    afterEvent?: number;
+}
+export interface ResumeDefinitionOptions extends RunObservers {
+    registry?: ExecutorRegistry;
+    answers?: Record<string, JsonValue>;
+    recover?: string[];
+    /** Optional frozen host context assertion prevents attaching another project's run. */
+    context?: PipelineContext;
+}
+export declare function createRun(input: DefinitionRunInput & RunObservers): Promise<{
+    error?: {
+        code: string;
+        message: string;
+    } | undefined;
+    metrics: import("../efficiency-types.js").RuntimeEfficiency;
+    efficiencySummary: {
+        reservations: {
+            pendingInvocations: number;
+            knownTokens: number;
+            knownCostUsd: number;
+            tokensUnknown: boolean;
+            costUnknown: boolean;
+        };
+        schemaVersion: 1;
+        currentEvidenceIds: string[];
+        planHash: string | null;
+        candidateHash: string | null;
+        runId: string;
+        workflowVersion: string;
+        technicalAcceptance: string;
+        archive: import("../../pipeline/pipeline-state.js").PhaseStatus;
+        delivery: "pending" | "complete" | "pending-host";
+        roles: {
+            role: string;
+            provider: string | null;
+            model: string | null;
+            effort: string | null;
+            observedModel: null;
+            observedEffort: null;
+            origin: string;
+            tier: "base" | "escalation";
+        }[];
+        invocations: {
+            byKind: {
+                [k: string]: number;
+            };
+            total: number;
+            complete: boolean;
+            promptBytes: number | null;
+            contextBytes: number | null;
+            handoffBytes: number | null;
+            fullContexts: number;
+            incrementalContexts: number;
+        };
+        escalations: {
+            role: string;
+            attemptId: string;
+            provider: string;
+            model: string | null;
+            effort: string | null;
+            reason: string | null;
+        }[];
+        escalationsTruncated: boolean;
+        checks: {
+            invalidated: number | null;
+            available: boolean;
+            complete: boolean;
+            executed: number | null;
+            reused: number | null;
+            notRun: number | null;
+            durationMs: number | null;
+        };
+        metrics: import("../efficiency-types.js").RuntimeEfficiency;
+    };
+    revision: number;
+    eventCursor: number;
+    forkOf?: string | undefined;
+    type: "runtime-status";
+    engineVersion: number;
+    state: {
+        nextNodePath: string;
+        nextStep: string;
+        steps: {
+            [k: string]: {
+                kind: string;
+                status: string;
+                visits: number;
+            };
+        };
+        scopes: {
+            output?: unknown;
+            nodePath: string;
+            scopeId: string;
+            branch: import("node:sqlite").SQLOutputValue;
+            kind: string;
+            status: string;
+            visits: number;
+            attemptId: string | null;
+        }[];
+        lease: {
+            owner: string;
+            epoch: number;
+            expiresAt: number;
+            active: boolean;
+        } | null;
+        recoverableSteps: {
+            nodePath: string;
+            scopeId: string;
+            attemptId: string;
+            status: string;
+            effect: "write";
+        }[];
+        steering: {
+            receipts: import("./steering/inbox.js").SteeringReceipt[];
+            pending: number;
+            consumed: number;
+            truncated: boolean;
+            consumptionReported: true;
+        };
+        reservations: {
+            pendingInvocations: number;
+            knownTokens: number;
+            knownCostUsd: number;
+            tokensUnknown: boolean;
+            costUnknown: boolean;
+        };
+        pendingInterrupts: {
+            id: string;
+            nodePath: string;
+            scopeId: string;
+            branchId?: string;
+            attemptId: string;
+            kind: string;
+            requestedAt: string;
+            value: JsonValue;
+            answer?: JsonValue;
+        }[];
+        recentFailures: {
+            nodePath: import("node:sqlite").SQLOutputValue;
+            scopeId: import("node:sqlite").SQLOutputValue;
+            branch: import("node:sqlite").SQLOutputValue;
+            status: import("node:sqlite").SQLOutputValue;
+            attempt: import("node:sqlite").SQLOutputValue;
+            visit: import("node:sqlite").SQLOutputValue;
+            at: import("node:sqlite").SQLOutputValue;
+            error: {
+                code: import("node:sqlite").SQLOutputValue;
+                message: string;
+            };
+        }[];
+        schemaVersion: 2;
+        runId: string;
+        traceId: string;
+        workflowId: string;
+        workflowVersion: string;
+        workflowFingerprint: string;
+        inputFingerprint: string;
+        status: import("../workflow-types.js").WorkflowStatus;
+        createdAt: string;
+        updatedAt: string;
+        nextAttempt: number;
+        transitions: number;
+        executionCount: number;
+        history: import("../workflow-types.js").StepAttemptRecord[];
+        events: import("../workflow-types.js").WorkflowEvent[];
+        budget: import("./contracts.js").WorkflowBudget;
+        usage: {
+            costUsd: number | null;
+            inputTokens: number | null;
+            outputTokens: number | null;
+            knownCostUsd: number;
+            knownTokens: number;
+            durationMs: number;
+        };
+        pendingApproval?: {
+            stepId: string;
+            requestedAt: string;
+            grantedAt?: string;
+            reason?: string;
+        };
+        pendingQuestion?: {
+            stepId: string;
+            requestedAt: string;
+            question: string;
+            answeredAt?: string;
+            answer?: string;
+        };
+        error?: string;
+    } | {
+        nextNodePath: string;
+        nextStep: string;
+        steps: {
+            [k: string]: {
+                kind: string;
+                status: string;
+                visits: number;
+            };
+        };
+        scopes: {
+            output?: unknown;
+            nodePath: string;
+            scopeId: string;
+            branch: import("node:sqlite").SQLOutputValue;
+            kind: string;
+            status: string;
+            visits: number;
+            attemptId: string | null;
+        }[];
+        lease: {
+            owner: string;
+            epoch: number;
+            expiresAt: number;
+            active: boolean;
+        } | null;
+        recoverableSteps: {
+            nodePath: string;
+            scopeId: string;
+            attemptId: string;
+            status: string;
+            effect: "write";
+        }[];
+        steering: {
+            receipts: import("./steering/inbox.js").SteeringReceipt[];
+            pending: number;
+            consumed: number;
+            truncated: boolean;
+            consumptionReported: true;
+        };
+        reservations: {
+            pendingInvocations: number;
+            knownTokens: number;
+            knownCostUsd: number;
+            tokensUnknown: boolean;
+            costUnknown: boolean;
+        };
+        pendingInterrupts: {
+            id: string;
+            nodePath: string;
+            scopeId: string;
+            branchId?: string;
+            attemptId: string;
+            kind: string;
+            requestedAt: string;
+            value: JsonValue;
+            answer?: JsonValue;
+        }[];
+        recentFailures: {
+            nodePath: import("node:sqlite").SQLOutputValue;
+            scopeId: import("node:sqlite").SQLOutputValue;
+            branch: import("node:sqlite").SQLOutputValue;
+            status: import("node:sqlite").SQLOutputValue;
+            attempt: import("node:sqlite").SQLOutputValue;
+            visit: import("node:sqlite").SQLOutputValue;
+            at: import("node:sqlite").SQLOutputValue;
+            error: {
+                code: import("node:sqlite").SQLOutputValue;
+                message: string;
+            };
+        }[];
+        pendingQuestion?: {
+            stepId: string;
+            requestedAt: string;
+            question: string;
+            answeredAt?: string;
+            answer?: string;
+        } | undefined;
+        pendingApproval?: {
+            stepId: string;
+            requestedAt: string;
+            grantedAt?: string;
+            reason?: string;
+        } | undefined;
+        runId: string;
+        traceId: string;
+        status: import("../workflow-types.js").WorkflowStatus;
+        updatedAt: string;
+        usage: {
+            costUsd: number | null;
+            inputTokens: number | null;
+            outputTokens: number | null;
+            knownCostUsd: number;
+            knownTokens: number;
+            durationMs: number;
+        };
+    };
+    workflow: {
+        id: string;
+        version: string;
+        source: string;
+    };
+    completion: any;
+}>;
+export declare function resumeRun(directory: string, options?: ResumeDefinitionOptions): Promise<{
+    metrics: import("../efficiency-types.js").RuntimeEfficiency;
+    efficiencySummary: {
+        reservations: {
+            pendingInvocations: number;
+            knownTokens: number;
+            knownCostUsd: number;
+            tokensUnknown: boolean;
+            costUnknown: boolean;
+        };
+        schemaVersion: 1;
+        currentEvidenceIds: string[];
+        planHash: string | null;
+        candidateHash: string | null;
+        runId: string;
+        workflowVersion: string;
+        technicalAcceptance: string;
+        archive: import("../../pipeline/pipeline-state.js").PhaseStatus;
+        delivery: "pending" | "complete" | "pending-host";
+        roles: {
+            role: string;
+            provider: string | null;
+            model: string | null;
+            effort: string | null;
+            observedModel: null;
+            observedEffort: null;
+            origin: string;
+            tier: "base" | "escalation";
+        }[];
+        invocations: {
+            byKind: {
+                [k: string]: number;
+            };
+            total: number;
+            complete: boolean;
+            promptBytes: number | null;
+            contextBytes: number | null;
+            handoffBytes: number | null;
+            fullContexts: number;
+            incrementalContexts: number;
+        };
+        escalations: {
+            role: string;
+            attemptId: string;
+            provider: string;
+            model: string | null;
+            effort: string | null;
+            reason: string | null;
+        }[];
+        escalationsTruncated: boolean;
+        checks: {
+            invalidated: number | null;
+            available: boolean;
+            complete: boolean;
+            executed: number | null;
+            reused: number | null;
+            notRun: number | null;
+            durationMs: number | null;
+        };
+        metrics: import("../efficiency-types.js").RuntimeEfficiency;
+    };
+    revision: number;
+    eventCursor: number;
+    forkOf?: string | undefined;
+    type: "runtime-status";
+    engineVersion: number;
+    state: {
+        nextNodePath: string;
+        nextStep: string;
+        steps: {
+            [k: string]: {
+                kind: string;
+                status: string;
+                visits: number;
+            };
+        };
+        scopes: {
+            output?: unknown;
+            nodePath: string;
+            scopeId: string;
+            branch: import("node:sqlite").SQLOutputValue;
+            kind: string;
+            status: string;
+            visits: number;
+            attemptId: string | null;
+        }[];
+        lease: {
+            owner: string;
+            epoch: number;
+            expiresAt: number;
+            active: boolean;
+        } | null;
+        recoverableSteps: {
+            nodePath: string;
+            scopeId: string;
+            attemptId: string;
+            status: string;
+            effect: "write";
+        }[];
+        steering: {
+            receipts: import("./steering/inbox.js").SteeringReceipt[];
+            pending: number;
+            consumed: number;
+            truncated: boolean;
+            consumptionReported: true;
+        };
+        reservations: {
+            pendingInvocations: number;
+            knownTokens: number;
+            knownCostUsd: number;
+            tokensUnknown: boolean;
+            costUnknown: boolean;
+        };
+        pendingInterrupts: {
+            id: string;
+            nodePath: string;
+            scopeId: string;
+            branchId?: string;
+            attemptId: string;
+            kind: string;
+            requestedAt: string;
+            value: JsonValue;
+            answer?: JsonValue;
+        }[];
+        recentFailures: {
+            nodePath: import("node:sqlite").SQLOutputValue;
+            scopeId: import("node:sqlite").SQLOutputValue;
+            branch: import("node:sqlite").SQLOutputValue;
+            status: import("node:sqlite").SQLOutputValue;
+            attempt: import("node:sqlite").SQLOutputValue;
+            visit: import("node:sqlite").SQLOutputValue;
+            at: import("node:sqlite").SQLOutputValue;
+            error: {
+                code: import("node:sqlite").SQLOutputValue;
+                message: string;
+            };
+        }[];
+        schemaVersion: 2;
+        runId: string;
+        traceId: string;
+        workflowId: string;
+        workflowVersion: string;
+        workflowFingerprint: string;
+        inputFingerprint: string;
+        status: import("../workflow-types.js").WorkflowStatus;
+        createdAt: string;
+        updatedAt: string;
+        nextAttempt: number;
+        transitions: number;
+        executionCount: number;
+        history: import("../workflow-types.js").StepAttemptRecord[];
+        events: import("../workflow-types.js").WorkflowEvent[];
+        budget: import("./contracts.js").WorkflowBudget;
+        usage: {
+            costUsd: number | null;
+            inputTokens: number | null;
+            outputTokens: number | null;
+            knownCostUsd: number;
+            knownTokens: number;
+            durationMs: number;
+        };
+        pendingApproval?: {
+            stepId: string;
+            requestedAt: string;
+            grantedAt?: string;
+            reason?: string;
+        };
+        pendingQuestion?: {
+            stepId: string;
+            requestedAt: string;
+            question: string;
+            answeredAt?: string;
+            answer?: string;
+        };
+        error?: string;
+    } | {
+        nextNodePath: string;
+        nextStep: string;
+        steps: {
+            [k: string]: {
+                kind: string;
+                status: string;
+                visits: number;
+            };
+        };
+        scopes: {
+            output?: unknown;
+            nodePath: string;
+            scopeId: string;
+            branch: import("node:sqlite").SQLOutputValue;
+            kind: string;
+            status: string;
+            visits: number;
+            attemptId: string | null;
+        }[];
+        lease: {
+            owner: string;
+            epoch: number;
+            expiresAt: number;
+            active: boolean;
+        } | null;
+        recoverableSteps: {
+            nodePath: string;
+            scopeId: string;
+            attemptId: string;
+            status: string;
+            effect: "write";
+        }[];
+        steering: {
+            receipts: import("./steering/inbox.js").SteeringReceipt[];
+            pending: number;
+            consumed: number;
+            truncated: boolean;
+            consumptionReported: true;
+        };
+        reservations: {
+            pendingInvocations: number;
+            knownTokens: number;
+            knownCostUsd: number;
+            tokensUnknown: boolean;
+            costUnknown: boolean;
+        };
+        pendingInterrupts: {
+            id: string;
+            nodePath: string;
+            scopeId: string;
+            branchId?: string;
+            attemptId: string;
+            kind: string;
+            requestedAt: string;
+            value: JsonValue;
+            answer?: JsonValue;
+        }[];
+        recentFailures: {
+            nodePath: import("node:sqlite").SQLOutputValue;
+            scopeId: import("node:sqlite").SQLOutputValue;
+            branch: import("node:sqlite").SQLOutputValue;
+            status: import("node:sqlite").SQLOutputValue;
+            attempt: import("node:sqlite").SQLOutputValue;
+            visit: import("node:sqlite").SQLOutputValue;
+            at: import("node:sqlite").SQLOutputValue;
+            error: {
+                code: import("node:sqlite").SQLOutputValue;
+                message: string;
+            };
+        }[];
+        pendingQuestion?: {
+            stepId: string;
+            requestedAt: string;
+            question: string;
+            answeredAt?: string;
+            answer?: string;
+        } | undefined;
+        pendingApproval?: {
+            stepId: string;
+            requestedAt: string;
+            grantedAt?: string;
+            reason?: string;
+        } | undefined;
+        runId: string;
+        traceId: string;
+        status: import("../workflow-types.js").WorkflowStatus;
+        updatedAt: string;
+        usage: {
+            costUsd: number | null;
+            inputTokens: number | null;
+            outputTokens: number | null;
+            knownCostUsd: number;
+            knownTokens: number;
+            durationMs: number;
+        };
+    };
+    workflow: {
+        id: string;
+        version: string;
+        source: string;
+    };
+    completion: any;
+}>;
+export declare function signalRun(directory: string, text: string, requestId?: string): Promise<import("./steering/inbox.js").SteeringMessage>;
+export declare function cancelRun(directory: string, requestId?: string): Promise<{
+    requestId: string;
+    createdAt: string;
+}>;