specrails-core 6.4.0 → 6.5.0

package/dist/agent-runtime/capabilities.js

@@ -36,6 +36,16 @@ export async function cliCapabilities(provider, model, options = {}) {
                 return { ...result, effortSupport: 'supported', supportedEfforts: levels };
         }
         else if (model && help.stdout.includes('--config')) {
+            // Ask the installed client for its own model catalog. Other Codex clients
+            // (the desktop app's app-server daemon, IDE extensions) share
+            // models_cache.json and rewrite it with their own version, so the cache
+            // is only a fallback for clients without `codex debug models`.
+            const catalog = await runner({ command: provider, args: ['debug', 'models'] }, { cwd: tmpdir(), env, timeoutMs: 10_000 }).catch(() => null);
+            if (catalog?.exitCode === 0 && catalog.stdout.length <= 2 * 1024 * 1024) {
+                const levels = codexModelEfforts(JSON.parse(catalog.stdout), model);
+                if (levels)
+                    return { ...result, effortSupport: 'supported', supportedEfforts: levels };
+            }
             // Use the installed client's own bounded, fresh model catalog. Do not
             // infer reasoning support from a model prefix or another provider.
             const file = path.join(env.CODEX_HOME ?? path.join(env.HOME ?? homedir(), '.codex'), 'models_cache.json');
@@ -48,16 +58,23 @@ export async function cliCapabilities(provider, model, options = {}) {
             const version = await runner({ command: provider, args: ['--version'] }, { cwd: tmpdir(), env, timeoutMs: 10_000 });
             if (version.exitCode !== 0 || version.stdout.trim() !== `codex-cli ${cache.client_version}`)
                 return result;
-            const entry = Array.isArray(cache.models) ? cache.models.find((item) => item?.slug === model) : undefined;
-            const levels = entry?.supported_reasoning_levels?.map((item) => item?.effort);
-            if (Array.isArray(levels) && levels.length && levels.every(value => typeof value === 'string' && /^[a-z][a-z0-9_-]{0,31}$/.test(value))) {
-                return { ...result, effortSupport: 'supported', supportedEfforts: [...new Set(levels)] };
-            }
+            const levels = codexModelEfforts(cache, model);
+            if (levels)
+                return { ...result, effortSupport: 'supported', supportedEfforts: levels };
         }
     }
     catch { /* Missing/stale metadata is unknown, never optimistic support. */ }
     return result;
 }
