specrails-core 6.0.0 → 6.1.0

package/dist/agent-runtime/engine/pieces/prompt.js

@@ -0,0 +1,130 @@
+import { performance } from 'node:perf_hooks';
+import { AgentExecutionError, unknownUsage } from '../../executor-types.js';
+import { ROLE_INSTRUCTIONS_VERSION } from '../../prompts.js';
+import { contentDigest } from '../canonical-json.js';
+import { EngineError } from '../contracts.js';
+import { answerEntry, boundedText, captures, captureSchema, historyEntry, json, paramsSchema, invocationTimers, stringSchema, text } from './shared.js';
+const sessionFailures = new Set(['session_not_found', 'session_expired', 'session_unsupported']);
+const engineSchema = paramsSchema({ provider: { type: 'string', minLength: 1, maxLength: 128 }, model: { type: 'string', minLength: 1, maxLength: 256 }, effort: { type: 'string', minLength: 1, maxLength: 64 }, thinking: { enum: ['on', 'off'] } }, ['provider']);
+const promptSchema = {
+    ...paramsSchema({ engine: engineSchema, text: { ...stringSchema, minLength: 1 }, nativeCommand: paramsSchema({ id: { type: 'string', pattern: '^[a-z][a-z0-9:_-]{0,63}$' }, args: stringSchema }, ['id']),
+        access: { enum: ['read', 'write'] }, sentinel: { enum: ['verification', 'blocked', 'none'] }, captureVars: captureSchema,
+        sessionContinuity: { enum: ['run', 'none'] }, ...invocationTimers, appendHistory: { type: 'boolean' }, appendSteering: { type: 'boolean' },
+    }, ['engine', 'access']),
+    oneOf: [{ properties: { text: true }, required: ['text'] }, { properties: { nativeCommand: true }, required: ['nativeCommand'] }],
+};
+export function verificationSentinel(output) {
+    const values = [...output.matchAll(/\bVERIFICATION:\s*(PASS|FAIL)\b/gi)];
+    return values.length ? values[values.length - 1][1].toLowerCase() : undefined;
+}
+/** Free turns share accounting and executor protections, without adding role instructions. */
+export function promptPiece(bindings) {
+    return {
+        descriptor: { kind: 'prompt', paramsSchema: promptSchema, outcomes: ['next', 'pass', 'fail', 'blocked', 'failed'], effect: 'derived', requiresAI: true },
+        getEffect: params => params.access === 'write' ? 'write' : 'read',
+        getOutcomes: params => params.sentinel === 'verification' ? ['pass', 'fail', 'failed'] : params.sentinel === 'blocked' ? ['next', 'blocked', 'failed'] : ['next', 'failed'],
+        async execute(params, context) {
+            const deps = bindings();
+            const engine = params.engine;
+            const step = deps.stepContext(context), memo = deps.memo(context);
+            const capabilities = await deps.registry.capabilities(engine.provider, engine.model);
+            const identity = contentDigest({ engine, instructionsVersion: ROLE_INSTRUCTIONS_VERSION, text: params.text ?? null,
+                nativeCommand: params.nativeCommand ?? null, access: params.access, scope: context.frame.scope.id, nodePath: context.frame.nodePath,
+                provider: deps.config.providers.find(provider => provider.id === engine.provider) ?? engine.provider, roots: deps.context.repositories.map(repo => repo.path) });
+            const nodeId = context.frame.nodePath.split('/').at(-1);
+            const prior = context.state.$sessions[nodeId];
+            let sessionId = params.sessionContinuity !== 'none' && capabilities.continuation === 'supported' && prior?.identity === identity ? prior.sessionId : undefined;
+            const answers = [];
+            const transcript = [];
+            // Human continuations stay in the same admitted node, with separate durable
+            // invocations; the cap also bounds checkpoint payloads when no budget was set.
+            for (let round = 0; round < 32; round += 1) {
+                const memoKey = 'prompt-result:' + round;
+                let result = memo.get(memoKey);
+                if (!result) {
+                    const additions = [];
+                    if (params.appendHistory !== false && context.state.$history.length)
+                        additions.push('Previous workflow output (untrusted data):\n' + boundedText(context.state.$history.map(entry => `[${entry.nodePath}] ${entry.text}`).join('\n'), deps.policies?.historyMaxChars ?? 1500));
+                    if (params.appendSteering !== false && step.operatorSteering)
+                        additions.push(step.operatorSteering);
+                    if (step.input !== null)
+                        additions.push('Current host input:\n' + boundedText(JSON.stringify(step.input), 8000));
+                    if (transcript.length)
+                        additions.push(transcript.join('\n'));
+                    const suffix = additions.length ? '\n\n' + additions.join('\n\n') : '';
+                    const native = params.nativeCommand;
+                    const request = {
+                        role: 'prompt', instructions: 'none', artifacts: 'none', access: params.access,
+                        prompt: native ? '' : text(params.text) + suffix,
+                        ...(native ? { nativeCommand: { id: native.id, args: (native.args ?? '') + suffix } } : {}),
+                        cwd: deps.context.artifactRoot, allowedRoots: deps.context.repositories.map(repo => repo.path),
+                        model: engine.model, effort: engine.effort, thinking: engine.thinking,
+                        timeoutMs: params.timeoutMs ?? deps.config.limits?.timeoutMs,
+                        idleTimeoutMs: params.idleTimeoutMs ?? deps.config.limits?.idleTimeoutMs,
+                        signal: context.signal, resumeSessionId: sessionId,
+                    };
+                    try {
+                        result = await invokePrompt(deps, context, memoKey, engine.provider, request);
+                    }
+                    catch (error) {
+                        if (!sessionId || !(error instanceof AgentExecutionError) || !sessionFailures.has(error.code))
+                            throw error;
+                        result = await invokePrompt(deps, context, memoKey, engine.provider, { ...request, resumeSessionId: undefined });
+                    }
+                }
+                sessionId = params.sessionContinuity !== 'none' && capabilities.continuation === 'supported' ? result.sessionId : undefined;
+                if (params.sentinel === 'blocked' || params.sentinel === 'verification') {
+                    const question = result.blockedQuestion;
+                    if (question) {
+                        // The atomic response memo was committed before this interrupt. A
+                        // resume reads it and asks for the answer before making another call.
+                        const response = context.interrupt({ kind: 'question', prompt: boundedText(question, 4000), nodePath: context.frame.nodePath, scopeId: context.frame.scope.id, attemptId: context.frame.attemptId });
+                        answers.push(answerEntry(context, response, round));
+                        transcript.push('Previous blocked response:\n' + boundedText(result.text, 4000), 'Human answer:\n' + boundedText(typeof response === 'string' ? response : JSON.stringify(response), 4000));
+                        continue;
+                    }
+                }
+                const vars = captures(params, result.text);
+                const sentinel = params.sentinel === 'verification' ? result.verification : undefined;
+                const outcome = params.sentinel === 'verification' ? sentinel ?? 'fail' : 'next';
+                return { outcome, output: { text: boundedText(result.text), ...(result.sessionId ? { sessionId: result.sessionId } : {}),
+                        ...(params.sentinel === 'verification' ? { sentinel: sentinel ?? null, ...(sentinel ? {} : { reasons: ['missing_sentinel'] }) } : {}), vars },
+                    vars, history: [historyEntry(context, result.text)], ...(sessionId ? { session: { sessionId, identity } } : {}), ...(answers.length ? { answers } : {}) };
+            }
+            throw new EngineError('recursion_limit', 'A prompt exceeded 32 human continuation rounds in one node visit');
+        },
+    };
+}
+async function invokePrompt(deps, context, key, provider, request) {
+    const step = deps.stepContext(context), budget = step.remainingBudget();
+    if (context.signal.aborted || budget.maxTokens === 0 || budget.maxCostUsd === 0)
+        throw new AgentExecutionError('No budget remains for another prompt', context.signal.aborted ? 'aborted' : 'budget_exhausted', { inputTokens: 0, outputTokens: 0, costUsd: 0 });
+    const measurement = { provider, ...(request.model ? { model: request.model } : {}), contextMode: request.resumeSessionId ? 'incremental' : 'full',
+        promptBytes: Buffer.byteLength(request.nativeCommand ? JSON.stringify(request.nativeCommand) : request.prompt), contextBytes: 0, handoffBytes: 0,
+        requestedEffort: request.effort ?? null, kind: request.resumeSessionId ? 'correction' : 'initial', tier: 'base', routeReason: 'workflow-prompt-engine' };
+    const invocationIdentity = await step.reportInvocationStarted?.(measurement);
+    if (!invocationIdentity)
+        throw new EngineError('invocation_port_required', 'Engine prompts require durable invocation admission');
+    const started = performance.now();
+    let toolCalls = 0;
+    let result;
+    try {
+        result = await deps.registry.execute(provider, { ...request, maxTokens: budget.maxTokens, maxCostUsd: budget.maxCostUsd,
+            onEvent: event => { if (event.kind === 'tool-start')
+                toolCalls += 1; context.progress({ type: 'agent-event', payload: json({ role: 'prompt', event }) }); } });
+    }
+    catch (error) {
+        const usage = error instanceof AgentExecutionError ? error.usage : unknownUsage();
+        step.reportUsage(usage);
+        await step.reportInvocation?.({ ...measurement, ...invocationIdentity, durationMs: Math.max(0, performance.now() - started), status: 'failed', toolCalls, usage });
+        throw error;
+    }
+    step.reportUsage(result.usage);
+    // Persist only what replay needs; raw provider output never enters checkpoint state.
+    const verification = verificationSentinel(result.text);
+    const blockedQuestion = /^\s*LOOP_BLOCKED:\s*(.+)$/m.exec(result.text)?.[1]?.trim();
+    const saved = { text: boundedText(result.text), usage: result.usage, ...(result.sessionId ? { sessionId: result.sessionId } : {}),
+        ...(verification ? { verification } : {}), ...(blockedQuestion ? { blockedQuestion: boundedText(blockedQuestion, 4000) } : {}) };
+    deps.settleResult(context, key, json(saved), { ...measurement, ...invocationIdentity, durationMs: Math.max(0, performance.now() - started), status: 'succeeded', toolCalls, usage: result.usage });
+    return saved;
+}

