specrails-core 5.3.0 → 5.4.0

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

@@ -0,0 +1,19 @@
+import type { AgentRole } from './executor-types.js';
+import type { RepositoryContextSnapshot } from './repository-context.js';
+export interface RoleSession {
+    identity: string;
+    sessionId: string;
+    context: RepositoryContextSnapshot;
+}
+export interface RoleExecutionState {
+    sessions: Partial<Record<AgentRole, RoleSession>>;
+    routes: Partial<Record<AgentRole, {
+        tier: 'base' | 'escalation';
+        reason: string;
+        attemptId: string;
+    }>>;
+}
+/** Host-owned auxiliary state lives under the workflow's existing run lease.
+ * A corrupted packet fails explicitly; it is never used as missing context. */
+export declare function readRoleState(directory: string): RoleExecutionState;
+export declare function writeRoleState(directory: string, data: RoleExecutionState): void;

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

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fingerprint } from './durable-store.js';
+import { write } from './graph/artifacts.js';
+/** Host-owned auxiliary state lives under the workflow's existing run lease.
+ * A corrupted packet fails explicitly; it is never used as missing context. */
+export function readRoleState(directory) {
+    const file = path.join(directory, 'role-execution.json');
+    if (!existsSync(file))
+        return { sessions: {}, routes: {} };
+    if (statSync(file).size > 2 * 1024 * 1024)
+        throw new Error('Role execution state exceeds its size limit');
+    const envelope = JSON.parse(readFileSync(file, 'utf8'));
+    if (envelope.schemaVersion !== 1 || envelope.checksum !== fingerprint(envelope.data) || !envelope.data?.sessions || !envelope.data?.routes)
+        throw new Error('Role execution state failed its integrity check');
+    return envelope.data;
+}
+export function writeRoleState(directory, data) {
+    const content = JSON.stringify({ schemaVersion: 1, checksum: fingerprint(data), data }) + '\n';
+    if (Buffer.byteLength(content) > 2 * 1024 * 1024)
+        throw new Error('Role execution state exceeds its size limit');
+    write(path.join(directory, 'role-execution.json'), content);
+}
+//# sourceMappingURL=role-state.js.map

package/dist/agent-runtime/role-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-state.js","sourceRoot":"","sources":["../../src/agent-runtime/role-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAC5D,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAA;AAa5C;+EAC+E;AAC/E,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,qBAAqB,CAAC,CAAA;IACxD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAA;IAC1D,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;IACzG,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAA;IACvD,IAAI,QAAQ,CAAC,aAAa,KAAK,CAAC,IAAI,QAAQ,CAAC,QAAQ,KAAK,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAA;IAC9M,OAAO,QAAQ,CAAC,IAA0B,CAAA;AAC5C,CAAC;AACD,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,IAAwB;IACxE,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IAC9F,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;IAChH,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,qBAAqB,CAAC,EAAE,OAAO,CAAC,CAAA;AAC7D,CAAC"}

package/dist/agent-runtime/runtime-identity.d.ts

@@ -0,0 +1,11 @@
+export interface RuntimeIdentity {
+    packageVersion: string;
+    workflowVersion: string;
+    instructionsVersion: string;
+    packageIntegrity: string;
+    apiVersion: 1;
+}
+/** Hash the executable package, not a mutable path or its advertised version.
+ * Dependencies are retained/verified by the host package snapshot separately. */
+export declare function runtimePackageIntegrity(root?: string): string;
+export declare function sameRuntimeIdentity(left: RuntimeIdentity, right: RuntimeIdentity): boolean;

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