+/** Reasoning levels a Codex catalog (`{ models: [...] }`) declares for one model; null when unknown or malformed. */
+function codexModelEfforts(catalog, model) {
+    const models = catalog?.models;
+    const entry = Array.isArray(models) ? models.find((item) => item?.slug === model) : undefined;
+    const levels = entry?.supported_reasoning_levels?.map?.((item) => item?.effort);
+    if (!Array.isArray(levels) || !levels.length || !levels.every(value => typeof value === 'string' && /^[a-z][a-z0-9_-]{0,31}$/.test(value)))
+        return null;
+    return [...new Set(levels)];
+}
 export function assertEffortSupported(selection, capability) {
     if (selection.effort !== undefined && (capability.effortSupport !== 'supported' || !capability.supportedEfforts?.includes(selection.effort))) {
         throw new AgentExecutionError(`Requested effort '${selection.effort}' is not confirmed for ${capability.transport}. Select a supported effort or provider default.`, 'provider_capability_unsupported');

package/dist/agent-runtime/cli-executor.js

@@ -32,7 +32,7 @@ export function buildCliInvocation(provider, request, options = {}) {
     }
     const readOnly = requestPolicy(request).access === 'read';
     // Pin the product alias; explicit IDs remain reproducible across releases.
-    const claudeModelIds = { opus: 'claude-opus-5-5', sonnet: 'claude-sonnet-5-5' };
+    const claudeModelIds = { opus: 'claude-opus-5-5', sonnet: 'claude-sonnet-5-5', haiku: 'claude-haiku-5-5' };
     const modelId = provider === 'claude' && request.model ? claudeModelIds[request.model] ?? request.model : request.model;
     const model = modelId ? ['--model', modelId] : [];
     const extraRoots = request.allowedRoots.filter(root => root !== request.cwd);
@@ -54,14 +54,19 @@ export function buildCliInvocation(provider, request, options = {}) {
                 ...(resume ? ['--resume', resume] : []),
             ] };
         case 'codex': {
-            const sandbox = readOnly ? 'read-only' : 'workspace-write';
+            // Writers run without Codex's OS sandbox, like the Claude developer
+            // (--dangerously-skip-permissions) and Desktop's legacy rail runs: the
+            // workspace-write seatbelt denies what real verification needs (a
+            // localhost listen, Chromium's Mach bootstrap registration, the browser
+            // cache). Read-only roles keep the read-only sandbox.
+            const sandbox = readOnly ? 'read-only' : 'danger-full-access';
             const common = ['--json', '--skip-git-repo-check', '-c', 'approval_policy="never"', ...model,
                 ...(request.effort === undefined ? [] : ['-c', 'model_reasoning_effort=' + JSON.stringify(request.effort)]),
                 ...(options.openspecBridge ? ['-c', 'mcp_servers.specrails_openspec.command=' + JSON.stringify(options.openspecBridge.command), '-c', 'mcp_servers.specrails_openspec.args=' + JSON.stringify(options.openspecBridge.args), '-c', 'mcp_servers.specrails_openspec.default_tools_approval_mode="approve"', '-c', 'mcp_servers.specrails_openspec.required=true'] : []),
             ];
             // `codex exec resume` has no --sandbox flag; the same policy travels as a config override.
             if (resume)
-                return { command: 'codex', stdin: request.prompt, args: ['exec', 'resume', ...common, '-c', `sandbox_mode="${sandbox}"`, '-c', 'sandbox_workspace_write.writable_roots=' + JSON.stringify(readOnly ? [] : request.allowedRoots), resume, '-'] };
+                return { command: 'codex', stdin: request.prompt, args: ['exec', 'resume', ...common, '-c', `sandbox_mode="${sandbox}"`, ...(readOnly ? ['-c', 'sandbox_workspace_write.writable_roots=[]'] : []), resume, '-'] };
             return { command: 'codex', stdin: request.prompt, args: [
                     'exec', ...common, '--sandbox', sandbox,
                     ...(options.codexSchemaFile ? ['--output-schema', options.codexSchemaFile] : []),

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

@@ -10,7 +10,7 @@ export declare function runtimeFailure(error: unknown): {
     };
 };
 /** Machine operations are mirrored in integration-contract.json; help is presentation-only. */
-export declare const RUNTIME_CLI_OPERATIONS: readonly ["api", "validate", "run", "status", "resume", "prompts", "capabilities", "evidence", "recovery", "evaluate", "workflows", "fork", "signal", "cancel", "help"];
+export declare const RUNTIME_CLI_OPERATIONS: readonly ["api", "validate", "run", "status", "resume", "prompts", "capabilities", "evidence", "recovery", "evaluate", "workflows", "fork", "signal", "cancel", "host", "help"];
 /** The host-facing summary: phase status, pending interrupts and usage without accumulated outputs. */
 export declare function compactState(state: WorkflowState | null): {
     runId: string;

package/dist/agent-runtime/cli.js

@@ -18,14 +18,58 @@ import { configuredCapabilities } from './capabilities.js';
 import { createExecutorRegistry } from './executors.js';
 import { runRecovery } from './recovery.js';
 import { EngineError } from './engine/contracts.js';
+/**
+ * Long-lived agent session host (docs/agent-sessions/protocol.md). Loaded lazily
+ * so batch operations never initialize session drivers or the journal.
+ */
+async function runSessionHost(flags) {
+    if (flags.stdio !== true)
+        throw new Error('runtime host requires --stdio');
+    if (flags.scope !== undefined && typeof flags.scope !== 'string')
+        throw new Error('--scope requires a value');
+    const [{ createSessionRuntime, GLOBAL_SESSION_SCOPE }, { SessionHost }, { CliExecutor }] = await Promise.all([
+        import('./session/index.js'),
+        import('./session/host/server.js'),
+        import('./cli-executor.js'),
+    ]);
+    const scope = flags.scope ?? GLOBAL_SESSION_SCOPE;
+    let host = null;
+    const runtime = await createSessionRuntime({
+        scope,
+        drivers: {
+            executors: [
+                { id: 'gemini', displayName: 'Gemini CLI', executor: new CliExecutor('gemini') },
+                { id: 'kimi', displayName: 'Kimi Code', executor: new CliExecutor('kimi') },
+            ],
+        },
+        onLeaseLost: () => host?.leaseLost(),
+    });
+    host = new SessionHost({ service: runtime.service, scope, identity: { ...coreRuntimeIdentity(), coreVersion: CORE_PACKAGE_VERSION }, close: () => runtime.close() }, { input: process.stdin, output: process.stdout });
+    const stop = () => { void host?.stop(); };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    try {
+        await host.start();
+        return 0;
+    }
+    finally {
+        process.off('SIGINT', stop);
+        process.off('SIGTERM', stop);
+        // A stopped host must not be kept alive by its still-open stdin pipe.
+        process.stdin.destroy();
+    }
+}
 /** Both runtime entry points emit the same machine-readable fatal result. */
 export function runtimeFailure(error) {
     return { type: 'runtime-result', status: 'failed', error: error instanceof EngineError
             ? { code: error.code, message: error.message, ...(error.details === undefined ? {} : { details: error.details }) }
-            : error instanceof Error ? error.message : String(error) };
+            // Session errors keep their code so hosts can react (e.g. `journal_locked` must not be retried).
+            : error instanceof Error && error.name === 'SessionError' && typeof error.code === 'string'
+                ? { code: error.code, message: error.message }
+                : error instanceof Error ? error.message : String(error) };
 }
 /** Machine operations are mirrored in integration-contract.json; help is presentation-only. */
-export const RUNTIME_CLI_OPERATIONS = ['api', 'validate', 'run', 'status', 'resume', 'prompts', 'capabilities', 'evidence', 'recovery', 'evaluate', 'workflows', 'fork', 'signal', 'cancel', 'help'];
+export const RUNTIME_CLI_OPERATIONS = ['api', 'validate', 'run', 'status', 'resume', 'prompts', 'capabilities', 'evidence', 'recovery', 'evaluate', 'workflows', 'fork', 'signal', 'cancel', 'host', 'help'];
 function read(file) { return JSON.parse(readFileSync(file, 'utf8')); }
 async function readStdin() {
     const chunks = [];
@@ -150,6 +194,7 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
                 'specrails-core runtime fork --context <json> --from <nodePath> --run-id <newRunId> [--scope-id <scope>] [--visit <number>] [--state <json>]',
                 'specrails-core runtime signal --context <json> --stdin [--request-id <id>]',
                 'specrails-core runtime cancel --context <json> [--request-id <id>]',
+                'specrails-core runtime host --stdio [--scope <projectKey|global>]',
             ] });
         return 0;
     }