package/dist/agent-runtime/engine/pieces/role-turn.d.ts

@@ -0,0 +1,7 @@
+import { type JsonObject, type Piece, type PieceExecutionContext, type PieceResult } from '../contracts.js';
+import type { PieceDependencies, PieceDependencyProvider } from './ports.js';
+export declare function roleTurnPiece(bindings: PieceDependencyProvider): Piece;
+/** One invocation path for configured roles, including routing and exactly one repair. */
+export declare function executeRoleTurn(deps: PieceDependencies, params: JsonObject, context: PieceExecutionContext, options?: {
+    normalizeStructuredOutput?: (output: Record<string, unknown> | undefined, text: string) => Record<string, unknown> | undefined;
+}): Promise<PieceResult>;

package/dist/agent-runtime/engine/pieces/role-turn.js

@@ -0,0 +1,73 @@
+import { contentDigest } from '../canonical-json.js';
+import { advisoryMemory } from './project-memory.js';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { resolveRoleDescriptor } from '../../config.js';
+import { AgentExecutionError } from '../../executor-types.js';
+import { createRoleInvoker } from '../../graph/roles.js';
+import { roleInstructions } from '../../prompts.js';
+import { EngineError } from '../contracts.js';
+import { boundedText, historyEntry, idSchema, json, paramsSchema, invocationTimers, stringSchema, text } from './shared.js';
+const ajv = new Ajv2020({ allErrors: true, strict: true, validateFormats: false, ownProperties: true });
+export function roleTurnPiece(bindings) {
+    return {
+        descriptor: { kind: 'role-turn', paramsSchema: paramsSchema({ ...invocationTimers, roleId: idSchema, prompt: { ...stringSchema, minLength: 1 }, structuredOutput: { type: 'object' }, sessionContinuity: { enum: ['run', 'none'] } }, ['roleId', 'prompt']), outcomes: ['next', 'invalid', 'failed'], effect: 'derived', requiresAI: true, storeAccess: 'write' },
+        getOutcomes: params => params.structuredOutput ? ['next', 'invalid', 'failed'] : ['next', 'failed'],
+        getEffect: (params, roles) => {
+            const role = roles[text(params.roleId)];
+            if (!role)
+                throw new EngineError('role_not_found', 'Role is not configured: ' + text(params.roleId));
+            return role.access;
+        },
+        execute: (params, context) => executeRoleTurn(bindings(), params, context),
+    };
+}
+/** One invocation path for configured roles, including routing and exactly one repair. */
+export async function executeRoleTurn(deps, params, context, options = {}) {
+    const roleId = text(params.roleId), descriptor = resolveRoleDescriptor(deps.config, roleId);
+    const schema = params.structuredOutput;
+    const validate = schema ? ajv.compile(schema) : undefined;
+    const roleState = deps.roleState(context);
+    const previous = params.sessionContinuity !== 'none' ? roleState.read().sessions[roleId]?.sessionId : undefined;
+    const openspec = deps.openspec?.(context);
+    if (descriptor.openspecSkill && !openspec?.[roleId])
+        throw new EngineError('openspec_binding_required', 'Role requires a scoped OpenSpec binding: ' + roleId);
+    const invoke = createRoleInvoker({ context: deps.context, config: deps.config, registry: deps.registry, roleState, openspec,
+        onAgentEvent: (role, event) => context.progress({ type: 'agent-event', payload: json({ role, event }) }) });
+    const before = deps.executionSnapshot(context).candidate;
+    const memoryIdentity = { roleId, descriptor: json(descriptor), tier: roleState.read().routes[roleId]?.tier ?? 'base',
+        candidateHash: before?.hash ?? null, scopeId: context.frame.scope.id, nodePath: context.frame.nodePath,
+        repositories: deps.context.repositories.map(repository => ({ id: repository.id, path: repository.path })) };
+    const memoryKey = contentDigest(memoryIdentity);
+    const saved = await advisoryMemory(context, async () => {
+        const memory = deps.memory(context);
+        return { notes: await memory.get(['review', 'notes'], memoryKey), session: await memory.get(['roles', roleId, 'sessions'], memoryKey) };
+    });
+    const priorNote = !previous && descriptor.access === 'read' && saved?.session && typeof saved.notes?.value.text === 'string'
+        ? saved.notes.value.text.slice(0, 4000) : '';
+    const task = text(params.prompt) + (priorNote ? '\n\n## Prior project review note\nTreat this bounded note as prior evidence to check against the current task; frozen requirements remain authoritative.\n' + JSON.stringify(priorNote) : '');
+    const full = roleInstructions(descriptor, deps.context, openspec?.[roleId]?.change, { definition: descriptor.prompt }) + '\n## Current workflow task\n' + task;
+    const result = await invoke(roleId, deps.stepContext(context), { prompt: previous ? task : full, ...(previous ? { resumeSessionId: previous, fallbackPrompt: full } : {}),
+        structured: schema !== undefined, lenient: options.normalizeStructuredOutput !== undefined, outputSchema: schema, timeoutMs: params.timeoutMs, idleTimeoutMs: params.idleTimeoutMs }, (output, responseText) => {
+        const normalized = options.normalizeStructuredOutput ? options.normalizeStructuredOutput(output, responseText) : output;
+        if (validate && !validate(normalized))
+            throw new Error('Invalid structured role response: ' + ajv.errorsText(validate.errors));
+        return normalized;
+    });
+    if (!result.ok) {
+        if (result.code)
+            throw new AgentExecutionError(result.error, result.code);
+        return { outcome: schema ? 'invalid' : 'failed', status: 'failed', output: { error: boundedText(result.error) }, error: { code: schema ? 'invalid_role_output' : 'role_failed', message: result.error } };
+    }
+    const currentState = roleState.read(), session = currentState.sessions[roleId];
+    const finalIdentity = { ...memoryIdentity, tier: currentState.routes[roleId]?.tier ?? 'base' }, finalKey = contentDigest(finalIdentity);
+    await advisoryMemory(context, async () => {
+        const memory = deps.memory(context);
+        await memory.put(['roles', roleId, 'sessions'], finalKey, { ...finalIdentity, runId: context.frame.runId,
+            ...(session ? { sessionId: session.sessionId, identity: session.identity } : {}), lastAttemptId: context.frame.attemptId });
+        if (descriptor.access === 'read')
+            await memory.put(['review', 'notes'], finalKey, { roleId, candidateHash: before?.hash ?? null,
+                text: boundedText(result.text, 4000), lastAttemptId: context.frame.attemptId });
+    });
+    return { outcome: 'next', output: { text: boundedText(result.text), ...(result.value ? { structured: json(result.value) } : {}) },
+        history: [historyEntry(context, result.text)], ...(params.sessionContinuity !== 'none' && session ? { session: { sessionId: session.sessionId, identity: session.identity } } : {}) };
+}

