unfold-deploy 0.0.0-stage → 0.2.0

package/dist/providers/agents/claude.js

@@ -0,0 +1,205 @@
+import { UsageError } from '../../core/errors.js';
+import { agentFixHints, AGENT_NOTES, agentStages, CheckTracker, classifyCommand, oneLine, relPath } from './shared.js';
+const parse = (text) => {
+    if (!text.startsWith('{'))
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+const EXPLORE_TOOLS = new Set(['Read', 'Glob', 'Grep', 'LS', 'WebFetch', 'WebSearch', 'NotebookRead', 'Task', 'Agent', 'ToolSearch']);
+const CHANGE_TOOLS = new Set(['Edit', 'MultiEdit', 'Write', 'NotebookEdit']);
+function activity(name, input) {
+    if (name === 'Bash')
+        return classifyCommand(String(input.command ?? ''));
+    if (CHANGE_TOOLS.has(name))
+        return 'change';
+    if (EXPLORE_TOOLS.has(name) || name.startsWith('mcp__'))
+        return 'explore';
+    return undefined; // TodoWrite and other bookkeeping
+}
+function describe(name, input, cwd) {
+    const path = typeof input.file_path === 'string' ? relPath(input.file_path, cwd) : typeof input.notebook_path === 'string' ? relPath(input.notebook_path, cwd) : '';
+    switch (name) {
+        case 'Bash':
+            return `$ ${oneLine(String(input.command ?? ''), 140)}`;
+        case 'Read':
+            return `Read ${path}`;
+        case 'Edit':
+        case 'MultiEdit':
+            return `Edit ${path}`;
+        case 'Write':
+            return `Write ${path}`;
+        case 'NotebookEdit':
+            return `Edit ${path}`;
+        case 'Glob':
+            return `Find files ${String(input.pattern ?? '')}`;
+        case 'Grep':
+            return `Search for ${oneLine(String(input.pattern ?? ''), 60)}`;
+        case 'WebFetch':
+            return `Fetch ${String(input.url ?? '')}`;
+        case 'WebSearch':
+            return `Web search: ${oneLine(String(input.query ?? ''), 60)}`;
+        case 'Task':
+        case 'Agent':
+            return `Subagent: ${oneLine(String(input.description ?? input.prompt ?? ''), 60)}`;
+        default:
+            return name.startsWith('mcp__') ? `Tool ${name.slice(5).replace('__', '.')}` : name;
+    }
+}
+const resultText = (content) => typeof content === 'string' ? content : Array.isArray(content) ? content.map((c) => (typeof c === 'object' && c && 'text' in c ? String(c.text) : '')).join(' ') : '';
+export class ClaudeParser {
+    cwd;
+    pending = new Map();
+    checks = new CheckTracker();
+    feed(line) {
+        const e = parse(line.text.trim());
+        if (!e) {
+            // Plain text: Claude Code's own errors (bad flags, not logged in) land here.
+            const t = line.text.trim();
+            return /error|invalid|not logged in|unauthorized/i.test(t) ? [{ kind: 'error', severity: 'cause', stage: 'start', message: t }] : [];
+        }
+        const out = [];
+        if (e.type === 'system' && e.subtype === 'init') {
+            this.cwd = e.cwd;
+            if (e.claude_code_version)
+                out.push({ kind: 'fact', key: 'cliVersion', label: 'Claude Code', value: e.claude_code_version, stage: 'start' });
+            if (e.model)
+                out.push({ kind: 'fact', key: 'model', label: 'Model', value: e.model, stage: 'start' });
+            if (e.permissionMode)
+                out.push({ kind: 'fact', key: 'permissionMode', label: 'Permission mode', value: e.permissionMode, stage: 'start' });
+            out.push({ kind: 'stage', stage: 'start', status: 'confirmed', note: `Session started${e.model ? ` with ${e.model}` : ''}.` });
+            return out;
+        }
+        if (e.type === 'assistant') {
+            for (const b of e.message?.content ?? []) {
+                if (b.type !== 'tool_use' || !b.id || !b.name)
+                    continue;
+                const input = b.input ?? {};
+                const kind = activity(b.name, input);
+                this.pending.set(b.id, { name: b.name, input, kind });
+                if (kind)
+                    out.push({ kind: 'stage', stage: kind, status: 'active', note: describe(b.name, input, this.cwd) });
+            }
+            return out;
+        }
+        if (e.type === 'user') {
+            for (const b of e.message?.content ?? []) {
+                if (b.type !== 'tool_result' || !b.tool_use_id)
+                    continue;
+                const call = this.pending.get(b.tool_use_id);
+                if (!call?.kind)
+                    continue;
+                this.pending.delete(b.tool_use_id);
+                const what = describe(call.name, call.input, this.cwd);
+                if (call.kind === 'verify')
+                    this.checks.record(String(call.input.command ?? call.name), !b.is_error);
+                if (b.is_error) {
+                    const why = oneLine(resultText(b.content), 120);
+                    out.push({ kind: 'evidence', stage: call.kind, note: `Failed: ${what}${why ? ` (${why})` : ''}` });
+                    if (call.kind === 'verify')
+                        out.push({ kind: 'error', severity: 'cause', stage: 'verify', message: `${what}: ${why}`, priority: 1 });
+                }
+                else {
+                    if (call.kind === 'change' && typeof call.input.file_path === 'string')
+                        this.checks.changed.add(relPath(call.input.file_path, this.cwd));
+                    out.push({ kind: 'stage', stage: call.kind, status: 'confirmed', note: call.kind === 'verify' ? `Check passed: ${what.replace(/^\$ /, '')}` : what });
+                }
+            }
+            return out;
+        }
+        if (e.type === 'result') {
+            const secs = e.duration_ms !== undefined ? `${(e.duration_ms / 1000).toFixed(1)}s` : undefined;
+            if (e.total_cost_usd !== undefined)
+                out.push({ kind: 'fact', key: 'cost', label: 'Cost', value: `$${e.total_cost_usd.toFixed(2)}`, stage: 'done' });
+            if (e.num_turns !== undefined)
+                out.push({ kind: 'fact', key: 'turns', label: 'Turns', value: String(e.num_turns), stage: 'done' });
+            if (secs)
+                out.push({ kind: 'fact', key: 'duration', label: 'Duration', value: secs, stage: 'done' });
+            const denied = [...new Set((e.permission_denials ?? []).map((d) => d.tool_name).filter(Boolean))];
+            if (denied.length)
+                out.push({ kind: 'fact', key: 'denied', label: 'Permission denied', value: denied.join(', '), stage: 'done' });
+            if (e.subtype === 'success' && !e.is_error) {
+                if (e.result)
+                    out.push({ kind: 'fact', key: 'answer', label: 'Answer', value: oneLine(e.result, 300), stage: 'done' });
+                out.push({ kind: 'stage', stage: 'done', status: 'confirmed', note: `Finished${secs ? ` in ${secs}` : ''}${e.num_turns ? ` after ${e.num_turns} turns` : ''}.` });
+            }
+            else {
+                const reason = e.subtype === 'error_max_turns' ? 'It hit the maximum number of turns.' : oneLine(e.result || String(e.api_error_status ?? '') || e.subtype || 'The session ended with an error.', 200);
+                out.push({ kind: 'error', severity: 'fatal', stage: 'done', message: reason });
+            }
+            if (denied.length)
+                out.push({ kind: 'error', severity: 'cause', stage: 'done', message: `Permission denied for: ${denied.join(', ')}`, priority: 2 });
+        }
+        return out;
+    }
+    finish() {
+        return this.checks.finish();
+    }
+}
+/** Turns stream-json events into readable terminal lines. */
+export function claudePresenter() {
+    let cwd;
+    const calls = new Map();
+    return (raw) => {
+        const e = parse(raw.trim());
+        if (!e)
+            return raw.trim() ? raw : null;
+        if (e.type === 'system' && e.subtype === 'init') {
+            cwd = e.cwd;
+            return `● Claude Code ${e.claude_code_version ?? ''} · ${e.model ?? 'model'} · permission mode: ${e.permissionMode ?? 'default'}`;
+        }
+        if (e.type === 'assistant') {
+            const lines = [];
+            for (const b of e.message?.content ?? []) {
+                if (b.type === 'tool_use' && b.name) {
+                    const d = describe(b.name, b.input ?? {}, cwd);
+                    if (b.id)
+                        calls.set(b.id, d);
+                    if (b.name !== 'TodoWrite')
+                        lines.push(`  ${d.startsWith('$') ? d : `→ ${d}`}`);
+                }
+                else if (b.type === 'text' && b.text?.trim()) {
+                    lines.push(`› ${oneLine(b.text, 300)}`);
+                }
+            }
+            return lines.length ? lines.join('\n') : null;
+        }
+        if (e.type === 'user') {
+            const failed = (e.message?.content ?? []).filter((b) => b.type === 'tool_result' && b.is_error);
+            return failed.length ? failed.map((b) => `    ✗ ${oneLine(resultText(b.content), 140)}`).join('\n') : null;
+        }
+        if (e.type === 'result') {
+            const ok = e.subtype === 'success' && !e.is_error;
+            const bits = [e.duration_ms !== undefined ? `${(e.duration_ms / 1000).toFixed(1)}s` : '', e.num_turns ? `${e.num_turns} turns` : '', e.total_cost_usd !== undefined ? `$${e.total_cost_usd.toFixed(2)}` : ''].filter(Boolean);
+            return `■ ${ok ? 'Done' : `Failed (${e.subtype})`}${bits.length ? ` · ${bits.join(' · ')}` : ''}`;
+        }
+        return null; // hooks, rate limits, partial messages
+    };
+}
+export const claude = {
+    id: 'claude',
+    title: 'Claude Code task',
+    stages: agentStages('Claude Code', 'https://docs.claude.com/en/docs/claude-code/sdk/sdk-headless', 'Allow tools with `--allowedTools` (for example `--allowedTools Read Edit Bash`) or `--permission-mode acceptEdits`.'),
+    notes: { ...AGENT_NOTES, docsLabel: 'Claude Code docs' },
+    install: 'Install Claude Code (https://docs.claude.com/en/docs/claude-code), then run `claude` once to log in.',
+    maxLineLength: 2_000_000,
+    launch(userArgs) {
+        const args = userArgs.filter((a) => a !== '-p' && a !== '--print');
+        if (!args.some((a) => !a.startsWith('-'))) {
+            throw new UsageError('give Claude Code a task, for example: unfold claude "fix the failing test" --allowedTools Read Edit Bash');
+        }
+        const out = ['-p', ...args];
+        if (!args.some((a) => a.startsWith('--output-format')))
+            out.push('--output-format', 'stream-json');
+        if (!args.includes('--verbose'))
+            out.push('--verbose');
+        return { bin: process.env.UNFOLD_CLAUDE_BIN || 'claude', args: out };
+    },
+    createParser: () => new ClaudeParser(),
+    createPresenter: claudePresenter,
+    fixHints: (state) => agentFixHints(state, 'Allow it with `--allowedTools <tool>` or `--permission-mode acceptEdits`, or run the task interactively.'),
+};

package/dist/providers/agents/codex.js

@@ -0,0 +1,152 @@
+import { UsageError } from '../../core/errors.js';
+import { agentFixHints, AGENT_NOTES, agentStages, CheckTracker, classifyCommand, oneLine, relPath, unwrapShell } from './shared.js';
+const parse = (text) => {
+    if (!text.startsWith('{'))
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+const k = (n) => (n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n));
+function describeChanges(changes, cwd) {
+    return changes.map((c) => `${c.kind === 'add' ? 'add' : c.kind === 'delete' ? 'delete' : 'edit'} ${relPath(c.path, cwd)}`).join(', ');
+}
+export class CodexParser {
+    cwd;
+    checks = new CheckTracker();
+    constructor(cwd = process.cwd()) {
+        this.cwd = cwd;
+    }
+    feed(line) {
+        const e = parse(line.text.trim());
+        if (!e) {
+            const t = line.text.trim();
+            // Codex prints its own warnings and errors as plain text; MCP transport noise is not a task error.
+            return /^(error|fatal)\b|not logged in|unauthorized/i.test(t) && !/rmcp::|mcp/i.test(t) ? [{ kind: 'error', severity: 'cause', stage: 'start', message: t }] : [];
+        }
+        const it = e.item ?? {};
+        switch (e.type) {
+            case 'thread.started':
+                return [{ kind: 'stage', stage: 'start', status: 'confirmed', note: 'Session started.' }];
+            case 'item.started':
+                if (it.type === 'command_execution' && it.command) {
+                    const cmd = unwrapShell(it.command);
+                    return [{ kind: 'stage', stage: classifyCommand(cmd), status: 'active', note: `$ ${oneLine(cmd, 140)}` }];
+                }
+                if (it.type === 'file_change')
+                    return [{ kind: 'stage', stage: 'change', status: 'active', note: `Editing ${describeChanges(it.changes ?? [], this.cwd)}` }];
+                return [];
+            case 'item.completed':
+                return this.completed(it);
+            case 'turn.completed': {
+                const u = e.usage ?? {};
+                const out = [];
+                if (u.input_tokens !== undefined)
+                    out.push({ kind: 'fact', key: 'tokens', label: 'Tokens', value: `${k(u.input_tokens)} in (${k(u.cached_input_tokens ?? 0)} cached), ${k(u.output_tokens ?? 0)} out`, stage: 'done' });
+                out.push({ kind: 'stage', stage: 'done', status: 'confirmed', note: 'Finished the turn.' });
+                return out;
+            }
+            case 'turn.failed':
+                return [{ kind: 'error', severity: 'fatal', stage: 'done', message: e.error?.message ?? 'The turn failed.' }];
+            case 'error':
+                return [{ kind: 'error', severity: 'fatal', stage: 'done', message: e.message ?? e.error?.message ?? 'Codex reported an error.' }];
+            default:
+                return [];
+        }
+    }
+    completed(it) {
+        switch (it.type) {
+            case 'command_execution': {
+                const cmd = unwrapShell(it.command ?? '');
+                const kind = classifyCommand(cmd);
+                const ok = it.exit_code === 0 && it.status !== 'failed';
+                if (kind === 'verify')
+                    this.checks.record(cmd, ok);
+                if (ok)
+                    return [{ kind: 'stage', stage: kind, status: 'confirmed', note: kind === 'verify' ? `Check passed: ${oneLine(cmd, 100)}` : `$ ${oneLine(cmd, 140)}` }];
+                const out = [{ kind: 'evidence', stage: kind, note: `Failed (exit ${it.exit_code ?? '?'}): $ ${oneLine(cmd, 120)}` }];
+                if (kind === 'verify') {
+                    const tail = oneLine((it.aggregated_output ?? '').trim().split('\n').slice(-3).join(' '), 160);
+                    out.push({ kind: 'error', severity: 'cause', stage: 'verify', message: `${oneLine(cmd, 80)} exited with ${it.exit_code ?? '?'}${tail ? `: ${tail}` : ''}`, priority: 2 });
+                }
+                return out;
+            }
+            case 'file_change': {
+                const changes = it.changes ?? [];
+                if (it.status === 'failed')
+                    return [{ kind: 'evidence', stage: 'change', note: `Failed to change ${describeChanges(changes, this.cwd)}` }];
+                for (const c of changes)
+                    this.checks.changed.add(relPath(c.path, this.cwd));
+                return [{ kind: 'stage', stage: 'change', status: 'confirmed', note: `Changed: ${describeChanges(changes, this.cwd)}` }];
+            }
+            case 'mcp_tool_call':
+                return [{ kind: 'stage', stage: 'explore', status: it.status === 'failed' ? 'active' : 'confirmed', note: `Tool ${it.server ?? ''}.${it.tool ?? ''}` }];
+            case 'web_search':
+                return [{ kind: 'stage', stage: 'explore', status: 'confirmed', note: `Web search: ${oneLine(it.query ?? '', 60)}` }];
+            case 'agent_message':
+                return it.text ? [{ kind: 'fact', key: 'answer', label: 'Answer', value: oneLine(it.text, 300), stage: 'done' }] : [];
+            case 'error':
+                return [{ kind: 'error', severity: 'cause', stage: 'done', message: it.message ?? 'Codex reported an error.' }];
+            default:
+                return [];
+        }
+    }
+    finish() {
+        return this.checks.finish();
+    }
+}
+export function codexPresenter(cwd = process.cwd()) {
+    return (raw) => {
+        const e = parse(raw.trim());
+        if (!e)
+            return raw.trim() && !/rmcp::/.test(raw) ? raw : null;
+        const it = e.item ?? {};
+        if (e.type === 'thread.started')
+            return '● Codex session started';
+        if (e.type === 'item.started' && it.type === 'command_execution')
+            return `  $ ${oneLine(unwrapShell(it.command ?? ''), 140)}`;
+        if (e.type === 'item.completed') {
+            if (it.type === 'command_execution')
+                return it.exit_code === 0 ? null : `    ✗ exit ${it.exit_code ?? '?'}${it.aggregated_output?.trim() ? `: ${oneLine(it.aggregated_output.trim().split('\n').at(-1), 120)}` : ''}`;
+            if (it.type === 'file_change')
+                return `  ✎ ${describeChanges(it.changes ?? [], cwd)}${it.status === 'failed' ? ' (failed)' : ''}`;
+            if (it.type === 'agent_message' && it.text)
+                return `› ${oneLine(it.text, 300)}`;
+            if (it.type === 'mcp_tool_call')
+                return `  → Tool ${it.server ?? ''}.${it.tool ?? ''}`;
+            if (it.type === 'web_search')
+                return `  → Web search: ${oneLine(it.query ?? '', 60)}`;
+            if (it.type === 'error')
+                return `  ✗ ${it.message ?? 'error'}`;
+            return null;
+        }
+        if (e.type === 'turn.completed') {
+            const u = e.usage ?? {};
+            return `■ Done${u.input_tokens !== undefined ? ` · ${k(u.input_tokens)} tokens in, ${k(u.output_tokens ?? 0)} out` : ''}`;
+        }
+        if (e.type === 'turn.failed' || e.type === 'error')
+            return `■ Failed: ${e.error?.message ?? e.message ?? ''}`;
+        return null;
+    };
+}
+export const codex = {
+    id: 'codex',
+    title: 'Codex task',
+    stages: agentStages('Codex', 'https://developers.openai.com/codex/cli', 'Codex runs in a sandbox; use `--sandbox workspace-write` to let it edit files.'),
+    notes: { ...AGENT_NOTES, docsLabel: 'Codex docs' },
+    install: 'Install the Codex CLI (`npm i -g @openai/codex`), then run `codex login`.',
+    maxLineLength: 2_000_000,
+    launch(userArgs) {
+        const args = userArgs[0] === 'exec' ? userArgs.slice(1) : [...userArgs];
+        if (!args.some((a) => !a.startsWith('-'))) {
+            throw new UsageError('give Codex a task, for example: unfold codex "fix the failing test" --sandbox workspace-write');
+        }
+        return { bin: process.env.UNFOLD_CODEX_BIN || 'codex', args: ['exec', ...(args.includes('--json') ? [] : ['--json']), ...args] };
+    },
+    createParser: (ctx) => new CodexParser(ctx.cwd),
+    createPresenter: (ctx) => codexPresenter(ctx.cwd),
+    fixHints: (state) => agentFixHints(state, 'Give it more room with `--sandbox workspace-write`.'),
+};

package/dist/providers/agents/shared.js

@@ -0,0 +1,119 @@
+export function agentStages(agent, docsUrl, permissions) {
+    return [
+        {
+            id: 'start',
+            title: 'Start',
+            summary: `${agent} starts a session with its model, settings and the tools it may use.`,
+            explanation: [
+                `Unfold runs ${agent} in its non-interactive mode, which reports every step as a structured event instead of drawing a full-screen interface.`,
+                `In this mode ${agent} cannot stop to ask you for permission, so it can only do what your settings and flags allow. ${permissions}`,
+            ],
+            confirmedBy: 'The session start event.',
+            docsUrl,
+        },
+        {
+            id: 'explore',
+            title: 'Explore',
+            summary: 'It reads files and searches the code to understand the task.',
+            explanation: [
+                'Agents usually start by looking around: listing folders, reading files, searching for symbols and running read-only commands such as `git status`.',
+            ],
+            confirmedBy: 'A successful read, search or read-only command.',
+            docsUrl,
+        },
+        {
+            id: 'change',
+            title: 'Change',
+            summary: 'It edits or creates files to carry out the task.',
+            explanation: [
+                'Edits are written straight to your working tree. Review them with `git diff` before committing.',
+                'If it is not allowed to edit, its attempts are denied and the task cannot be completed.',
+            ],
+            confirmedBy: 'A successful file edit or write.',
+            docsUrl,
+        },
+        {
+            id: 'verify',
+            title: 'Verify',
+            summary: 'It runs checks such as tests, a type check, a linter or a build.',
+            explanation: [
+                'Unfold counts a command as a check when it looks like one, for example `npm test`, `pytest`, `tsc`, `eslint`, `cargo build` or `make`.',
+                'If the agent never runs a check, this stays unverified: the change may still be right, but nothing in the run showed it working.',
+            ],
+            confirmedBy: 'A check command that exits successfully.',
+            docsUrl,
+        },
+        {
+            id: 'done',
+            title: 'Done',
+            summary: 'It reports its final answer and the session ends.',
+            explanation: ['The final event says whether the session succeeded and, depending on the agent, how long it took, how many turns it used and what it cost.'],
+            confirmedBy: 'The final result event, with no error.',
+            docsUrl,
+        },
+    ];
+}
+export const AGENT_NOTES = {
+    success: 'Done',
+    successHeadline: 'The agent finished',
+    docsLabel: 'Docs',
+    highlights: ['answer', 'filesChanged', 'denied', 'cost', 'tokens'],
+    interrupted: 'You pressed Ctrl+C while this was in progress. Changes the agent already wrote stay on disk; review them with `git diff`.',
+    unverified: "This run's output never showed this step.",
+};
+const VERIFY = /(^|[\s;&|(])((npm|pnpm|yarn|bun)( run)? (test|build|lint|typecheck|check)\b|npx (tsc|vitest|jest|eslint|playwright)|\b(tsc|vitest|jest|mocha|pytest|tox|ruff|mypy|eslint|phpunit|rspec|playwright)\b|go (test|build|vet)|cargo (test|build|check|clippy)|\bmake\b|gradle|mvn|dotnet (test|build)|swift (test|build))/;
+const CHANGE = /(^|[\s;&|(])(sed -i|perl -pi|tee |mv |rm |cp |mkdir |touch |chmod |apply_patch|git (commit|apply|checkout|restore|reset|stash|add)|(npm|pnpm|yarn|bun) (i|install|add|remove|uninstall)\b|pip install)|[^2&]>{1,2}\s*(?!\/dev\/null)[\w./]/;
+/** Rough classification of a shell command by what it does. */
+export function classifyCommand(cmd) {
+    if (VERIFY.test(cmd))
+        return 'verify';
+    if (CHANGE.test(cmd))
+        return 'change';
+    return 'explore';
+}
+/** `/bin/zsh -lc "npm test"` → `npm test` (Codex wraps commands in a login shell). */
+export function unwrapShell(cmd) {
+    const m = /^\S*\/(?:ba|z)?sh -l?c (['"])([\s\S]*)\1$/.exec(cmd.trim()) ?? /^\S*\/(?:ba|z)?sh -l?c (\S+)$/.exec(cmd.trim());
+    if (!m)
+        return cmd;
+    const inner = m.length === 3 ? m[2] : m[1];
+    return m[1] === "'" ? inner.replace(/'\\''/g, "'").replace(/'"'"'/g, "'") : inner.replace(/\\"/g, '"');
+}
+/** Shows paths relative to the session's folder when possible. */
+export function relPath(path, cwd) {
+    if (cwd && path.startsWith(cwd.replace(/\/$/, '') + '/'))
+        return path.slice(cwd.replace(/\/$/, '').length + 1);
+    return path;
+}
+export const oneLine = (s, max = 160) => {
+    const t = s.replace(/\s+/g, ' ').trim();
+    return t.length > max ? t.slice(0, max - 1) + '…' : t;
+};
+/** Tracks checks across a run so the end of the run can say how they went. */
+export class CheckTracker {
+    last;
+    changed = new Set();
+    record(cmd, ok) {
+        this.last = { cmd, ok };
+    }
+    finish() {
+        const out = [];
+        if (this.changed.size) {
+            const files = [...this.changed];
+            out.push({ kind: 'fact', key: 'filesChanged', label: 'Files changed', value: `${files.slice(0, 8).join(', ')}${files.length > 8 ? ` and ${files.length - 8} more` : ''}`, stage: 'change' });
+        }
+        if (this.last && !this.last.ok) {
+            out.push({ kind: 'stage', stage: 'verify', status: 'unverified', note: `Checks ran, but the last one failed: ${oneLine(this.last.cmd, 80)}` });
+        }
+        return out;
+    }
+}
+/** Hints for the fix prompt when an agent run fails. */
+export function agentFixHints(state, allowHint) {
+    const hints = [];
+    const denied = state.facts.find((f) => f.key === 'denied');
+    if (denied)
+        hints.push(`The agent was denied permission for: ${denied.value}. ${allowHint}`);
+    hints.push('Review what the agent already changed with `git diff` before running it again.');
+    return hints;
+}

package/dist/providers/gcloud/index.js

@@ -0,0 +1,39 @@
+import { GcloudParser } from './parser.js';
+import { GCLOUD_NOTES, GCLOUD_STAGES } from './stages.js';
+export const gcloud = {
+    id: 'gcloud',
+    title: 'Cloud Run deploy',
+    stages: GCLOUD_STAGES,
+    notes: GCLOUD_NOTES,
+    install: 'Install the Google Cloud CLI (https://cloud.google.com/sdk/docs/install), then run `gcloud auth login`.',
+    launch(userArgs) {
+        const args = [...userArgs];
+        // `unfold gcloud …` means `gcloud run deploy …`; accept the full form too.
+        if (args[0] === 'run' && args[1] === 'deploy')
+            args.splice(0, 2);
+        return { bin: process.env.UNFOLD_GCLOUD_BIN || 'gcloud', args: ['run', 'deploy', ...args] };
+    },
+    createParser: () => new GcloudParser(),
+    fixHints(state) {
+        const fact = (k) => state.facts.find((f) => f.key === k)?.value;
+        switch (state.failedStage) {
+            case 'prepare':
+                return [
+                    'This failed before anything was built. Account, project, billing and disabled-API problems are fixed with gcloud commands, not code: `gcloud auth login`, `gcloud config set project <id>`, and `gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com`. If that is the cause, say so and stop.',
+                ];
+            case 'build':
+                return [
+                    `The container was built by Cloud Build, not locally.${fact('logsUrl') ? ` The full build log is at ${fact('logsUrl')}.` : ''}`,
+                    `It was built with ${fact('buildType') ?? 'a Dockerfile or buildpacks'}. Reproduce it locally with \`docker build .\` (Dockerfile) or \`pack build\` (buildpacks) before and after the fix.`,
+                    'For buildpacks, check that the project declares how to start (for example a `start` script in package.json, or a Procfile).',
+                ];
+            case 'deploy':
+                return [
+                    'The image built, but the new revision did not become healthy. The most common cause: the container must listen on 0.0.0.0 at the port in the PORT environment variable (8080 by default).',
+                    `Check start-up errors with \`gcloud run services logs read ${fact('service') ?? '<service>'}${fact('region') ? ` --region ${fact('region')}` : ''}\`. Crashes on start, missing environment variables and memory limits show up there.`,
+                ];
+            default:
+                return [];
+        }
+    },
+};