@@ -158,9 +203,11 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
         emit({ type: 'runtime-api', apiVersion: RUNTIME_API_VERSION, coreVersion: CORE_PACKAGE_VERSION, runtimeIdentity: coreRuntimeIdentity(), workflowVersions: [CORE_WORKFLOW_VERSION],
             engineVersion: 2, engines: RUNTIME_ENGINES, nodeKindsVersion: NODE_KINDS_VERSION, nodeKinds: validationPieceRegistry().kinds(),
             capabilities: { openRoles: 1, scopedRecovery: 1, efficientRoleExecution: 1, reproducibleVerification: 1, implementationEfficiencyMetrics: 1, compactAgentLoop: 1, configurableGuardrails: 1, compactOutputBudget: 1, roleThinkingControl: 1, repositoryScope: 1,
-                engineV2: 1, workflowAgentSteps: 1, implementationSteps: 1, workflowDefinitions: 1, fanOut: 1, fork: 1, forkIdempotency: 1, steeringInbox: 1, hostBlockers: 1, setupCommands: 1 }, guardrails: GUARDRAIL_CATALOG });
+                engineV2: 1, workflowAgentSteps: 1, implementationSteps: 1, workflowDefinitions: 1, fanOut: 1, fork: 1, forkIdempotency: 1, steeringInbox: 1, hostBlockers: 1, setupCommands: 1, sessions: 1 }, guardrails: GUARDRAIL_CATALOG });
         return 0;
     }
