specrails-core 6.4.0 → 6.6.0

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

@@ -5,6 +5,9 @@ import { withScopeDefault } from '../../change-scope.js';
 import { resolveRoleDescriptor } from '../../config.js';
 import { AgentExecutionError } from '../../executor-types.js';
 import { createRoleInvoker } from '../../graph/roles.js';
+import { admitVerificationProposals } from '../../verification-proposals.js';
+import { guardrailEnabled } from '../../guardrails.js';
+import { installEnvironment, prepareEnvironment } from '../../compact/environment.js';
 import { roleInstructions } from '../../prompts.js';
 import { EngineError } from '../contracts.js';
 import { boundedText, historyEntry, idSchema, json, paramsSchema, invocationTimers, stringSchema, text } from './shared.js';
@@ -25,6 +28,14 @@ export function roleTurnPiece(bindings) {
 /** 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);
+    // Agents run sandboxed and cannot install what the repository needs (Codex
+    // cannot even write the Playwright browser cache): the host prepares it
+    // before any writer turn and says so in the task.
+    const hostRepairs = descriptor.access === 'write' && guardrailEnabled(deps.config.guardrails, 'environment-repair');
+    const note = (line) => context.progress({ type: 'verification-output', payload: { text: line } });
+    const environment = options.environmentRetry
+        ? environmentNote(options.environmentRetry.installs, 'retry')
+        : hostRepairs ? environmentNote(prepareEnvironment(deps.context.repositories.map(repository => repository.path), environmentIo(deps, note)), 'prepared') : '';
     const schema = params.structuredOutput;
     const validate = schema ? ajv.compile(schema) : undefined;
     const roleState = deps.roleState(context);
@@ -45,9 +56,10 @@ export async function executeRoleTurn(deps, params, context, options = {}) {
     });
     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 task = text(params.prompt) + environment + (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 verification = descriptor.access === 'write' ? hostVerificationPlan(deps, context, params) : undefined;
-    const full = roleInstructions(descriptor, deps.context, openspec?.[roleId]?.change, { definition: descriptor.prompt, verification }) + '\n## Current workflow task\n' + task;
+    const adopted = adoptedVerificationOutputs(context.state.$outputs);
+    const full = roleInstructions(descriptor, deps.context, openspec?.[roleId]?.change, { definition: descriptor.prompt, verification, ...(adopted.length ? { adoptedOutputs: adopted } : {}) }) + '\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;
@@ -60,6 +72,19 @@ export async function executeRoleTurn(deps, params, context, options = {}) {
             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 } };
     }
+    // A writer that still hit a missing tool reports a structured blocker. When
+    // the host can install it, it does so and reruns the turn once instead of
+    // ending the run on something it can fix itself.
+    const blocker = hostRepairs && !options.environmentRetry ? repairableBlocker(result.value) : undefined;
+    if (blocker) {
+        const roots = deps.context.repositories.map(repository => repository.path);
+        const io = environmentIo(deps, note);
+        const installs = [...installEnvironment(roots, { ...io, failureOutput: blocker }), ...prepareEnvironment(roots, io)];
+        if (installs.some(install => install.ok)) {
+            note('[environment] The agent reported a missing dependency or tool; the host installed it and runs the turn again.');
+            return executeRoleTurn(deps, params, context, { ...options, environmentRetry: { installs } });
+        }
+    }
     const currentState = roleState.read(), session = currentState.sessions[roleId];
     const finalIdentity = { ...memoryIdentity, tier: currentState.routes[roleId]?.tier ?? 'base' }, finalKey = contentDigest(finalIdentity);
     await advisoryMemory(context, async () => {
@@ -73,34 +98,51 @@ export async function executeRoleTurn(deps, params, context, options = {}) {
     return { outcome: 'next', output: { candidateHash: deps.executionSnapshot(context).candidate?.hash ?? null, 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 } } : {}) };
 }
+/** Files any committed `verify` output reports as host-adopted verification output (sticky for the run), so no role is told to revert them. */
+function adoptedVerificationOutputs(outputs) {
+    return Object.values(outputs).flatMap(output => {
+        const listed = output && typeof output === 'object' && !Array.isArray(output) ? output.adoptedOutputs : undefined;
+        return Array.isArray(listed) ? listed.flatMap(item => item && typeof item === 'object' && !Array.isArray(item) && typeof item.path === 'string'
+            ? [{ ...(typeof item.repositoryId === 'string' ? { repositoryId: item.repositoryId } : {}), path: item.path }] : []) : [];
+    });
+}
+const REPAIRABLE_BLOCKERS = new Set(['toolchain', 'setup', 'environment']);
+/** The text of a structured `blocker` the host may be able to install away; undefined for other kinds (credentials, network, scope). */
+function repairableBlocker(value) {
+    const blocker = value?.blocker;
+    if (!blocker || typeof blocker !== 'object' || !REPAIRABLE_BLOCKERS.has(String(blocker.kind)))
+        return undefined;
+    return ['evidence', 'reason', 'command', 'requiredAction'].map(field => typeof blocker[field] === 'string' ? blocker[field] : '').join('\n').slice(0, 8_000);
+}
+function environmentIo(deps, note) {
+    return { lockfileRepair: guardrailEnabled(deps.config.guardrails, 'lockfile-repair'),
+        onEvent: (event) => note(event.kind === 'text' ? event.text ?? '' : `[environment] ${event.tool ?? ''} ${event.detail ?? ''}`.trim()) };
+}
+/** What the host installed (or could not) for this turn, as task context; empty when nothing was needed. */
+function environmentNote(installs, when) {
+    if (!installs.length)
+        return '';
+    const done = installs.filter(install => install.ok).map(install => install.installs ?? `${install.ecosystem} dependencies`);
+    const failed = installs.filter(install => !install.ok).map(install => install.detail);
+    return '\n\n## Host environment\n' + (when === 'retry' ? 'Your previous turn reported an environment blocker. ' : '')
+        + (done.length ? `The host installed ${done.join('; ')} for this workspace${when === 'retry' ? ': continue the remaining work and rerun the checks that were blocked.' : ' before this turn.'} ` : '')
+        + (failed.length ? `It could not install: ${failed.join('; ')}. ` : '')
+        + 'Do not install these yourself; if something is still missing, return the structured blocker.';
+}
 /** The complete plan the host will run for the repositories in scope: configured checks plus, when `verificationProposalsFrom`
- * names a committed output, its proposals for repositories without a configured check (the rule the verify piece applies). */
+ * names a committed output, the proposals the verify piece admits (see admitVerificationProposals). */
 function hostVerificationPlan(deps, context, params) {
     const inScope = new Set(deps.context.repositories.map(repository => repository.id));
     const commands = deps.config.verification.filter(command => inScope.has(command.repositoryId)).map(command => withScopeDefault(deps.context, command));
-    const configured = new Set(commands.map(command => command.repositoryId));
-    const seen = new Set(commands.map(planKey));
     if (typeof params.verificationProposalsFrom === 'string') {
         const source = context.state.$outputs[params.verificationProposalsFrom];
-        const proposals = Array.isArray(source?.structured?.verification) ? source.structured.verification.slice(0, 20) : [];
-        for (const proposal of proposals) {
+        const proposals = (Array.isArray(source?.structured?.verification) ? source.structured.verification.slice(0, 20) : []).filter((proposal) => {
             if (!proposal || typeof proposal !== 'object' || Array.isArray(proposal))
-                continue;
+                return false;
             const raw = proposal;
-            if (typeof raw.repositoryId !== 'string' || typeof raw.command !== 'string' || !Array.isArray(raw.args) || !raw.args.every(arg => typeof arg === 'string'))
-                continue;
-            if (!inScope.has(raw.repositoryId) || configured.has(raw.repositoryId))
-                continue;
-            const command = withScopeDefault(deps.context, { repositoryId: raw.repositoryId, command: raw.command, args: raw.args, ...(typeof raw.cwd === 'string' ? { cwd: raw.cwd } : {}) });
-            const key = planKey(command);
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            commands.push(command);
-        }
+            return typeof raw.repositoryId === 'string' && inScope.has(raw.repositoryId) && typeof raw.command === 'string' && Array.isArray(raw.args) && raw.args.every(arg => typeof arg === 'string');
+        });
+        commands.push(...admitVerificationProposals(deps.context, commands, proposals, raw => withScopeDefault(deps.context, { repositoryId: raw.repositoryId, command: raw.command, args: raw.args, ...(typeof raw.cwd === 'string' ? { cwd: raw.cwd } : {}) })));
     }
     return commands;
 }
-function planKey(command) {
-    return JSON.stringify([command.repositoryId, command.cwd ?? '', command.command, command.args]);
-}

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

@@ -14,14 +14,14 @@ export declare const positiveInteger: {
 };
 export declare const invocationTimers: {
     timeoutMs: {
-        minimum: number;
         type: string;
         maximum: number;
+        minimum: number;
     };
     idleTimeoutMs: {
-        minimum: number;
         type: string;
         maximum: number;
+        minimum: number;
     };
 };
 export declare const variableNameSchema: {

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

@@ -1,13 +1,14 @@
+import { admitVerificationProposals } from '../../verification-proposals.js';
 import { stripVTControlCharacters } from 'node:util';
 import { contentDigest } from '../canonical-json.js';
 import { advisoryMemory } from './project-memory.js';
-import { executeVerification, validateVerificationRequest } from '../../../pipeline/pipeline-state.js';
+import { describeModifiedFiles, executeVerification, validateVerificationRequest } from '../../../pipeline/pipeline-state.js';
 import { withScopeDefault } from '../../change-scope.js';
 import { verificationDiagnosticPriority, verificationFailureSummary } from '../../verification-diagnostics.js';
 import { boundedText, json, paramsSchema, positiveInteger } from './shared.js';
-import { isEnvironmentFailure } from '../../compact/environment.js';
+import { describeDrift } from '../../compact/environment.js';
 import { guardrailEnabled } from '../../guardrails.js';
-import { checkoutRelative, preconditionBlock, repairEnvironment } from '../../verification-repair.js';
+import { NONDETERMINISTIC_OUTPUT_CODE, adoptedOutputNote, checkoutRelative, environmentFailure, nondeterministicOutputBlocker, preconditionBlock, repairEnvironment, selfMutationOnly } from '../../verification-repair.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. */
@@ -89,7 +90,6 @@ const verificationCommandList = { type: 'array', maxItems: 100, items: verificat
 export function resolveVerificationPlan(deps, context, params) {
     const configured = params.commands === undefined || params.commands === 'configured' ? deps.config.verification : params.commands;
     const commands = configured.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;
@@ -100,12 +100,10 @@ export function resolveVerificationPlan(deps, context, params) {
         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))
+            if (!deps.context.repositories.some(repository => repository.id === proposal.repositoryId))
                 throw new Error('Unknown verification repository');
-            if (!hostRepositories.has(raw.repositoryId))
-                commands.push(withScopeDefault(deps.context, raw));
         }
+        commands.push(...admitVerificationProposals(deps.context, commands, proposals, raw => withScopeDefault(deps.context, raw)));
     }
     return commands;
 }