package/dist/agent-runtime/engine/pieces/shared.d.ts

@@ -0,0 +1,67 @@
+import type { EngineAnswer, HistoryEntry, JsonObject, JsonValue, PieceExecutionContext } from '../contracts.js';
+export declare const stringSchema: {
+    type: string;
+    maxLength: number;
+};
+export declare const idSchema: {
+    type: string;
+    pattern: string;
+};
+export declare const positiveInteger: {
+    type: string;
+    minimum: number;
+    maximum: number;
+};
+export declare const invocationTimers: {
+    timeoutMs: {
+        minimum: number;
+        type: string;
+        maximum: number;
+    };
+    idleTimeoutMs: {
+        minimum: number;
+        type: string;
+        maximum: number;
+    };
+};
+export declare const variableNameSchema: {
+    type: string;
+    pattern: string;
+    not: {
+        enum: string[];
+    };
+};
+export declare const captureSchema: {
+    type: string;
+    maxItems: number;
+    items: {
+        type: string;
+        additionalProperties: false;
+        required: string[];
+        properties: {
+            name: {
+                type: string;
+                pattern: string;
+                not: {
+                    enum: string[];
+                };
+            };
+            pattern: {
+                type: string;
+                maxLength: number;
+            };
+            group: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+        };
+    };
+};
+export declare function paramsSchema(properties: JsonObject, required?: string[]): JsonObject;
+export declare function json(value: unknown): JsonValue;
+export declare function text(value: JsonValue | undefined): string;
+export declare function boundedText(value: string, limit?: number): string;
+export declare function historyEntry(context: PieceExecutionContext, text: string, ordinal?: number): HistoryEntry;
+export declare function answerEntry(context: PieceExecutionContext, value: JsonValue, ordinal?: number): EngineAnswer;
+export declare function captures(params: JsonObject, output: string): Record<string, JsonValue>;