+    if (command === 'host')
+        return runSessionHost(flags);
     if (command === 'validate') {
         if (flags.stdin !== undefined && flags.stdin !== true)
             throw new Error('--stdin is a boolean flag');

package/dist/agent-runtime/compact/environment.d.ts

@@ -47,7 +47,7 @@ export declare function missingNodeDependencies(root: string): string[];
 /** The installs a repository root needs, judged from its manifests and the absence of their install output. */
 export declare function plannedInstalls(root: string, failureOutput?: string): EnvironmentInstall[];
 /** Runs each planned install once, bounded; never throws. */
-export declare function installEnvironment(roots: readonly string[], io?: {
+export interface InstallIo {
     spawn?: typeof spawnSync;
     timeoutMs?: number;
     failureOutput?: string;
@@ -58,7 +58,35 @@ export declare function installEnvironment(roots: readonly string[], io?: {
         detail?: string;
         text?: string;
     }) => void;
-}): InstallOutcome[];
+    /** The installs for one root; the failure-driven plan by default. */
+    plan?: (root: string) => EnvironmentInstall[];
+}
+export declare function installEnvironment(roots: readonly string[], io?: InstallIo): InstallOutcome[];
+type PlaywrightBrowser = 'chromium' | 'firefox' | 'webkit';
+/** Browsers the repository's Playwright config runs (by project names, devices or browserName); chromium when it names none. */
+export declare function configuredPlaywrightBrowsers(root: string): PlaywrightBrowser[];
+/**
+ * The configured browsers when any build the installed Playwright pins is
+ * missing from the host cache. `install --dry-run` names the exact install
+ * locations without downloading; an unreadable answer means "unknown", never
+ * an install.
+ */
+export declare function missingPlaywrightBrowsers(root: string, spawn?: typeof spawnSync): PlaywrightBrowser[];
+/**
+ * Host preparation before an agent edits a repository: the dependencies its
+ * manifest declares but are not installed, then the browser builds its
+ * Playwright pins. Agents run sandboxed (Codex cannot write the browser cache
+ * or reach it at all), so what they need must already be there. Only cheap,
+ * idempotent, project-local work happens here; other ecosystems keep their
+ * failure-driven repair at verification.
+ */
+export declare function prepareEnvironment(roots: readonly string[], io?: Omit<InstallIo, 'plan' | 'failureOutput'>): InstallOutcome[];
+/**
+ * A Node preload that answers IPv6 lookups with nothing when the host has an
+ * IPv4 address, so dual-stack clients connect over IPv4. Written once to the
+ * temp directory; undefined when it cannot be written.
+ */
+export declare function ipv4FirstPreload(): string | undefined;
 /** The repository's own test command, judged from its manifest (npm/pnpm/yarn `test` script, pytest, go, cargo); undefined when none. */
 export declare function detectCheckCommand(root: string): {
     command: string;

package/dist/agent-runtime/compact/environment.js

@@ -1,5 +1,6 @@
 import crossSpawn from 'cross-spawn';
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
 // npm/pnpm/yarn are `.cmd` shims on Windows: a bare `spawnSync('npm')` is
 // ENOENT there, which read as an environment failure of its own and sent the
@@ -208,12 +209,11 @@ function relaxManifestPin(root, name, version) {
         writeFileSync(file, JSON.stringify(manifest, null, 2) + '\n');
     return changed;
 }
-/** Runs each planned install once, bounded; never throws. */
 export function installEnvironment(roots, io = {}) {
     const spawn = io.spawn ?? defaultSpawn;
     const outcomes = [];
     for (const root of roots) {
-        for (const plan of plannedInstalls(root, io.failureOutput ?? '')) {
+        for (const plan of io.plan ? io.plan(root) : plannedInstalls(root, io.failureOutput ?? '')) {
             io.onEvent?.({ kind: 'tool-start', tool: plan.command, detail: `${plan.args.join(' ')} (${path.basename(root)})` });
             const run = () => {
                 try {
@@ -245,6 +245,21 @@ export function installEnvironment(roots, io = {}) {
                 io.onEvent?.({ kind: 'text', text: `Environment: ${unpublished[1]}@${unpublished[2]} is not published; relaxed the pin in package.json and retrying ${plan.command} ${plan.args.join(' ')}` });
                 result = run();
             }
+            // Playwright's downloader tries IPv6 first; on a host whose DNS returns
+            // an AAAA record without an IPv6 route, Node's family auto-selection
+            // times the request out before IPv4 is tried. Retry once preferring IPv4.
+            if (result.status !== 0 && plan.installs?.startsWith('Playwright') && NETWORK_TIMEOUT.test(`${result.stdout ?? ''}\n${result.stderr ?? ''}`)) {
+                const preload = ipv4FirstPreload();
+                if (preload) {
+                    io.onEvent?.({ kind: 'text', text: `Environment: the browser download timed out; retrying ${plan.command} ${plan.args.join(' ')} over IPv4` });
+                    try {
+                        result = spawn(plan.command, plan.args, { cwd: root, encoding: 'utf8', timeout: plan.timeoutMs ?? io.timeoutMs ?? 5 * 60_000, windowsHide: true, env: { ...process.env, NODE_OPTIONS: `${process.env.NODE_OPTIONS ?? ''} --require ${JSON.stringify(preload)}`.trim() } });
+                    }
+                    catch (error) {
+                        result = { status: null, error: error, stdout: '', stderr: '', pid: 0, output: [], signal: null };
+                    }
+                }
+            }
             io.onEvent?.({ kind: 'tool-end', tool: plan.command });
             const ok = result.status === 0;
             const detail = ok ? `installed ${plan.installs ?? `${plan.ecosystem} dependencies`} in ${path.basename(root)}` : `${plan.command} ${plan.args.join(' ')} failed in ${path.basename(root)}: ${String(result.stderr || result.error?.message || `exit ${result.status}`).trim().slice(0, 400)}`;
@@ -255,6 +270,109 @@ export function installEnvironment(roots, io = {}) {
     }
     return outcomes;
 }
+const PLAYWRIGHT_CONFIGS = ['playwright.config.ts', 'playwright.config.mts', 'playwright.config.cts', 'playwright.config.js', 'playwright.config.mjs', 'playwright.config.cjs'];
+/** Browsers the repository's Playwright config runs (by project names, devices or browserName); chromium when it names none. */
+export function configuredPlaywrightBrowsers(root) {
+    const file = PLAYWRIGHT_CONFIGS.map(name => path.join(root, name)).find(candidate => existsSync(candidate));
+    let source = '';
+    try {
+        if (file)
+            source = readFileSync(file, 'utf8').slice(0, 200_000);
+    }
+    catch { /* unreadable config: the default browser */ }
+    const browsers = [];
+    if (/\b(?:chromium|chrome|edge|pixel|galaxy)\b/i.test(source))
+        browsers.push('chromium');
+    if (/\bfirefox\b/i.test(source))
+        browsers.push('firefox');
+    if (/\b(?:webkit|safari|iphone|ipad)\b/i.test(source))
+        browsers.push('webkit');
+    return browsers.length ? browsers : ['chromium'];
+}
+/** How to run the repository's own Playwright CLI; undefined until its package is installed (never downloads one). */
+function playwrightCli(root) {
+    const bin = path.join(root, 'node_modules', '.bin');
+    if (!['playwright', 'playwright.cmd'].some(name => existsSync(path.join(bin, name))))
+        return undefined;
+    if (existsSync(path.join(root, 'pnpm-lock.yaml')))
+        return { command: 'pnpm', args: ['exec', 'playwright'] };
+    if (existsSync(path.join(root, 'yarn.lock')))
+        return { command: 'yarn', args: ['playwright'] };
+    return { command: 'npx', args: ['--no', 'playwright'] };
+}
+/**
+ * The configured browsers when any build the installed Playwright pins is
+ * missing from the host cache. `install --dry-run` names the exact install
+ * locations without downloading; an unreadable answer means "unknown", never
+ * an install.
+ */
+export function missingPlaywrightBrowsers(root, spawn = defaultSpawn) {
+    if (!declaresPlaywright(root))
+        return [];
+    const cli = playwrightCli(root);
+    if (!cli)
+        return [];
+    const browsers = configuredPlaywrightBrowsers(root);
+    let result;
+    try {
+        result = spawn(cli.command, [...cli.args, 'install', '--dry-run', ...browsers], { cwd: root, encoding: 'utf8', timeout: 30_000, windowsHide: true, env: process.env });
+    }
+    catch {
+        return [];
+    }
+    if (result.status !== 0)
+        return [];
+    const locations = [...String(result.stdout ?? '').matchAll(/Install location:\s+(.+?)\s*$/gm)].map(match => match[1]);
+    return locations.length && locations.some(location => !existsSync(location)) ? browsers : [];
+}
+/**
+ * Host preparation before an agent edits a repository: the dependencies its
+ * manifest declares but are not installed, then the browser builds its
+ * Playwright pins. Agents run sandboxed (Codex cannot write the browser cache
+ * or reach it at all), so what they need must already be there. Only cheap,
+ * idempotent, project-local work happens here; other ecosystems keep their
+ * failure-driven repair at verification.
+ */
+export function prepareEnvironment(roots, io = {}) {
+    const spawn = io.spawn ?? defaultSpawn;
+    const dependencies = installEnvironment(roots, { ...io, plan: root => plannedInstalls(root).filter(plan => plan.ecosystem === 'node') });
+    const browsers = installEnvironment(roots, { ...io, plan: root => {
+            const missing = missingPlaywrightBrowsers(root, spawn);
+            const cli = missing.length ? playwrightCli(root) : undefined;
+            return cli ? [{ ecosystem: 'node', root, command: cli.command, args: [...cli.args, 'install', ...missing], timeoutMs: PLAYWRIGHT_INSTALL_TIMEOUT_MS, installs: `Playwright ${missing.join(', ')}` }] : [];
+        } });
+    return [...dependencies, ...browsers];
+}
+const NETWORK_TIMEOUT = /timed out after \d+ ?ms|ETIMEDOUT|ENETUNREACH|EHOSTUNREACH/i;
+/**
+ * A Node preload that answers IPv6 lookups with nothing when the host has an
+ * IPv4 address, so dual-stack clients connect over IPv4. Written once to the
+ * temp directory; undefined when it cannot be written.
+ */
+export function ipv4FirstPreload() {
+    const file = path.join(tmpdir(), 'specrails-ipv4-first-v1.cjs');
+    if (existsSync(file))
+        return file;
+    try {
+        writeFileSync(file, [
+            "const dns = require('node:dns')",
+            'const lookup = dns.promises.lookup.bind(dns.promises)',
+            'dns.promises.lookup = async (hostname, options) => {',
+            "  const family = typeof options === 'number' ? options : options && options.family",
+            '  if (family === 6) {',
+            '    const v4 = await lookup(hostname, { all: true, family: 4 }).catch(() => [])',
+            "    if (v4.length) { if (options && typeof options === 'object' && options.all) return []; throw Object.assign(new Error('IPv6 skipped: ' + hostname), { code: 'ENOTFOUND' }) }",
+            '  }',
+            '  return lookup(hostname, options)',
+            '}',
+            '',
+        ].join('\n'));
+        return file;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** The repository's own test command, judged from its manifest (npm/pnpm/yarn `test` script, pytest, go, cargo); undefined when none. */
 export function detectCheckCommand(root) {
     const has = (file) => existsSync(path.join(root, file));

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

@@ -1,7 +1,12 @@
+import { type InstallOutcome } from '../../compact/environment.js';
 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;
+    /** Set on the single rerun after the host repaired an environment blocker the agent reported. */
+    environmentRetry?: {
+        installs: InstallOutcome[];
+    };
 }): Promise<PieceResult>;

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,7 +56,7 @@ 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 result = await invoke(roleId, deps.stepContext(context), { prompt: previous ? task : full, ...(previous ? { resumeSessionId: previous, fallbackPrompt: full } : {}),
@@ -60,6 +71,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 +97,43 @@ 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 } } : {}) };
 }
+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/verify.js

@@ -1,3 +1,4 @@
+import { admitVerificationProposals } from '../../verification-proposals.js';
 import { stripVTControlCharacters } from 'node:util';
 import { contentDigest } from '../canonical-json.js';
 import { advisoryMemory } from './project-memory.js';
@@ -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;
 }