specrails-core 6.0.1 → 6.1.0

package/dist/agent-runtime/engine/run-status.d.ts

@@ -0,0 +1,563 @@
+import { RunDatabase } from './checkpoint/database.js';
+import { RunLedger } from './checkpoint/ledger.js';
+/** An observer has no valid execution token; every attempted mutation remains fenced. */
+export declare function observeLedger(database: RunDatabase): RunLedger;
+export declare function projectRunStatus(ledger: RunLedger, compact?: boolean): {
+    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: import("./contracts.js").JsonValue;
+            answer?: import("./contracts.js").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: import("./contracts.js").JsonValue;
+            answer?: import("./contracts.js").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;
+};
+/** Status never fingerprints a repository, changes ACLs or acquires an execution lease. */
+export declare function statusRun(directory: string, compact?: boolean): 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: import("./contracts.js").JsonValue;
+            answer?: import("./contracts.js").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: import("./contracts.js").JsonValue;
+            answer?: import("./contracts.js").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;
+}>;

package/dist/agent-runtime/engine/run-status.js

@@ -0,0 +1,61 @@
+import { RunDatabase } from './checkpoint/database.js';
+import { RunLedger } from './checkpoint/ledger.js';
+import { EngineError } from './contracts.js';
+import { ledgerWorkflowState } from './invocation-context.js';
+import { runtimeEfficiency } from '../efficiency.js';
+import path from 'node:path';
+import { definitionEfficiencySummary } from './efficiency-summary.js';
+import { ControlInbox } from './steering/inbox.js';
+/** An observer has no valid execution token; every attempted mutation remains fenced. */
+export function observeLedger(database) {
+    const row = database.sqlite.prepare('SELECT run_id,definition_json FROM runs').get();
+    if (!row)
+        throw new EngineError('run_not_found', 'Run does not exist');
+    const definition = JSON.parse(String(row.definition_json));
+    return new RunLedger(database, { runId: String(row.run_id), owner: 'read-only-observer', epoch: -1, expiresAt: 0 }, { maxTransitions: definition.maxTransitions });
+}
+export function projectRunStatus(ledger, compact = true) {
+    const row = ledger.run(), definition = JSON.parse(String(row.definition_json));
+    const base = ledgerWorkflowState(ledger, definition, '*'), pending = ledger.pendingInterrupts();
+    const steps = ledger.db.sqlite.prepare(`SELECT s.*, a.output_json, a.terminal_digest FROM steps s
+    LEFT JOIN attempts a ON a.attempt_id=s.last_attempt_id AND a.run_id=s.run_id
+    WHERE s.run_id=? ORDER BY s.node_path,s.scope_id`).all(ledger.runId);
+    const failures = ledger.db.sqlite.prepare("SELECT node_path,scope_id,branch,status,attempt,visit,ended_at,error_code,error_message FROM attempts WHERE run_id=? AND status IN ('failed','interrupted','blocked') ORDER BY started_at DESC LIMIT 8").all(ledger.runId);
+    const lease = ledger.lease.current();
+    const recoverable = ledger.db.sqlite.prepare("SELECT a.node_path,a.scope_id,a.attempt_id,a.status,v.effect 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.terminal_digest IS NULL AND a.status IN ('running','interrupted') AND v.effect='write'").all(ledger.runId);
+    const next = pending[0]?.nodePath ?? (row.status === 'succeeded' || row.status === 'cancelled' ? null : base.nextStep);
+    const state = { ...(compact ? { runId: base.runId, traceId: base.traceId, status: base.status, updatedAt: base.updatedAt, usage: base.usage,
+            ...(base.pendingApproval ? { pendingApproval: base.pendingApproval } : {}), ...(base.pendingQuestion ? { pendingQuestion: base.pendingQuestion } : {}) } : base),
+        nextNodePath: next, nextStep: next,
+        steps: Object.fromEntries(steps.map(step => [String(step.node_path), { kind: String(step.kind), status: String(step.status), visits: Number(step.visits) }])),
+        scopes: steps.map(step => {
+            // Read only the current committed attempt. A previous successful visit is
+            // not evidence for a later pending/failed visit of the same node.
+            const result = !compact && step.terminal_digest && step.output_json
+                ? JSON.parse(String(step.output_json)) : undefined;
+            return { nodePath: String(step.node_path), scopeId: String(step.scope_id), branch: step.branch_id,
+                kind: String(step.kind), status: String(step.status), visits: Number(step.visits),
+                attemptId: step.last_attempt_id === null ? null : String(step.last_attempt_id),
+                ...(result && Object.hasOwn(result, 'output') ? { output: result.output } : {}) };
+        }),
+        lease: lease ? { owner: lease.owner, epoch: lease.epoch, expiresAt: lease.expiresAt, active: lease.expiresAt > Date.now() } : null,
+        recoverableSteps: recoverable.map(value => ({ nodePath: String(value.node_path), scopeId: String(value.scope_id), attemptId: String(value.attempt_id), status: String(value.status), effect: 'write' })),
+        steering: new ControlInbox(ledger.db, ledger.runId).status(),
+        reservations: ledger.reservationStatus(), pendingInterrupts: pending, recentFailures: failures.map(failure => ({ nodePath: failure.node_path, scopeId: failure.scope_id, branch: failure.branch,
+            status: failure.status, attempt: failure.attempt, visit: failure.visit, at: failure.ended_at, error: { code: failure.error_code, message: String(failure.error_message ?? '').slice(-6000) } })), };
+    return { type: 'runtime-status', engineVersion: 2, state,
+        workflow: { id: definition.id, version: definition.version, source: String(row.source) },
+        completion: row.completion_json ? JSON.parse(String(row.completion_json)) : null,
+        ...(row.fork_of ? { forkOf: String(row.fork_of) } : {}),
+        metrics: runtimeEfficiency(base), efficiencySummary: definitionEfficiencySummary(ledger, base), revision: ledger.db.revision, eventCursor: Number(row.next_event_sequence) - 1, };
+}
+/** Status never fingerprints a repository, changes ACLs or acquires an execution lease. */
+export async function statusRun(directory, compact = true) {
+    const database = await RunDatabase.open(path.join(directory, 'run.sqlite'), { readOnly: true });
+    try {
+        return projectRunStatus(observeLedger(database), compact);
+    }
+    finally {
+        database.close();
+    }
+}