@@ -171,10 +169,16 @@ export function verifyPiece(bindings) {
             // fresh worktree has no node_modules whatever wrote the code. Install
             // once where the failing command runs and verify again; only the second
             // receipt becomes feedback.
+            // Installed versions outside their declared ranges (a stale warm-linked
+            // tree) count as environmental whatever the failing output says.
             let environmentRepair;
-            if (!blocker && !receipt.valid && guardrailEnabled(deps.config.guardrails, 'environment-repair') && receipt.commands.some(command => isEnvironmentFailure(command.exitCode, command.output))) {
+            const environment = !blocker && !receipt.valid && guardrailEnabled(deps.config.guardrails, 'environment-repair') ? environmentFailure(deps.context, receipt) : undefined;
+            if (environment) {
+                const drift = environment.drift.flatMap(item => item.drift.map(entry => ({ root: checkoutRelative(deps.context, item.root), ...entry }))).slice(0, 20);
+                if (drift.length)
+                    progress(`[environment] Installed dependencies do not satisfy their declared ranges (${describeDrift(drift)}); the host reinstalls them before judging the failure.`);
                 const repair = repairEnvironment(deps.context, receipt, deps.config.guardrails, progress);
-                environmentRepair = { attempted: true, reverified: false, installs: repair.installs.map(install => ({ command: install.command, args: install.args, root: checkoutRelative(deps.context, install.root), ok: install.ok, detail: boundedText(install.detail, 1_000) })) };
+                environmentRepair = { attempted: true, reverified: false, installs: repair.installs.map(install => ({ command: install.command, args: install.args, root: checkoutRelative(deps.context, install.root), ok: install.ok, detail: boundedText(install.detail, 1_000) })), ...(drift.length ? { drift } : {}) };
                 if (repair.refused)
                     blocker = repair.refused;
                 else if (repair.installs.some(install => install.ok)) {
@@ -184,6 +188,29 @@ export function verifyPiece(bindings) {
                     blocker = receipt.valid ? undefined : preconditionBlock(deps.context, receipt);
                 }
             }
+            // Verification that rewrote candidate files itself (a lint pre-step
+            // regenerating a tracked mapping) is not a code failure: reverting the
+            // file only makes the next run regenerate it. Keep it in the candidate
+            // and verify once more; output that changes again is the repository's
+            // or operator's to fix, never a correction round.
+            let adopted, nondeterministic;
+            if (!blocker && selfMutationOnly(receipt) && !context.signal.aborted && (verificationDeadline(deps, context) ?? Infinity) > Date.now()) {
+                const first = receipt.selfMutation;
+                if (!guardrailEnabled(deps.config.guardrails, 'verification-output-adoption'))
+                    nondeterministic = nondeterministicOutputBlocker(deps.context, receipt, false);
+                else {
+                    progress(`[verification] Verification commands modified ${describeModifiedFiles(first)}; keeping them in the candidate and verifying once more.`);
+                    receipt = await run(request, concurrency);
+                    if (receipt.valid) {
+                        adopted = first.files;
+                        progress(adoptedOutputNote(first));
+                    }
+                    else if (selfMutationOnly(receipt))
+                        nondeterministic = nondeterministicOutputBlocker(deps.context, receipt, true);
+                    else
+                        blocker = preconditionBlock(deps.context, receipt);
+                }
+            }
             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,
@@ -195,12 +222,18 @@ export function verifyPiece(bindings) {
             const fingerprint = contentDigest(json({ candidateHash: identity.candidateHash,
                 failures: receipt.commands.filter(command => command.exitCode !== 0).map(command => ({ repositoryId: command.repositoryId, command: command.command, args: command.args, cwd: command.cwd, exitCode: command.exitCode })) }));
             const previous = context.state.$vars[progressKey];
+            // Adopted output stays adopted for the rest of the run: a later pass that no longer mutates must not invite its revert.
+            const adoptedOutputs = [...new Map([...(Array.isArray(previous?.adopted) ? previous.adopted : []), ...(adopted ?? [])].map(file => [file.repositoryId + '\0' + file.path, file])).values()].slice(0, 200);
             const count = receipt.valid ? 0 : previous?.fingerprint === fingerprint ? (previous.count ?? 0) + 1 : 1;
             const stalled = !infrastructure && !receipt.valid && count >= 3;
             const verified = receipt.valid && receipt.commands.length > 0 && !receipt.unverifiedRepositories?.length;
-            const output = { receiptId: receipt.id, valid: receipt.valid, candidateHash: identity.candidateHash, noProgressCount: count, ...(receipt.reason ? { reason: receipt.reason } : {}), ...(stalled ? { reason: 'Verification failed three times without candidate changes' } : {}),
-                ...(setup ? { setup } : {}), ...(environmentRepair ? { environmentRepair } : {}), ...verificationDiagnostics(receipt) };
-            const vars = { [progressKey]: { fingerprint, count } };
+            const output = { receiptId: receipt.id, valid: receipt.valid, candidateHash: adopted ? receipt.candidateHash : identity.candidateHash, noProgressCount: count, ...(receipt.reason ? { reason: receipt.reason } : {}), ...(stalled ? { reason: 'Verification failed three times without candidate changes' } : {}),
+                ...(setup ? { setup } : {}), ...(environmentRepair ? { environmentRepair } : {}), ...(receipt.selfMutation ? { selfMutation: json(receipt.selfMutation) } : {}),
+                ...(adoptedOutputs.length ? { adoptedOutputs: json(adoptedOutputs) } : {}), ...verificationDiagnostics(receipt) };
+            const vars = { [progressKey]: { fingerprint, count, ...(adoptedOutputs.length ? { adopted: json(adoptedOutputs) } : {}) } };
+            if (nondeterministic)
+                return { outcome: params.hostBlockers === true ? 'blocked' : 'failed', status: params.hostBlockers === true ? 'blocked' : 'failed', vars, receipt: receiptEvidence(receipt), verified: null,
+                    error: { code: NONDETERMINISTIC_OUTPUT_CODE, message: `${nondeterministic.reason}. ${nondeterministic.requiredAction}` }, output: { ...output, valid: false, blocker: json(nondeterministic) } };
             // Without the opt-in outcome a blocker still travels in the output, and the no-progress stop keeps bounding the loop.
             if (blocker && (params.hostBlockers === true || !stalled))
                 return { ...blocked(blocker, output), vars, receipt: receiptEvidence(receipt) };