@@ -0,0 +1,33 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Hash the executable package, not a mutable path or its advertised version.
+ * Dependencies are retained/verified by the host package snapshot separately. */
+export function runtimePackageIntegrity(root = fileURLToPath(new URL('../../', import.meta.url))) {
+    const hash = createHash('sha256');
+    const visit = (relative) => {
+        const file = path.join(root, relative);
+        const stat = lstatSync(file);
+        if (stat.isSymbolicLink())
+            throw new Error('Runtime package contains an unsupported symbolic link: ' + relative);
+        if (stat.isDirectory()) {
+            for (const name of readdirSync(file).sort())
+                visit(path.posix.join(relative, name));
+        }
+        else if (stat.isFile()) {
+            hash.update(JSON.stringify([relative, stat.size])).update('\0').update(readFileSync(file)).update('\0');
+        }
+        else
+            throw new Error('Runtime package contains a nonregular file: ' + relative);
+    };
+    for (const entry of ['package.json', 'dist', 'bin', 'templates', 'schemas', 'commands', 'integration-contract.json', 'pinned-versions.json']) {
+        if (existsSync(path.join(root, entry)))
+            visit(entry);
+    }
+    return 'sha256:' + hash.digest('hex');
+}
+export function sameRuntimeIdentity(left, right) {
+    return ['packageVersion', 'workflowVersion', 'instructionsVersion', 'packageIntegrity', 'apiVersion'].every(key => left[key] === right[key]);
+}
+//# sourceMappingURL=runtime-identity.js.map

package/dist/agent-runtime/runtime-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-identity.js","sourceRoot":"","sources":["../../src/agent-runtime/runtime-identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC1E,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AASxC;iFACiF;AACjF,MAAM,UAAU,uBAAuB,CAAC,IAAI,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9F,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAA;IACjC,MAAM,KAAK,GAAG,CAAC,QAAgB,EAAQ,EAAE;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;QACtC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;QAC5B,IAAI,IAAI,CAAC,cAAc,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,yDAAyD,GAAG,QAAQ,CAAC,CAAA;QAChH,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACvB,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE;gBAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAA;QACrF,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACzG,CAAC;;YAAM,MAAM,IAAI,KAAK,CAAC,8CAA8C,GAAG,QAAQ,CAAC,CAAA;IACnF,CAAC,CAAA;IACD,KAAK,MAAM,KAAK,IAAI,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,2BAA2B,EAAE,sBAAsB,CAAC,EAAE,CAAC;QAC7I,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,KAAK,CAAC,KAAK,CAAC,CAAA;IACtD,CAAC;IACD,OAAO,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AACvC,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAqB,EAAE,KAAsB;IAC/E,OAAO,CAAC,gBAAgB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,YAAY,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,GAA4B,CAAC,KAAK,KAAK,CAAC,GAA4B,CAAC,CAAC,CAAA;AAChM,CAAC"}

package/dist/agent-runtime/tool-event.d.ts

@@ -0,0 +1,3 @@
+import type { AgentEvent } from './executor-types.js';
+/** Short, human-readable tool activity for host logs; never a transcript. */
+export declare function toolEvent(tool: string, input: unknown): AgentEvent;

package/dist/agent-runtime/tool-event.js

@@ -0,0 +1,24 @@
+function object(value) { return value && typeof value === 'object' && !Array.isArray(value) ? value : {}; }
+function shorten(value, limit = 160) {
+    if (typeof value !== 'string' || !value.trim())
+        return undefined;
+    const single = value.replace(/\s+/g, ' ').trim();
+    return single.length > limit ? single.slice(0, limit - 1) + '…' : single;
+}
+/** Short, human-readable tool activity for host logs; never a transcript. */
+export function toolEvent(tool, input) {
+    if (typeof input === 'string') {
+        try {
+            input = JSON.parse(input);
+        }
+        catch {
+            input = {};
+        }
+    }
+    const args = object(input);
+    const detail = shorten(args.file_path ?? args.path ?? (Array.isArray(args.paths) ? args.paths[0] : undefined) ?? args.command ?? args.pattern ?? args.query ?? args.notebook_path ?? args.url ?? (typeof args.action === 'string' ? [args.action, args.artifact].filter(Boolean).join(' ') : undefined));
+    const targetPaths = [args.file_path, args.path, args.notebook_path, ...(Array.isArray(args.paths) ? args.paths : [])].filter((value) => typeof value === 'string' && value.length > 0);
+    const cwd = args.workdir ?? args.cwd;
+    return { kind: 'tool-start', tool, ...(detail ? { detail } : {}), ...(targetPaths.length ? { targetPaths } : {}), ...(typeof cwd === 'string' ? { cwd } : {}) };
+}
+//# sourceMappingURL=tool-event.js.map