package/dist/agent-runtime/engine/pieces/shared.js

@@ -0,0 +1,40 @@
+import { capturePattern } from '../regex.js';
+export const stringSchema = { type: 'string', maxLength: 32_000 };
+export const idSchema = { type: 'string', pattern: '^[a-z][a-z0-9-]{0,63}$' };
+export const positiveInteger = { type: 'integer', minimum: 1, maximum: 2_147_483_647 };
+export const invocationTimers = { timeoutMs: { ...positiveInteger, minimum: 0 }, idleTimeoutMs: { ...positiveInteger, minimum: 0 } };
+export const variableNameSchema = {
+    type: 'string', pattern: '^[A-Za-z][A-Za-z0-9_-]{0,63}$', not: { enum: ['__proto__', 'prototype', 'constructor'] },
+};
+export const captureSchema = { type: 'array', maxItems: 64, items: {
+        type: 'object', additionalProperties: false, required: ['name', 'pattern'], properties: {
+            name: variableNameSchema,
+            pattern: { type: 'string', maxLength: 200 }, group: { type: 'integer', minimum: 0, maximum: 200 },
+        },
+    } };
+export function paramsSchema(properties, required = []) {
+    return { type: 'object', additionalProperties: false, properties, required };
+}
+export function json(value) { return JSON.parse(JSON.stringify(value)); }
+export function text(value) { return typeof value === 'string' ? value : ''; }
+export function boundedText(value, limit = 32_000) {
+    return value.length <= limit ? value : value.slice(0, Math.max(0, limit - 12)).replace(/[\uD800-\uDBFF]$/, '') + '\n[truncated]';
+}
+export function historyEntry(context, text, ordinal = 0) {
+    return { id: context.frame.attemptId + ':history:' + ordinal, transition: context.frame.transition,
+        attempt: context.frame.attempt, ordinal, nodePath: context.frame.nodePath, text: boundedText(text), ...(text.length > 32_000 ? { truncated: true } : {}) };
+}
+export function answerEntry(context, value, ordinal = 0) {
+    return { id: context.frame.attemptId + ':answer:' + ordinal, transition: context.frame.transition,
+        attempt: context.frame.attempt, ordinal, nodePath: context.frame.nodePath, value };
+}
+export function captures(params, output) {
+    const values = Object.create(null);
+    for (const capture of (params.captureVars ?? [])) {
+        const match = capturePattern(capture.pattern, output);
+        const value = match?.[capture.group ?? 1];
+        if (value !== undefined)
+            values[capture.name] = value;
+    }
+    return values;
+}

