prismatica 0.2.0

package/dist/agent-runner.js

@@ -0,0 +1,656 @@
+/**
+ * The safe runner for an INSTALLED agent CLI.
+ *
+ * This is not an LLM client. Prismatica imports no LLM SDK, holds no API key,
+ * and reads no transcript (src/safety/no-llm-imports.test.ts enforces that
+ * forever). What this module does is exactly what `open` already does — shell
+ * out to a CLI the owner installed and is already paying for — with three
+ * additions that the Planner role needs and an interactive session does not:
+ *
+ *  1. a read-only, non-persisting mode, so a planning run cannot edit the repo
+ *     or leave a resumable session behind;
+ *  2. a declared JSON Schema, so the answer arrives as one structured document
+ *     instead of prose we would have to parse loosely;
+ *  3. capability detection that FAILS CLOSED — if the installed version does
+ *     not advertise the exact flags we depend on, we refuse and hand the owner
+ *     the copy/import fallback rather than inventing brittle flags.
+ *
+ * Everything the agent returns is UNTRUSTED. This module only guarantees the
+ * bytes came back and parse as JSON; `planning/validate.ts` decides whether
+ * their CONTENT may be acted on. Nothing here ever executes a string the agent
+ * produced.
+ *
+ * The flags below were read from the live CLIs' own `--help` output, not from
+ * memory — see DECISIONS.md "Installed-agent adapters".
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execa } from 'execa';
+import { agentExecutorEnv } from './executor.js';
+import { getAdapter, resolveTuning } from './skills.js';
+export const PLANNER_AGENTS = ['claude', 'codex'];
+export function isPlannerAgent(value) {
+    return PLANNER_AGENTS.includes(value);
+}
+/** The real executor. `shell` is never enabled — args are passed as a vector. */
+export const spawnExecutor = async (file, args, options) => {
+    const result = await execa(file, args, {
+        cwd: options.cwd,
+        timeout: options.timeoutMs,
+        // execa refuses both at once, so exactly one is ever passed.
+        ...(options.input === undefined ? { stdin: options.stdin } : { input: options.input }),
+        reject: false,
+        // Explicitly not a shell: no string is ever interpreted, so nothing the
+        // agent (or a pack) contains can become a command.
+        shell: false,
+        // The Planner is read-only and non-persisting and could not amend anyway,
+        // but every agent Prismatica launches carries the same marker — a launch
+        // site that forgets it is how the guard quietly stops covering something.
+        env: agentExecutorEnv(),
+        extendEnv: true,
+    });
+    return {
+        exitCode: result.exitCode ?? 1,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        timedOut: result.timedOut === true,
+    };
+};
+/**
+ * The Planner's budget. Unchanged, and deliberately so: raising a default
+ * because a run once took longer is how a ten-minute wait becomes a
+ * twenty-five-minute one for everybody. `--agent-timeout` is the honest
+ * alternative — the owner who knows this particular request is large says so
+ * for that run, and nobody else pays for it.
+ */
+export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const DURATION = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/;
+const DURATION_UNIT_MS = {
+    ms: 1,
+    s: 1000,
+    m: 60 * 1000,
+    h: 60 * 60 * 1000,
+};
+/**
+ * Parses `25m`, `900s`, `600000ms`, `2h` into milliseconds, or returns null.
+ *
+ * A UNIT is required. A bare `600` is genuinely ambiguous — ten minutes to one
+ * reader, six-tenths of a second to another — and silently choosing either
+ * meaning would produce a budget the owner did not ask for, which is the one
+ * outcome this option exists to prevent.
+ */
+export function parseDuration(value) {
+    const match = DURATION.exec(value.trim().toLowerCase());
+    if (!match) {
+        return null;
+    }
+    const raw = Number.parseFloat(match[1]) * DURATION_UNIT_MS[match[2]];
+    if (!Number.isFinite(raw) || raw <= 0) {
+        return null;
+    }
+    const ms = Math.round(raw);
+    return ms >= 1 ? ms : null;
+}
+/** A duration as the owner would say it: `10m`, `1m 30s`, `45s`. */
+export function formatDuration(ms) {
+    if (ms < 1000) {
+        return `${Math.round(ms)}ms`;
+    }
+    const seconds = Math.round(ms / 1000);
+    if (seconds < 60) {
+        return `${seconds}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const rest = seconds % 60;
+    return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`;
+}
+// ── Capability detection ─────────────────────────────────────────────────────
+/**
+ * The flags each adapter genuinely depends on. Detection asks the installed
+ * binary for its own help and requires every one of these to appear; a version
+ * that lacks any of them is `unsupported`, never "try it and hope".
+ */
+const REQUIRED_FLAGS = {
+    claude: {
+        helpArgs: ['--help'],
+        flags: [
+            '--print',
+            '--output-format',
+            '--json-schema',
+            '--permission-mode',
+            '--no-session-persistence',
+        ],
+    },
+    codex: {
+        helpArgs: ['exec', '--help'],
+        // Every flag the codex invocation below actually passes — including
+        // `--color`, which was previously invoked without being detected. "Fails
+        // closed" is only true if the list here and the argv there are the same
+        // list; `-C` is absent from both because the process `cwd` already sets it.
+        flags: [
+            '--sandbox',
+            '--output-schema',
+            '--output-last-message',
+            '--ephemeral',
+            '--skip-git-repo-check',
+            '--color',
+        ],
+    },
+};
+export async function detectAgentCapability(agent, options) {
+    const execute = options.execute ?? spawnExecutor;
+    const base = REQUIRED_FLAGS[agent];
+    const spec = {
+        helpArgs: base.helpArgs,
+        flags: [...new Set([...base.flags, ...(options.extraFlags ?? [])])],
+    };
+    let result;
+    try {
+        result = await execute(agent, spec.helpArgs, {
+            cwd: options.cwd,
+            timeoutMs: options.timeoutMs ?? 30_000,
+        });
+    }
+    catch (error) {
+        return {
+            agent,
+            status: 'not-installed',
+            detail: `could not run "${agent}" (${error instanceof Error ? error.message.split('\n')[0] : String(error)})`,
+            missingFlags: spec.flags,
+        };
+    }
+    if (result.exitCode !== 0) {
+        return {
+            agent,
+            status: 'not-installed',
+            detail: `"${agent} ${spec.helpArgs.join(' ')}" exited ${result.exitCode}`,
+            missingFlags: spec.flags,
+        };
+    }
+    const help = `${result.stdout}\n${result.stderr}`;
+    const missingFlags = spec.flags.filter((flag) => !help.includes(flag));
+    if (missingFlags.length > 0) {
+        return {
+            agent,
+            status: 'unsupported',
+            detail: `the installed ${agent} does not advertise ${missingFlags.join(', ')}`,
+            missingFlags,
+        };
+    }
+    return {
+        agent,
+        status: 'ready',
+        detail: `${agent} supports structured read-only planning`,
+        missingFlags: [],
+    };
+}
+/**
+ * Claude's `--output-format json` wraps the answer in a result envelope. We
+ * accept either the envelope's `result` (a JSON string or an object, depending
+ * on version) or a bare document — and treat anything else as malformed rather
+ * than guessing.
+ */
+function unwrapClaudeOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (trimmed === '') {
+        return { error: 'the agent printed nothing' };
+    }
+    let envelope;
+    try {
+        envelope = JSON.parse(trimmed);
+    }
+    catch {
+        return { error: 'the agent did not print valid JSON' };
+    }
+    if (envelope !== null && typeof envelope === 'object' && 'result' in envelope) {
+        const inner = envelope.result;
+        if (typeof inner === 'string') {
+            try {
+                return { value: JSON.parse(inner) };
+            }
+            catch {
+                return { error: 'the agent returned prose where a structured document was required' };
+            }
+        }
+        if (inner !== null && typeof inner === 'object') {
+            return { value: inner };
+        }
+        return { error: 'the agent returned an empty result' };
+    }
+    if (typeof envelope === 'object' && envelope !== null) {
+        return { value: envelope };
+    }
+    return { error: 'the agent returned a JSON value that is not a document' };
+}
+/**
+ * Claude's `--json-schema` rejects the top-level Draft 2020-12 `$schema`
+ * declaration Zod emits, while accepting everything under it. This drops that
+ * ONE key into a shallow copy: the caller's object is never mutated, and a
+ * shallow rest cannot reach — let alone remove — a nested `$schema` or any
+ * other constraint. Codex keeps the original, untouched.
+ */
+function claudeSchema(schema) {
+    if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) {
+        return schema;
+    }
+    const { $schema: _dropped, ...rest } = schema;
+    return rest;
+}
+/**
+ * Codex's structured-output transport requires EVERY declared property of every
+ * object to appear in `required`. The planning schemas are full of genuinely
+ * optional and defaulted fields (11 such object nodes in Start, 9 in Refresh),
+ * so the real generated schemas were refused before planning even began.
+ *
+ * The fix belongs here and only here. `planning/schema.ts` stays authoritative
+ * and untouched — tailoring the semantic schema to one provider would make the
+ * shape we ACCEPT a function of the shape one CLI happens to want, and a second
+ * hand-written schema would drift from the first the week after it was written.
+ * This is transport, not meaning: what comes back is re-parsed against the
+ * unchanged zod schema, and that parse is still the only thing that decides.
+ *
+ * The conversion is: require every declared property, and express the ones that
+ * were NOT required as "or null". Every other constraint is carried through
+ * untouched, and the caller's object is never mutated.
+ */
+function codexSchema(schema) {
+    const convert = (node) => {
+        if (node === null || typeof node !== 'object') {
+            return node;
+        }
+        if (Array.isArray(node)) {
+            return node.map(convert);
+        }
+        const source = node;
+        const declared = source.properties;
+        const required = new Set(Array.isArray(source.required) ? source.required : []);
+        const out = {};
+        for (const [key, value] of Object.entries(source)) {
+            if (key === 'properties') {
+                // A property MAP, not a schema: its values are subschemas and its keys
+                // are names, so it is never fed to `convert` as a node of its own.
+                const converted = {};
+                for (const [name, sub] of Object.entries(declared)) {
+                    converted[name] = required.has(name) ? convert(sub) : nullable(convert(sub));
+                }
+                out.properties = converted;
+            }
+            else {
+                out[key] = convert(value);
+            }
+        }
+        if (declared) {
+            out.required = Object.keys(declared);
+        }
+        return out;
+    };
+    return convert(schema);
+}
+/**
+ * "This, or null" — as an `anyOf`, never as `type: ['string', 'null']`.
+ *
+ * The type-union form looks equivalent and is not: `enum` and `const` are
+ * equality tests that reject null whatever `type` says. Both real schemas carry
+ * exactly that case — `variations[].status` is an optional `FlowStatus` enum —
+ * so the type-union form would hand Codex a property it MUST emit and that no
+ * value it could emit satisfies. One mechanism for every kind of node is also
+ * one mechanism to get right.
+ *
+ * `default` is hoisted out to sit beside the union: it is an annotation about
+ * the property, not a constraint on either branch.
+ */
+function nullable(node) {
+    const { default: fallback, ...rest } = (node ?? {});
+    const union = { anyOf: [rest, { type: 'null' }] };
+    return fallback === undefined ? union : { default: fallback, ...union };
+}
+/**
+ * Whether any node in the schema gives `null` a meaning of its OWN.
+ *
+ * This is the precondition for everything above. The conversion spends `null`
+ * as the wire spelling of "absent", and `dropTransportNulls` spends it again on
+ * the way back — both of which are only safe while `null` means nothing else.
+ * The moment a semantic schema declares a legitimate null, a returned null is
+ * ambiguous, and the honest answer is to refuse the provider rather than guess
+ * which of the two meanings was intended. Neither real schema declares one
+ * today; this is what keeps that true rather than assuming it.
+ *
+ * A deep walk over every value, so a null tucked inside `items`, a branch of an
+ * `anyOf`, or any keyword added later is still found.
+ */
+function declaresNull(node) {
+    if (node === null || typeof node !== 'object') {
+        return false;
+    }
+    if (Array.isArray(node)) {
+        return node.some(declaresNull);
+    }
+    const source = node;
+    if (source.type === 'null' || (Array.isArray(source.type) && source.type.includes('null'))) {
+        return true;
+    }
+    if ('const' in source && source.const === null) {
+        return true;
+    }
+    if (Array.isArray(source.enum) && source.enum.includes(null)) {
+        return true;
+    }
+    return Object.values(source).some(declaresNull);
+}
+/**
+ * Undoes the transport, and nothing else: a property `codexSchema` made
+ * nullable — declared on THIS object node and absent from ITS `required` list —
+ * whose value came back `null` is the wire spelling of "I am not sending this
+ * one", so the KEY is dropped and the unchanged zod schema then applies its own
+ * `.optional()` or `.default()` exactly as it would for a claude answer that
+ * simply omitted it.
+ *
+ * SCHEMA-AWARE, and that is the whole guard. Dropping every null-valued key
+ * regardless of the schema deletes keys the schema never declared, so a hostile
+ * `{ invented: null }` was normalised away and the strict zod parse — whose one
+ * job at that boundary is to REJECT an unknown key — never saw it. A `null` at
+ * an undeclared key is nobody's transport encoding; it is precisely the
+ * malformed answer the local parse exists to refuse, and it now travels through
+ * unaltered at every depth. `Object.hasOwn`, never `key in`: the lookup is
+ * against the SCHEMA's `properties` map, an ordinary object whose prototype
+ * chain carries `toString` and `constructor`, so `in` would report those two
+ * names as declared and hide an answer's invented `toString: null` the same way.
+ *
+ * The schema walked is the ORIGINAL, never `codexSchema`'s conversion. The
+ * conversion puts EVERY declared property into `required`, so "declared and not
+ * required" — the one fact that made a `null` legal on the wire — is readable
+ * only here. The two halves must therefore agree, and `agent-runner.test.ts`
+ * pins that agreement by OBSERVING both over the real schemas: nullability is
+ * read off the wire schema codex was actually handed, the drop is the real
+ * decode running, and one declared property is nulled per run so every one is
+ * exercised. A single wholly-null document could not do it — sending
+ * `plannedFlow: null` destroys the node you must descend through to reach
+ * `plannedFlow.truth.steps[0].assumes`.
+ *
+ * Deliberately narrow everywhere else, and it fails closed. A `null` on a
+ * REQUIRED property is kept — the conversion never made that one nullable, so
+ * it is the agent contradicting the schema. A `null` ELEMENT of an array is
+ * left exactly where it is, because no optional-property encoding put it there
+ * and removing it would be repairing a malformed answer rather than decoding a
+ * well-formed one. Where the schema says nothing about a position — no node, no
+ * `properties`, no `items` — the value is returned untouched for the parse to
+ * judge. An unknown key, a wrong type and a malformed value all travel through
+ * unaltered to be rejected locally, which is where rejection belongs.
+ *
+ * The object is copied by SPREAD and then pruned, never rebuilt into a fresh
+ * `{}`: `JSON.parse('{"__proto__":null}')` yields `__proto__` as a real own
+ * property, and writing that key into a fresh object literal hits
+ * `Object.prototype`'s setter and makes the key disappear — hiding an unknown
+ * key exactly as the null-blind drop did.
+ */
+function dropTransportNulls(value, schema) {
+    const node = schema !== null && typeof schema === 'object' && !Array.isArray(schema)
+        ? schema
+        : undefined;
+    if (Array.isArray(value)) {
+        return node?.items === undefined
+            ? value
+            : value.map((item) => dropTransportNulls(item, node.items));
+    }
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    const declared = node?.properties;
+    if (declared === null || typeof declared !== 'object') {
+        return value;
+    }
+    const required = new Set(Array.isArray(node?.required) ? node.required : []);
+    const out = { ...value };
+    for (const [key, item] of Object.entries(out)) {
+        if (!Object.hasOwn(declared, key)) {
+            continue;
+        }
+        if (item === null) {
+            if (!required.has(key)) {
+                delete out[key];
+            }
+        }
+        else {
+            out[key] = dropTransportNulls(item, declared[key]);
+        }
+    }
+    return out;
+}
+export async function runAgentJson(request) {
+    const { agent, cwd, prompt } = request;
+    const execute = request.execute ?? spawnExecutor;
+    const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    // Resolved before detection, so the flags this run will really pass are the
+    // flags detection insists the installed binary advertises.
+    const tuning = resolveTuning(agent, getAdapter(agent), request.tuning ?? {});
+    if (!tuning.ok) {
+        return { ok: false, agent, reason: 'unsupported', detail: `${tuning.problem} ${tuning.why}` };
+    }
+    // BEFORE LAUNCH — before even the capability probe, because no answer this
+    // provider could give would be decodable. Copy/import is unaffected: it runs
+    // no transport, and the unchanged zod schema is what validates it.
+    if (agent === 'codex' && declaresNull(request.schema)) {
+        return {
+            ok: false,
+            agent,
+            reason: 'schema-unsupported',
+            detail: 'this schema gives null a meaning of its own, and codex\'s transport spends null on "this optional property is absent" — a returned null could be either, and guessing is not an option',
+        };
+    }
+    const capability = await detectAgentCapability(agent, {
+        cwd,
+        execute,
+        extraFlags: tuning.detectFlags,
+    });
+    if (capability.status !== 'ready') {
+        return { ok: false, agent, reason: capability.status, detail: capability.detail };
+    }
+    const started = Date.now();
+    /**
+     * A finished-but-failed process, classified. TIMEOUT IS TESTED FIRST and on
+     * execa's own `timedOut`, never on the exit code: a killed process reports a
+     * non-zero exit like any other failure, so reading the code first told every
+     * owner whose Planner ran out of time that it "exited 1" — a message that
+     * suggests a broken install and hides the one fact that would have fixed it.
+     * Both branches carry the provider's actual output, so a real error is still
+     * in front of the owner either way.
+     */
+    const classifyFailure = (result) => result.timedOut
+        ? {
+            reason: 'timeout',
+            detail: `${agent} did not finish within its ${formatDuration(timeoutMs)} budget (stopped after ${formatDuration(Date.now() - started)}); last output: ${outputTail(result)}`,
+        }
+        : { reason: 'exit-code', detail: `exited ${result.exitCode}: ${outputTail(result)}` };
+    // One throwaway directory per run; removed in `finally` whatever happens, so
+    // no schema or answer file survives the command.
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), `prismatica-${agent}-`));
+    try {
+        const schemaFile = path.join(scratch, 'schema.json');
+        // Only codex reads this file, and only codex needs the transport rewrite;
+        // claude is handed `request.schema` inline, minus its top-level `$schema`.
+        fs.writeFileSync(schemaFile, JSON.stringify(agent === 'codex' ? codexSchema(request.schema) : request.schema));
+        let result;
+        let raw;
+        if (agent === 'codex') {
+            const outputFile = path.join(scratch, 'answer.json');
+            try {
+                result = await execute('codex', [
+                    'exec',
+                    // read-only: the planner may look, never write.
+                    '--sandbox',
+                    'read-only',
+                    // no session files left behind.
+                    '--ephemeral',
+                    '--skip-git-repo-check',
+                    '--color',
+                    'never',
+                    '--output-schema',
+                    schemaFile,
+                    '--output-last-message',
+                    outputFile,
+                    // Which model, and how hard it thinks — each value its own argv
+                    // element, resolved by the adapter that owns this provider's
+                    // dialect (`skills.ts`). Empty unless the owner asked.
+                    ...tuning.args,
+                    // No `-C`: the process is already spawned with this `cwd`, so a
+                    // second way of saying it would be one more flag to depend on for
+                    // nothing.
+                    prompt,
+                ], { cwd, timeoutMs, stdin: 'ignore' });
+            }
+            catch (error) {
+                return { ok: false, agent, reason: 'not-installed', detail: describe(error) };
+            }
+            if (result.exitCode !== 0) {
+                return { ok: false, agent, ...classifyFailure(result) };
+            }
+            if (!fs.existsSync(outputFile)) {
+                return { ok: false, agent, reason: 'empty', detail: 'the agent wrote no answer file' };
+            }
+            raw = fs.readFileSync(outputFile, 'utf8').trim();
+            if (raw === '') {
+                return {
+                    ok: false,
+                    agent,
+                    reason: 'empty',
+                    detail: 'the agent wrote an empty answer file',
+                };
+            }
+            try {
+                // `value` is decoded; `raw` stays exactly the bytes the provider wrote,
+                // so nothing downstream can be shown an answer the agent did not give.
+                return { ok: true, agent, value: dropTransportNulls(JSON.parse(raw), request.schema), raw };
+            }
+            catch {
+                return {
+                    ok: false,
+                    agent,
+                    reason: 'malformed',
+                    detail: 'the answer file was not valid JSON',
+                };
+            }
+        }
+        try {
+            result = await execute('claude', [
+                '--print',
+                '--output-format',
+                'json',
+                '--json-schema',
+                JSON.stringify(claudeSchema(request.schema)),
+                // plan mode: no WRITES — no edit, no file creation, no committed
+                // change. It is not a general execution block, and describing it as
+                // one would overstate it; what the Planner role needs is exactly
+                // that the repository cannot be modified, and that is what this
+                // gives.
+                '--permission-mode',
+                'plan',
+                '--no-session-persistence',
+                ...tuning.args,
+                prompt,
+            ], { cwd, timeoutMs, stdin: 'ignore' });
+        }
+        catch (error) {
+            return { ok: false, agent, reason: 'not-installed', detail: describe(error) };
+        }
+        if (result.exitCode !== 0) {
+            return { ok: false, agent, ...classifyFailure(result) };
+        }
+        raw = result.stdout.trim();
+        if (raw === '') {
+            return { ok: false, agent, reason: 'empty', detail: 'the agent printed nothing' };
+        }
+        const unwrapped = unwrapClaudeOutput(raw);
+        if ('error' in unwrapped) {
+            return { ok: false, agent, reason: 'malformed', detail: unwrapped.error };
+        }
+        return { ok: true, agent, value: unwrapped.value, raw };
+    }
+    finally {
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}
+function describe(error) {
+    return error instanceof Error ? error.message.split('\n')[0] : String(error);
+}
+/**
+ * The number of trailing characters of provider output a failure keeps.
+ * Generous enough for a real stack or usage message, small enough that a
+ * chatty CLI cannot flood the terminal.
+ */
+const MAX_OUTPUT_TAIL = 600;
+/**
+ * The ACTIONABLE end of what the provider printed.
+ *
+ * The tail, not the head: CLIs open with banners, update notices and progress
+ * chatter, so the first line was reliably the least useful one on the screen —
+ * an owner debugging a failed Planner run was shown a version string. The real
+ * error is what the process said last.
+ *
+ * `stderr` is preferred and `stdout` is the fallback, because a provider that
+ * writes its diagnostics to stdout would otherwise report "(no output)" while
+ * holding the explanation. Nothing is filtered by phrase: a list of known
+ * noise strings is a list that rots, and the one time it is wrong it discards
+ * the message the owner needed.
+ */
+function outputTail(result) {
+    const text = result.stderr.trim() || result.stdout.trim();
+    if (text === '') {
+        return '(no output)';
+    }
+    return text.length > MAX_OUTPUT_TAIL ? `…${text.slice(-MAX_OUTPUT_TAIL)}` : text;
+}
+// ── Waiting, honestly ────────────────────────────────────────────────────────
+/** How often the "still running" line repeats. Restrained on purpose — this is a wait, not a show. */
+const PROGRESS_INTERVAL_MS = 30_000;
+/**
+ * One start line, then a periodic elapsed-time line, while a provider runs.
+ * Returns the STOP function — call it in a `finally`, always.
+ *
+ * Three rules, all of them deliberate:
+ *
+ *  - **stderr, and only when stderr is a TTY.** Progress is for a person
+ *    watching a terminal. On a pipe, in CI, or with output being captured, it
+ *    is noise that corrupts whatever the caller is really collecting — and
+ *    stdout in particular must stay clean, since a caller may be reading it.
+ *  - **Process facts only.** Elapsed time and the budget. Nothing here reads,
+ *    streams, summarises or characterises anything the agent said; Prismatica
+ *    does not read agent output, and a progress line is not the place to start.
+ *  - **The timer is cleared unconditionally.** Success, failure, or a thrown
+ *    exception — a `finally` covers all three. A surviving interval would keep
+ *    printing over whatever the command wrote next, and keep the process alive
+ *    after its work is done; `unref` is a second belt for the same trousers.
+ */
+export function startAgentProgress(options) {
+    const stream = options.stream ?? process.stderr;
+    if (!stream.isTTY) {
+        return () => { };
+    }
+    const now = options.now ?? Date.now;
+    const started = now();
+    const budget = formatDuration(options.timeoutMs);
+    stream.write(`  … ${options.agent} is planning (read-only, no session kept) — up to ${budget}\n`);
+    const timer = setInterval(() => {
+        stream.write(`  … still running — ${formatDuration(now() - started)} of ${budget}\n`);
+    }, PROGRESS_INTERVAL_MS);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}
+/**
+ * The wording every caller uses when an adapter cannot run. Deliberately one
+ * sentence plus a fallback — an unavailable agent is a routine, recoverable
+ * state, not an error the owner has to debug.
+ */
+export function fallbackAdvice(agent, reason, detail) {
+    const cause = reason === 'not-installed'
+        ? `${agent} is not installed or could not run`
+        : reason === 'unsupported'
+            ? `this version of ${agent} cannot run a structured read-only plan`
+            : reason === 'schema-unsupported'
+                ? `${agent}'s structured-output transport cannot safely carry this planning schema`
+                : reason === 'timeout'
+                    ? `${agent} ran out of time before it finished planning`
+                    : `${agent} did not return a usable plan`;
+    return `${cause} (${detail}). Use the copy/import fallback instead.`;
+}
+//# sourceMappingURL=agent-runner.js.map