package/dist/agent-runtime/tool-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-event.js","sourceRoot":"","sources":["../../src/agent-runtime/tool-event.ts"],"names":[],"mappings":"AACA,SAAS,MAAM,CAAC,KAAc,IAA6B,OAAO,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAgC,CAAC,CAAC,CAAC,EAAE,CAAA,CAAC,CAAC;AACvK,SAAS,OAAO,CAAC,KAAc,EAAE,KAAK,GAAG,GAAG;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE;QAAE,OAAO,SAAS,CAAA;IAChE,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAA;IAChD,OAAO,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,MAAM,CAAA;AAC1E,CAAC;AACD,6EAA6E;AAC7E,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAc;IACpD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAAC,IAAI,CAAC;YAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,KAAK,GAAG,EAAE,CAAA;QAAC,CAAC;IAAC,CAAC;IACzF,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;IACxS,MAAM,WAAW,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IACvM,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,GAAG,CAAA;IACpC,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;AACjK,CAAC"}

package/dist/agent-runtime/verification-plan.d.ts

@@ -0,0 +1,55 @@
+import { type PipelineContext, type VerificationCommand } from '../installer/runtime/pipeline-state.js';
+export interface ProposedCheck {
+    kind: 'command' | 'harness';
+    key: string;
+    repositoryId: string;
+    label: string;
+    command: string;
+    args: string[];
+    cwd?: string;
+    timeoutMs?: number;
+    entrypoint?: string;
+    files?: Array<{
+        path: string;
+        content: string;
+    }>;
+}
+export interface HarnessSource {
+    path: string;
+    hash: string;
+    byteCount: number;
+}
+export interface PlanEntry {
+    id: string;
+    key: string;
+    label: string;
+    origins: Array<'host' | 'architect' | 'developer'>;
+    command: VerificationCommand;
+    harness?: {
+        hash: string;
+        entrypoint: string;
+        sources: HarnessSource[];
+    };
+}
+export interface VerificationPlan {
+    schemaVersion: 1;
+    runId: string;
+    revision: number;
+    planHash: string;
+    integrity: string;
+    scopeHash: string;
+    executionPolicy: {
+        maxConcurrency: number;
+    };
+    baseline: PlanEntry[];
+    developer: PlanEntry[];
+    entries: PlanEntry[];
+}
+/** All declarations are validated before any source is materialized. */
+export declare function validateProposedChecks(context: PipelineContext, raw: unknown): ProposedCheck[];
+export declare function readVerificationPlan(context: PipelineContext): VerificationPlan | null;
+export declare function initializeVerificationPlan(context: PipelineContext, host: VerificationCommand[], architect: VerificationCommand[], maxConcurrency?: number): VerificationPlan;
+export declare function addDeveloperChecks(context: PipelineContext, proposals: ProposedCheck[]): VerificationPlan;
+export declare function expandedPlanCommands(context: PipelineContext, plan: VerificationPlan): VerificationCommand[];
+/** Bind the exact manifest and every source to lifecycle gates. */
+export declare function bindPlan(context: PipelineContext, plan: VerificationPlan): void;

package/dist/agent-runtime/verification-plan.js