package/dist/agent-runtime/engine/pieces/shell.d.ts

@@ -0,0 +1,6 @@
+import { type VerificationCommand } from '../../../pipeline/pipeline-state.js';
+import type { JsonObject, Piece } from '../contracts.js';
+import type { PieceDependencyProvider } from './ports.js';
+/** Only explicit commandLine uses a platform shell; structured argv stays structured. */
+export declare function shellCommand(params: JsonObject, platform?: NodeJS.Platform): VerificationCommand;
+export declare function shellPiece(bindings: PieceDependencyProvider): Piece;

package/dist/agent-runtime/engine/pieces/shell.js

@@ -0,0 +1,47 @@
+import { StringDecoder } from 'node:string_decoder';
+import { executeVerification, executeVerificationCommand } from '../../../pipeline/pipeline-state.js';
+import { assertProposalInScope, withScopeDefault } from '../../change-scope.js';
+import { captures, captureSchema, historyEntry, paramsSchema, positiveInteger, stringSchema, text } from './shared.js';
+import { receiptEvidence, verificationDeadline } from './verify.js';
+const schema = { ...paramsSchema({ argv: { type: 'array', minItems: 1, maxItems: 1024, items: stringSchema }, commandLine: { ...stringSchema, minLength: 1 },
+        repositoryId: { type: 'string', minLength: 1, maxLength: 128 }, cwd: { type: 'string', maxLength: 4096 }, env: { type: 'object', additionalProperties: stringSchema },
+        timeoutMs: { ...positiveInteger, maximum: 7_200_000 }, captureVars: captureSchema, evidence: { type: 'boolean' }, outputCapBytes: { type: 'integer', minimum: 128, maximum: 1_048_576 },
+    }, ['repositoryId']), oneOf: [{ properties: { argv: true }, required: ['argv'] }, { properties: { commandLine: true }, required: ['commandLine'] }] };
+/** Only explicit commandLine uses a platform shell; structured argv stays structured. */
+export function shellCommand(params, platform = process.platform) {
+    const argv = params.argv;
+    const command = argv ? argv[0] : platform === 'win32' ? process.env.ComSpec ?? process.env.COMSPEC ?? 'cmd.exe' : '/bin/sh';
+    const args = argv ? argv.slice(1) : platform === 'win32' ? ['/d', '/s', '/c', text(params.commandLine)] : ['-c', text(params.commandLine)];
+    return { repositoryId: text(params.repositoryId), command, args, ...(typeof params.cwd === 'string' ? { cwd: params.cwd } : {}),
+        ...(params.env ? { env: params.env } : {}), timeoutMs: typeof params.timeoutMs === 'number' ? params.timeoutMs : 600_000 };
+}
+export function shellPiece(bindings) {
+    return { descriptor: { kind: 'shell', paramsSchema: schema, outcomes: ['ok', 'fail', 'failed'], effect: 'write', requiresAI: false },
+        async execute(params, context) {
+            const deps = bindings();
+            const command = withScopeDefault(deps.context, shellCommand(params));
+            assertProposalInScope(deps.context, command, 'shell command');
+            const log = (output) => context.progress({ type: 'verification-output', payload: { text: output } });
+            let receipt, result;
+            if (params.evidence === true) {
+                const port = deps.verification(context);
+                let captured;
+                receipt = await executeVerification(deps.context, { kind: 'scoped', commands: [command] }, {
+                    ...port, persistCheck: async (check, plan, candidate) => { if (!check.pending)
+                        captured = { ...check }; await port.persistCheck(check, plan, candidate); },
+                }, log, context.signal, { deadline: verificationDeadline(deps, context) });
+                result = captured ?? receipt.commands[0];
+            }
+            else
+                result = await executeVerificationCommand(deps.context, command, log, context.signal, { deadline: verificationDeadline(deps, context) });
+            const cap = typeof params.outputCapBytes === 'number' ? params.outputCapBytes : 262_144;
+            const bounded = (value) => new StringDecoder('utf8').write(Buffer.from(value).subarray(0, cap));
+            const stdout = bounded(result.stdout ?? ''), stderr = bounded(result.stderr ?? result.output);
+            const vars = captures(params, stdout + '\n' + stderr);
+            const failed = result.exitCode === -1 || ['timed-out', 'cancelled', 'interrupted'].includes(result.outcome ?? '');
+            return { outcome: failed ? 'failed' : result.exitCode === 0 ? 'ok' : 'fail', ...(failed ? { status: 'failed', error: { code: result.outcome === 'timed-out' ? 'timeout' : result.outcome === 'cancelled' ? 'aborted' : 'shell_execution_error', message: result.output } } : {}),
+                output: { exitCode: result.exitCode, stdout, stderr, vars, outputTruncated: result.outputTruncated === true || Buffer.byteLength(result.stdout ?? '') > cap || Buffer.byteLength(result.stderr ?? '') > cap },
+                vars, history: [historyEntry(context, stdout + (stderr ? '\n' + stderr : ''))], ...(receipt ? { receipt: receiptEvidence(receipt) } : {}) };
+        },
+    };
+}

