specrails-core 6.0.1 → 6.2.0

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

@@ -0,0 +1,102 @@
+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 { boundedText, json, paramsSchema, positiveInteger } from './shared.js';
+/** Keep real subprocess diagnostics in committed outputs for subsequent agents.
+ * The full command evidence remains in the receipt; prioritize failed checks
+ * when the output budget is exhausted. */
+function verificationDiagnostics(receipt) {
+    let remaining = 32_000;
+    const outputs = new Map();
+    const priority = receipt.commands.map((command, index) => ({ command, index }))
+        .sort((a, b) => Number(b.command.exitCode !== 0) - Number(a.command.exitCode !== 0));
+    for (const { command, index } of priority) {
+        const output = command.output.slice(-Math.min(8_000, remaining));
+        // slice(-0) would include all the original text.
+        outputs.set(index, remaining > 0 ? output : '');
+        remaining -= remaining > 0 ? output.length : 0;
+    }
+    let budget = 64_000;
+    const commands = [];
+    for (const { index, command } of priority) {
+        const output = outputs.get(index) ?? '';
+        const args = command.args.slice(0, 16).map(arg => boundedText(arg, 128));
+        const diagnostic = { repositoryId: command.repositoryId, command: boundedText(command.command, 512),
+            args, cwd: boundedText(command.cwd, 512),
+            exitCode: command.exitCode, durationMs: command.durationMs, output,
+            truncated: output.length < command.output.length || command.outputTruncated === true
+                || command.command.length > 512 || command.cwd.length > 512 || command.args.length > 16 || command.args.some(arg => arg.length > 128) };
+        const size = JSON.stringify(diagnostic).length;
+        if (size > budget)
+            break;
+        budget -= size;
+        commands.push(diagnostic);
+    }
+    return { commands, ...(commands.length < receipt.commands.length ? { omittedCommands: receipt.commands.length - commands.length } : {}) };
+}
+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 }] },
+                additionalCommandsFrom: { type: 'string', minLength: 1, maxLength: 128 }, 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 hostRepositories = new Set(commands.map(command => command.repositoryId));
+            if (typeof params.additionalCommandsFrom === 'string') {
+                const source = context.state.$outputs[params.additionalCommandsFrom];
+                const proposals = source?.structured?.verification;
+                if (!Array.isArray(proposals) || proposals.length > 20)
+                    throw new Error('Verification proposals must be a bounded array from a committed agent output');
+                // Host checks always stay mandatory. The same scoped command validation
+                // applies to these actual subprocesses and to configured checks below.
+                for (const proposal of proposals) {
+                    if (!proposal || typeof proposal !== 'object' || Array.isArray(proposal))
+                        throw new Error('Invalid verification proposal');
+                    const raw = proposal;
+                    if (!deps.context.repositories.some(repository => repository.id === raw.repositoryId))
+                        throw new Error('Unknown verification repository');
+                    if (!hostRepositories.has(raw.repositoryId))
+                        commands.push(withScopeDefault(deps.context, raw));
+                }
+            }
+            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 } : {}), ...verificationDiagnostics(receipt) },
+                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; }