@@ -0,0 +1,206 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { bindVerificationPlan, pipelineStateDirectory, validateVerificationRequest } from '../installer/runtime/pipeline-state.js';
+import { fingerprint } from './durable-store.js';
+import { child, write } from './graph/artifacts.js';
+const SAFE_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+const bytesHash = (text) => createHash('sha256').update(text).digest('hex');
+function text(value, field, limit) {
+    if (typeof value !== 'string' || !value.trim() || value.includes('\0') || value.length > limit)
+        throw new Error('Invalid verification proposal ' + field);
+    return value;
+}
+function sourcePath(value) {
+    const file = text(value, 'file path', 1024);
+    if (/^[a-z]:/i.test(file) || path.isAbsolute(file) || file.includes('\\') || /[\x00-\x1f\x7f]/.test(file) || file.split('/').some(part => !part || part === '.' || part === '..' || /[. ]$/.test(part) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part)))
+        throw new Error('Invalid verification proposal file path');
+    return file;
+}
+/** All declarations are validated before any source is materialized. */
+export function validateProposedChecks(context, raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw) || raw.length > 20)
+        throw new Error('Invalid verificationChecks: expected at most 20 checks');
+    let bytes = 0;
+    const keys = new Set();
+    return raw.map(value => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error('Invalid verification proposal');
+        const check = value;
+        for (const key of Object.keys(check))
+            if (!['kind', 'key', 'repositoryId', 'label', 'command', 'args', 'cwd', 'timeoutMs', 'entrypoint', 'files'].includes(key))
+                throw new Error('Invalid verification proposal field: ' + key);
+        if (!['command', 'harness'].includes(String(check.kind)) || typeof check.key !== 'string' || !SAFE_ID.test(check.key) || keys.has(check.key))
+            throw new Error('Invalid or duplicate verification proposal key/kind');
+        keys.add(check.key);
+        text(check.label, 'label', 256);
+        text(check.command, 'command', 4096);
+        if (!Array.isArray(check.args) || check.args.length > 128 || check.args.some(arg => typeof arg !== 'string' || arg.includes('\0') || arg.length > 4096))
+            throw new Error('Invalid verification proposal args');
+        validateVerificationRequest(context, { kind: 'scoped', commands: [check] });
+        if (check.kind === 'command') {
+            if (check.entrypoint !== undefined || check.files !== undefined)
+                throw new Error('Invalid command proposal: harness fields are forbidden');
+        }
+        else {
+            const entrypoint = sourcePath(check.entrypoint);
+            if (!Array.isArray(check.files) || !check.files.length || check.files.length > 8)
+                throw new Error('Invalid harness files: expected 1–8 files');
+            const paths = new Set();
+            for (const raw of check.files) {
+                if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                    throw new Error('Invalid harness source');
+                const file = raw;
+                if (Object.keys(file).some(key => !['path', 'content'].includes(key)))
+                    throw new Error('Invalid harness source fields');
+                const filePath = sourcePath(file.path);
+                if ([...paths].some(prior => prior === filePath.toLowerCase() || prior.startsWith(filePath.toLowerCase() + '/') || filePath.toLowerCase().startsWith(prior + '/')))
+                    throw new Error('Duplicate harness source path');
+                paths.add(filePath.toLowerCase());
+                if (typeof file.content !== 'string')
+                    throw new Error('Invalid harness source content');
+                const length = Buffer.byteLength(file.content);
+                if (length > 64 * 1024 || (bytes += length) > 256 * 1024)
+                    throw new Error('Invalid harness source size');
+            }
+            if (!check.files.some(file => file.path === entrypoint))
+                throw new Error('Invalid harness entrypoint: source is missing');
+        }
+        return structuredClone(check);
+    });
+}
+function normalized(command) {
+    return JSON.parse(JSON.stringify({ ...command, args: [...command.args], cwd: command.cwd ?? '.', timeoutMs: command.timeoutMs ?? 15 * 60_000 }));
+}
+function entry(key, label, command, origin, harness) {
+    const definition = normalized(command);
+    delete definition.key;
+    delete definition.label;
+    return { key, label, command: definition, origins: [origin], ...(harness ? { harness } : {}), id: fingerprint({ key, command: definition, harness: harness ?? null }) };
+}
+function mergePolicy(left, right) {
+    return {
+        reuse: left?.reuse === 'snapshot-local' && right?.reuse === 'snapshot-local' ? 'snapshot-local' : 'never',
+        deterministic: left?.deterministic === true && right?.deterministic === true,
+        readOnly: left?.readOnly === true && right?.readOnly === true,
+        inputs: [...new Set([...(left?.inputs ?? []), ...(right?.inputs ?? [])])].sort(),
+        toolchainInputs: [...new Set([...(left?.toolchainInputs ?? []), ...(right?.toolchainInputs ?? [])])].sort(),
+        ...(left?.independentGroup && left.independentGroup === right?.independentGroup && left.resources && right.resources ? { independentGroup: left.independentGroup, resources: [...new Set([...left.resources, ...right.resources])].sort() } : {}),
+    };
+}
+function coalesce(entries) {
+    const results = new Map();
+    for (const item of entries) {
+        const { policy: _policy, ...command } = item.command;
+        const semantic = fingerprint({ command, harness: item.harness ?? null });
+        const old = results.get(semantic);
+        if (!old) {
+            results.set(semantic, structuredClone(item));
+            continue;
+        }
+        if (item.origins.some(origin => origin !== 'developer'))
+            old.command.policy = mergePolicy(old.command.policy, item.command.policy);
+        old.origins = [...new Set([...old.origins, ...item.origins])];
+    }
+    return [...results.values()];
+}
+function planFile(context) { return child(pipelineStateDirectory(context), 'verification/plan.json'); }
+export function readVerificationPlan(context) {
+    const file = planFile(context);
+    if (!existsSync(file))
+        return null;
+    if (statSync(file).size > 2 * 1024 * 1024)
+        throw new Error('Verification plan exceeds its size limit');
+    const value = JSON.parse(readFileSync(file, 'utf8'));
+    const { integrity, ...payload } = value;
+    if (integrity !== fingerprint(payload))
+        throw new Error('Verification plan failed its integrity check');
+    if (value.scopeHash !== fingerprint(context) || value.schemaVersion !== 1 || value.runId !== context.runId || !Array.isArray(value.baseline) || !Array.isArray(value.developer) || !Array.isArray(value.entries) || value.entries.length > 100 || value.planHash !== fingerprint({ policyVersion: 1, scopeHash: value.scopeHash, executionPolicy: value.executionPolicy, entries: value.entries }))
+        throw new Error('Verification plan failed its integrity check');
+    return value;
+}
+export function initializeVerificationPlan(context, host, architect, maxConcurrency = 1) {
+    const previous = readVerificationPlan(context);
+    const baseline = [['host', host], ['architect', architect]].flatMap(([origin, commands]) => commands.map((command, i) => entry(`${origin}:${command.key ?? `${i}-${fingerprint(normalized(command)).slice(0, 12)}`}`, command.label ?? [command.command, ...command.args].join(' ').slice(0, 256), command, origin)));
+    if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4)
+        throw new Error('Invalid verification concurrency');
+    if (previous && fingerprint(previous.baseline) !== fingerprint(baseline))
+        throw new Error('Verification baseline is immutable');
+    return savePlan(context, baseline, previous?.developer ?? [], previous, { maxConcurrency });
+}
+function buildPlan(context, baseline, developer, previous, executionPolicy = previous?.executionPolicy ?? { maxConcurrency: 1 }) {
+    const entries = coalesce([...baseline, ...developer]);
+    if (entries.length > 100)
+        throw new Error('Invalid verification plan: maximum 100 effective checks');
+    const scopeHash = fingerprint(context);
+    const planHash = fingerprint({ policyVersion: 1, scopeHash, executionPolicy, entries });
+    const payload = { schemaVersion: 1, runId: context.runId, revision: (previous?.revision ?? 0) + (previous?.planHash === planHash ? 0 : 1), planHash, scopeHash, executionPolicy, baseline, developer, entries };
+    const plan = { ...payload, integrity: fingerprint(payload) };
+    const serialized = JSON.stringify(plan) + '\n';
+    if (Buffer.byteLength(serialized) > 2 * 1024 * 1024)
+        throw new Error('Verification plan exceeds 2 MiB');
+    return plan;
+}
+function savePlan(context, baseline, developer, previous, executionPolicy = previous?.executionPolicy ?? { maxConcurrency: 1 }) {
+    const plan = buildPlan(context, baseline, developer, previous, executionPolicy);
+    write(planFile(context), JSON.stringify(plan) + '\n');
+    return plan;
+}
+export function addDeveloperChecks(context, proposals) {
+    const previous = readVerificationPlan(context);
+    if (!previous)
+        throw new Error('Verification baseline is unavailable');
+    const checked = validateProposedChecks(context, proposals);
+    const developer = new Map(previous.developer.map(item => [item.key, item]));
+    const sources = [];
+    for (const check of checked) {
+        const command = { repositoryId: check.repositoryId, command: check.command, args: check.args, ...(check.cwd === undefined ? {} : { cwd: check.cwd }), ...(check.timeoutMs === undefined ? {} : { timeoutMs: check.timeoutMs }) };
+        const files = check.files?.slice().sort((a, b) => a.path.localeCompare(b.path)).map(file => ({ path: file.path, hash: bytesHash(file.content), byteCount: Buffer.byteLength(file.content) }));
+        const harness = files ? { hash: fingerprint(files), entrypoint: check.entrypoint, sources: files } : undefined;
+        const item = entry('dev:' + check.key, check.label, command, 'developer', harness);
+        developer.set(item.key, item);
+        for (const file of check.files ?? [])
+            sources.push({ file: child(pipelineStateDirectory(context), `verification/harnesses/${item.id}/${harness.hash}/${file.path}`), content: file.content });
+    }
+    const plan = buildPlan(context, previous.baseline, [...developer.values()], previous);
+    // An interrupted write cannot activate a partial harness. Old immutable
+    // revisions remain readable; only the new manifest changes the active plan.
+    for (const source of sources) {
+        if (existsSync(source.file) && readFileSync(source.file, 'utf8') !== source.content)
+            throw new Error('Immutable verification source changed');
+    }
+    for (const source of sources) {
+        if (!existsSync(source.file))
+            write(source.file, source.content);
+    }
+    write(planFile(context), JSON.stringify(plan) + '\n');
+    return plan;
+}
+export function expandedPlanCommands(context, plan) {
+    return plan.entries.map(item => {
+        if (!item.harness)
+            return { ...item.command, key: item.id, label: item.label };
+        const repository = context.repositories.find(repo => repo.id === item.command.repositoryId);
+        if (!repository)
+            throw new Error('Harness repository is no longer admitted');
+        for (const source of item.harness.sources) {
+            const file = child(pipelineStateDirectory(context), `verification/harnesses/${item.id}/${item.harness.hash}/${source.path}`);
+            if (bytesHash(readFileSync(file, 'utf8')) !== source.hash)
+                throw new Error('Verification harness source changed');
+        }
+        const entrypoint = child(pipelineStateDirectory(context), `verification/harnesses/${item.id}/${item.harness.hash}/${item.harness.entrypoint}`);
+        return { ...item.command, key: item.id, label: item.label, args: [...item.command.args, entrypoint], env: { SPECRAILS_CHECK_REPO_ROOT: repository.path } };
+    });
+}
+/** Bind the exact manifest and every source to lifecycle gates. */
+export function bindPlan(context, plan) {
+    const files = [{ path: 'verification/plan.json', hash: bytesHash(readFileSync(planFile(context), 'utf8')) }];
+    for (const item of plan.entries)
+        for (const source of item.harness?.sources ?? []) {
+            files.push({ path: `verification/harnesses/${item.id}/${item.harness.hash}/${source.path}`, hash: source.hash });
+        }
+    bindVerificationPlan(context, plan.planHash, files);
+}
+//# sourceMappingURL=verification-plan.js.map