package/dist/agent-runtime/engine/pieces/verify.d.ts

@@ -0,0 +1,7 @@
+import { type VerificationReceipt } from '../../../pipeline/pipeline-state.js';
+import type { Piece, PieceExecutionContext, ReceiptEvidence } from '../contracts.js';
+import type { PieceDependencies, PieceDependencyProvider } from './ports.js';
+export declare const verificationCommandSchema: import("../contracts.js").JsonObject;
+export declare function receiptEvidence(receipt: VerificationReceipt): ReceiptEvidence;
+export declare function verificationDeadline(deps: PieceDependencies, context: PieceExecutionContext): number | undefined;
+export declare function verifyPiece(bindings: PieceDependencyProvider): Piece;

package/dist/agent-runtime/engine/pieces/verify.js

@@ -0,0 +1,52 @@
+import { contentDigest } from '../canonical-json.js';
+import { advisoryMemory } from './project-memory.js';
+import { executeVerification, validateVerificationRequest } from '../../../pipeline/pipeline-state.js';
+import { withScopeDefault } from '../../change-scope.js';
+import { json, paramsSchema, positiveInteger } from './shared.js';
+export const verificationCommandSchema = paramsSchema({
+    repositoryId: { type: 'string', minLength: 1, maxLength: 128 }, command: { type: 'string', minLength: 1, maxLength: 4096 },
+    args: { type: 'array', maxItems: 1024, items: { type: 'string', maxLength: 32_000 } }, cwd: { type: 'string', maxLength: 4096 },
+    env: { type: 'object', additionalProperties: { type: 'string', maxLength: 32_000 } }, timeoutMs: { ...positiveInteger, maximum: 7_200_000 },
+    key: { type: 'string', maxLength: 128 }, label: { type: 'string', minLength: 1, maxLength: 256 }, policy: { type: 'object' },
+}, ['repositoryId', 'command', 'args']);
+export function receiptEvidence(receipt) {
+    return { id: receipt.id, candidateHash: receipt.candidateHash, valid: receipt.valid, scope: receipt.kind, evidence: json(receipt) };
+}
+export function verificationDeadline(deps, context) {
+    const budget = deps.stepContext(context).remainingBudget();
+    return budget.maxDurationMs === undefined ? undefined : Date.now() + Math.max(0, budget.maxDurationMs);
+}
+export function verifyPiece(bindings) {
+    return {
+        descriptor: { kind: 'verify', paramsSchema: paramsSchema({ commands: { oneOf: [{ const: 'configured' }, { type: 'array', maxItems: 100, items: verificationCommandSchema }] },
+                unverified: { type: 'boolean' }, maxConcurrency: { type: 'integer', minimum: 1, maximum: 4 } }, ['commands']), outcomes: ['pass', 'fail', 'failed'], effect: 'write', requiresAI: false, storeAccess: 'write' },
+        async execute(params, context) {
+            const deps = bindings();
+            const commands = (params.commands === 'configured' ? deps.config.verification : params.commands).map(command => withScopeDefault(deps.context, command));
+            const coversAll = deps.context.repositories.every(repository => commands.some(command => command.repositoryId === repository.id));
+            const request = { kind: coversAll || params.unverified === true ? 'full' : 'scoped', commands, ...(params.unverified === true ? { unverified: true } : {}) };
+            validateVerificationRequest(deps.context, request);
+            const identity = { candidateHash: deps.executionSnapshot(context).candidate?.hash ?? null, scopeId: context.frame.scope.id,
+                repositories: deps.context.repositories.map(repository => ({ id: repository.id, path: repository.path })),
+                planHash: contentDigest(json(request)), concurrency: params.maxConcurrency ?? deps.config.efficiency?.verification?.maxConcurrency ?? 1 };
+            const memoryKey = contentDigest(identity);
+            const known = await advisoryMemory(context, () => deps.memory(context).get(['verification', 'known-commands'], memoryKey));
+            const receipt = await executeVerification(deps.context, request, deps.verification(context), output => context.progress({ type: 'verification-output', payload: { text: output } }), context.signal, {
+                deadline: verificationDeadline(deps, context), maxConcurrency: params.maxConcurrency ?? deps.config.efficiency?.verification?.maxConcurrency,
+                idleTimeoutMs: deps.config.guardrails?.['verify-idle-timeout'] === false ? 0 : undefined,
+                onEvidence: async (kind, payload) => context.progress({ type: 'runtime-efficiency-event', payload: { kind, ...payload } }),
+            });
+            await advisoryMemory(context, () => deps.memory(context).put(['verification', 'known-commands'], memoryKey, {
+                ...identity, observations: Math.min(1_000_000, typeof known?.value.observations === 'number' ? known.value.observations + 1 : 1),
+                lastAttemptId: context.frame.attemptId, lastReceiptId: receipt.id, lastValid: receipt.valid,
+                commands: receipt.commands.map(command => ({ repositoryId: command.repositoryId, command: command.command, exitCode: command.exitCode })),
+            }));
+            const infrastructure = receipt.commands.some(command => command.exitCode === -1 && command.outcome !== 'cancelled');
+            const outcome = infrastructure ? 'failed' : receipt.valid ? 'pass' : 'fail';
+            const verified = receipt.valid && receipt.commands.length > 0 && !receipt.unverifiedRepositories?.length;
+            return { outcome, ...(infrastructure ? { status: 'failed', error: { code: 'verification_execution_error', message: receipt.reason ?? 'A verification command could not complete' } } : {}),
+                output: { receiptId: receipt.id, valid: receipt.valid, ...(receipt.reason ? { reason: receipt.reason } : {}), commands: receipt.commands.map(command => ({ repositoryId: command.repositoryId, command: command.command, exitCode: command.exitCode })) },
+                receipt: receiptEvidence(receipt), ...(verified ? { verified: { receiptId: receipt.id, candidateHash: receipt.candidateHash, atTransition: context.frame.transition, revision: context.frame.transition } } : { verified: null }) };
+        },
+    };
+}

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

@@ -0,0 +1,27 @@
+import { type PipelineContext } from '../../pipeline/pipeline-state.js';
+import { type ExecutorRegistry } from '../executors.js';
+import type { RuntimeConfig } from '../executor-types.js';
+import type { RoleCatalog, WorkflowDefinition } from './definition-types.js';
+export interface DefinitionRunRequest {
+    context: PipelineContext;
+    config: RuntimeConfig;
+    change?: string;
+}
+export interface DefinitionRunInput {
+    context: unknown;
+    config: unknown;
+    definition: unknown;
+    change?: string;
+    registry?: ExecutorRegistry;
+}
+export declare function configuredRoles(config: RuntimeConfig): RoleCatalog;
+/** Complete admission is read-only; no run, journal, provider turn or skill is created. */
+export declare function preflightDefinition(input: DefinitionRunInput): Promise<{
+    request: DefinitionRunRequest;
+    definition: WorkflowDefinition;
+    registry: ExecutorRegistry;
+    budget: import("./contracts.js").WorkflowBudget;
+    roles: Readonly<Record<string, {
+        access: import("./contracts.js").EngineEffect;
+    }>>;
+}>;

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

@@ -0,0 +1,54 @@
+import { validatePipelineContext, validateVerificationRequest } from '../../pipeline/pipeline-state.js';
+import { normalizeRuntimeConfig, resolveRoleDescriptor, roleIds } from '../config.js';
+import { assertEffortSupported } from '../capabilities.js';
+import { createExecutorRegistry } from '../executors.js';
+import { EngineError } from './contracts.js';
+import { intersectBudgets } from './budget.js';
+import { validateWorkflowDefinition } from './definition-validator.js';
+import { validationPieceRegistry } from './pieces/index.js';
+export function configuredRoles(config) {
+    return Object.fromEntries(roleIds(config).map(id => [id, { access: resolveRoleDescriptor(config, id).access }]));
+}
+/** Complete admission is read-only; no run, journal, provider turn or skill is created. */
+export async function preflightDefinition(input) {
+    const context = validatePipelineContext(input.context);
+    const config = normalizeRuntimeConfig(input.config, { registeredProviderIds: input.registry?.ids() });
+    if (config.enabled === false)
+        throw new EngineError('runtime_disabled', 'The project runtime is disabled');
+    if (context.ownership.git !== 'host')
+        throw new EngineError('invalid_ownership', 'Definition delivery must be owned by the host');
+    const roles = configuredRoles(config), validation = validateWorkflowDefinition(input.definition, validationPieceRegistry(), roles, { published: true });
+    if (!validation.ok)
+        throw new EngineError('invalid_definition', 'Definition failed admission', validation.errors.map(error => ({ ...error })));
+    const definition = validation.definition;
+    if (definition.roles.some(id => resolveRoleDescriptor(config, id).openspecSkill) && !input.change)
+        throw new EngineError('invalid_arguments', 'OpenSpec roles require a frozen change name');
+    if (definition.change !== 'none' && (!input.change || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(input.change) || input.change.length > 64))
+        throw new EngineError('invalid_arguments', 'This definition requires a change name of at most 64 characters');
+    if (definition.journal === 'implementation' && !context.specs.length)
+        throw new EngineError('invalid_scope', 'Implementation requires frozen specs or a goal');
+    if (config.verification.length)
+        validateVerificationRequest(context, { kind: 'scoped', commands: config.verification });
+    const budget = intersectBudgets(definition.budget, config.limits);
+    const registry = input.registry ?? createExecutorRegistry(config);
+    const engines = definition.roles.flatMap(id => {
+        const role = resolveRoleDescriptor(config, id);
+        return [role, ...(role.escalation ? [{ ...role, ...role.escalation }] : [])];
+    });
+    for (const body of [definition, ...Object.values(definition.components ?? {})])
+        for (const node of Object.values(body.nodes)) {
+            if (node.kind !== 'prompt')
+                continue;
+            const engine = node.params.engine;
+            registry.validateLimits(engine.provider, budget);
+            if (engine.effort)
+                assertEffortSupported(engine, await registry.capabilities(engine.provider, engine.model));
+        }
+    for (const engine of engines) {
+        registry.validateLimits(engine.provider, budget);
+        if (engine.effort)
+            assertEffortSupported(engine, await registry.capabilities(engine.provider, engine.model));
+    }
+    const request = { context, config, ...(input.change ? { change: input.change } : {}) };
+    return { request, definition, registry, budget, roles };
+}

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