package/dist/agent-runtime/verification-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-plan.js","sourceRoot":"","sources":["../../src/agent-runtime/verification-plan.ts"],"names":[],"mappings":"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"}

package/dist/agent-runtime/workflow-types.d.ts

@@ -1,4 +1,5 @@
 import type { AnnotationRoot } from '@langchain/langgraph';
+import type { ProviderInvocation } from './efficiency-types.js';
 /** JSON-only contracts keep checkpoints portable and independent of executors. */
 export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
@@ -62,10 +63,18 @@ export interface WorkflowStepContext {
     interrupt<R extends InterruptResume = InterruptResume>(request: InterruptRequest): R;
     /** Account provider spend as soon as it is known; a later pause or failure keeps it. */
     reportUsage(usage: StepUsage): void;
+    /** Persist a completed provider call with its already-reported usage. Optional for custom hosts. */
+    reportEfficiencyActivity?(kind: string, payload: Record<string, string | number | null>): Promise<void>;
+    reportInvocationStarted?(invocation: Omit<import('./efficiency-types.js').PendingProviderInvocation, 'invocationId' | 'ordinal'>): Promise<{
+        invocationId: string;
+        ordinal: number;
+    }>;
+    reportInvocation?(invocation: ProviderInvocation): Promise<void>;
     /** Budget left for the next provider call, after everything reported so far. */
     remainingBudget(): {
         maxTokens?: number;
         maxCostUsd?: number;
+        maxDurationMs?: number;
     };
 }
 export interface WorkflowNode<S extends Record<string, unknown>> {
@@ -115,6 +124,8 @@ export interface StepAttemptRecord {
     output?: JsonValue;
     error?: string;
     usage?: StepUsage;
+    pendingInvocations?: import('./efficiency-types.js').PendingProviderInvocation[];
+    invocations?: ProviderInvocation[];
 }
 export interface WorkflowEvent {
     id: string;
@@ -123,7 +134,12 @@ export interface WorkflowEvent {
     /** Trace correlation: the run's trace and the attempt span this event belongs to. */
     traceId: string;
     spanId?: string;
-    type: 'workflow_started' | 'workflow_resumed' | 'workflow_invalidated' | 'workflow_succeeded' | 'workflow_failed' | 'workflow_blocked' | 'workflow_paused' | 'workflow_cancelled' | 'step_started' | 'step_succeeded' | 'step_failed' | 'step_blocked' | 'step_paused' | 'step_interrupted';
+    efficiencyActivity?: {
+        kind: string;
+        payload: Record<string, string | number | null>;
+    };
+    efficiency?: ProviderInvocation;
+    type: 'efficiency_updated' | 'workflow_started' | 'workflow_resumed' | 'workflow_invalidated' | 'workflow_succeeded' | 'workflow_failed' | 'workflow_blocked' | 'workflow_paused' | 'workflow_cancelled' | 'step_started' | 'step_succeeded' | 'step_failed' | 'step_blocked' | 'step_paused' | 'step_interrupted';
     timestamp: string;
     stepId?: string;
     attemptId?: string;

package/dist/agent-runtime/workflow.js

@@ -271,7 +271,12 @@ export async function runWorkflow(options) {
         }
         let forkTarget;
         if (invalid.size) {
-            const first = Math.min(...Array.from(invalid, id => ids.indexOf(id)));
+            let first = Math.min(...Array.from(invalid, id => ids.indexOf(id)));
+            // A stale later receipt must never jump over an unfinished correction.
+            // This also repairs checkpoints whose previous resume chose that receipt.
+            const unfinished = ids.findIndex((id, index) => index < first && ['blocked', 'failed'].includes(state.steps[id].status));
+            if (unfinished >= 0)
+                first = unfinished;
             for (const id of ids.slice(first))
                 resetRecord(state, id);
             forkTarget = ids[first];
@@ -391,7 +396,29 @@ export async function runWorkflow(options) {
                         return interrupt(request);
                     },
                     reportUsage: usage => { validateUsage(usage); accountUsage(state, usage); reported = addUsage(reported ?? { costUsd: 0, inputTokens: 0, outputTokens: 0 }, usage); },
+                    reportEfficiencyActivity: async (kind, payload) => { await commit({ type: 'efficiency_updated', stepId: id, attemptId, efficiencyActivity: { kind, payload } }); },
+                    reportInvocationStarted: async (invocation) => {
+                        const ordinal = (history.invocations?.length ?? 0) + (history.pendingInvocations?.length ?? 0) + 1;
+                        const identity = { invocationId: `${attemptId}:call:${ordinal}`, ordinal };
+                        (history.pendingInvocations ??= []).push({ ...clone(invocation), ...identity });
+                        await persist();
+                        return identity;
+                    },
+                    reportInvocation: async (invocation) => {
+                        validateUsage(invocation.usage);
+                        if (!Number.isFinite(invocation.durationMs) || invocation.durationMs < 0 || !Number.isSafeInteger(invocation.toolCalls) || invocation.toolCalls < 0)
+                            throw new TypeError('Invalid invocation measurement');
+                        if (invocation.invocationId && history.invocations?.some(item => item.invocationId === invocation.invocationId))
+                            return;
+                        (history.invocations ??= []).push(clone(invocation));
+                        if (invocation.invocationId)
+                            history.pendingInvocations = history.pendingInvocations?.filter(item => item.invocationId !== invocation.invocationId);
+                        if (reported)
+                            history.usage = reported;
+                        await commit({ type: 'efficiency_updated', stepId: id, attemptId, efficiency: clone(invocation) });
+                    },
                     remainingBudget: () => ({
+                        ...(state.budget.maxDurationMs === undefined ? {} : { maxDurationMs: Math.max(0, state.budget.maxDurationMs - state.usage.durationMs - (performance.now() - elapsedMark)) }),
                         ...(state.budget.maxTokens === undefined ? {} : { maxTokens: Math.max(0, state.budget.maxTokens - state.usage.knownTokens) }),
                         ...(state.budget.maxCostUsd === undefined ? {} : { maxCostUsd: Math.max(0, state.budget.maxCostUsd - state.usage.knownCostUsd) }),
                     }),