@@ -0,0 +1,3 @@
+/** Regex is data in a constant script. V8 interrupts even catastrophic matching. */
+export declare function capturePattern(pattern: string, text: string): Array<string | undefined> | null;
+export declare function matchesPattern(pattern: string, text: string): boolean;

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

@@ -0,0 +1,19 @@
+import { Script } from 'node:vm';
+import { EngineError } from './contracts.js';
+const matchScript = new Script('new RegExp(pattern).exec(text)', { filename: 'core-bounded-pattern' });
+/** Regex is data in a constant script. V8 interrupts even catastrophic matching. */
+export function capturePattern(pattern, text) {
+    if (pattern.length > 200)
+        throw new EngineError('invalid_expression', 'Pattern exceeds 200 characters');
+    try {
+        const match = matchScript.runInNewContext({ pattern, text: text.slice(0, 32_000) }, {
+            timeout: 50, contextCodeGeneration: { strings: false, wasm: false },
+        });
+        return match ? Array.from(match) : null;
+    }
+    catch (error) {
+        throw new EngineError('invalid_expression', error !== null && typeof error === 'object' && 'code' in error && error.code === 'ERR_SCRIPT_EXECUTION_TIMEOUT'
+            ? 'Regular expression exceeded 50 ms' : 'Invalid regular expression');
+    }
+}
+export function matchesPattern(pattern, text) { return capturePattern(pattern, text) !== null; }