@asrunjs/asrun 0.2.0 → 0.5.3

package/dist/ui/server/actions.js

@@ -12,8 +12,7 @@ import { jobs } from './jobs.js';
 import { verifyProfiles } from './profiles.js';
 import { isValidCaseId, listCaseIds } from './cases.js';
 import { snapshotDirPath, specFilePath } from '../../lib/case-ops.js';
-import { AI_COMMANDS, AI_COMMAND_WRITES, AI_TOOLS, continueCommandLine, continueInvocation, headlessCommandLine, headlessInvocation, HINTS_DIR, HINTS_MAX_CHARS, makeCaseCommandLine, makeCaseInvocation, MEMO_DIR, MEMO_MAX_CHARS, REPLY_MAX_CHARS, } from '../shared/ai-commands.js';
-const VISIT_PATH = '/app/home';
+import { AI_COMMANDS, AI_COMMAND_WRITES, AI_TOOLS, continueCommandLine, continueInvocation, headlessCommandLine, headlessInvocation, HINTS_DIR, HINTS_MAX_CHARS, makeCaseCommandLine, makeCaseInvocation, MEMO_DIR, MEMO_MAX_CHARS, REPLY_DIR, REPLY_MAX_CHARS, } from '../shared/ai-commands.js';
 const REPORTS_DIR = path.join(ROOT, 'reports');
 const REPORT_ID = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(-[a-z0-9]+(-[a-z0-9]+)*)?$/;
 const newSessionId = (tool) => tool === 'claude' ? crypto.randomUUID() : `ses_${crypto.randomBytes(12).toString('hex')}`;
@@ -28,6 +27,8 @@ export const startJobSchema = z.discriminatedUnion('action', [
         env: z.string().min(1),
         force: z.boolean().optional(),
         attended: z.boolean().optional(),
+        thinking: z.boolean().optional(),
+        model: z.string().min(1).max(200).optional(),
         profiles: z.array(z.string().min(1)).optional(),
         hints: z.string().max(HINTS_MAX_CHARS).optional(),
         report: z.string().min(1).max(100).optional(),
@@ -41,6 +42,8 @@ export const startJobSchema = z.discriminatedUnion('action', [
         action: z.literal('make-cases'),
         tool: z.enum(AI_TOOLS),
         memo: z.string().max(MEMO_MAX_CHARS),
+        model: z.string().min(1).max(200).optional(),
+        thinking: z.boolean().optional(),
     }),
     z.object({
         action: z.literal('run'),
@@ -159,15 +162,17 @@ export function buildJobSpec(request) {
     }
     if (request.action === 'visit') {
         checkProfile(request.profile, request.env);
+        // Where a login lands is a profile setting (its own home page), not something the UI knows.
+        const startPath = knownProfiles.find((profile) => profile.id === request.profile)?.startPath ?? '';
         // Only reads the saved session when it starts, so it does not take the auth lock
         // (that would block test runs for as long as the window stays open).
         return {
             kind: 'visit',
             profile: request.profile,
             env: request.env,
-            command: `pnpm explore ${request.profile} ${VISIT_PATH}`,
+            command: ['pnpm explore', request.profile, startPath].filter(Boolean).join(' '),
             file: process.execPath,
-            args: [...scriptArgs('explore.ts'), request.profile, VISIT_PATH],
+            args: [...scriptArgs('explore.ts'), request.profile, ...(startPath ? [startPath] : [])],
             locks: [`visit:${request.profile}`],
             acceptsInput: false,
         };
@@ -175,14 +180,14 @@ export function buildJobSpec(request) {
     // An AI run on a case, a first turn or a continuation: the same permissions and locks either way.
     // Generating and healing write the spec and the case values and run the tests, so they must not overlap with a run.
     // Reviewing only edits the case file and looks at pages, so it takes just the case lock.
-    const aiSpec = (tool, command, caseId, env, sessionId, run) => ({
+    const aiSpec = (tool, command, caseId, env, sessionId, run, model, thinking) => ({
         kind: 'ai',
         env,
         ...run,
         locks: [`ai:${caseId}`, ...(AI_COMMAND_WRITES[command] === 'files' ? ['run', ...allLocks()] : [])],
         acceptsInput: false,
         stream: tool,
-        ai: { tool, command, caseId, env, sessionId },
+        ai: { tool, command, caseId, env, sessionId, ...(model && { model }), ...(thinking && { thinking }) },
     });
     if (request.action === 'ai') {
         if (!isValidCaseId(request.caseId) || !listCaseIds().includes(request.caseId)) {
@@ -225,6 +230,8 @@ export function buildJobSpec(request) {
         }
         const options = {
             env: request.env,
+            model: request.model,
+            thinking: request.thinking,
             force: request.force,
             attended: request.attended,
             // Naming every profile is the same as leaving it out: the agent then takes all that are logged in.
@@ -238,7 +245,7 @@ export function buildJobSpec(request) {
             command: headlessCommandLine(request.tool, request.command, request.caseId, options, session),
             file,
             args,
-        });
+        }, request.model, request.thinking);
     }
     if (request.action === 'continue') {
         const earlier = jobs.get(request.jobId);
@@ -253,13 +260,19 @@ export function buildJobSpec(request) {
         }
         if (!listCaseIds().includes(ai.caseId))
             throw new ActionError(`The case "${ai.caseId}" no longer exists.`);
-        const { file, args } = continueInvocation(ai.tool, ai.command, request.reply, ai.sessionId);
+        // The answers are stored as a file so the agent reads them verbatim; a line break or a quote in them cannot
+        // break the command line of the agent CLI.
+        const replyPath = `${REPLY_DIR}/${new Date().toISOString().replace(/[:.]/g, '-')}-${crypto.randomBytes(3).toString('hex')}.md`;
+        fs.mkdirSync(path.join(ROOT, REPLY_DIR), { recursive: true });
+        fs.writeFileSync(path.join(ROOT, replyPath), request.reply.trim() + '\n');
+        // The next turn keeps how the first one was told to run (model and reasoning), so the log stays the same.
+        const { file, args } = continueInvocation(ai.tool, ai.command, replyPath, ai.sessionId, ai.model, ai.thinking);
         return aiSpec(ai.tool, ai.command, ai.caseId, ai.env, ai.sessionId, {
-            command: continueCommandLine(ai.tool, ai.command, request.reply, ai.sessionId),
+            command: continueCommandLine(ai.tool, ai.command, replyPath, ai.sessionId, ai.model, ai.thinking),
             file,
             args,
             continuesJobId: earlier.info.id,
-        });
+        }, ai.model, ai.thinking);
     }
     if (request.action === 'make-cases') {
         if (request.memo.trim() === '')
@@ -268,10 +281,10 @@ export function buildJobSpec(request) {
         const memoPath = `${MEMO_DIR}/${new Date().toISOString().replace(/[:.]/g, '-')}-${crypto.randomBytes(3).toString('hex')}.md`;
         fs.mkdirSync(path.join(ROOT, MEMO_DIR), { recursive: true });
         fs.writeFileSync(path.join(ROOT, memoPath), request.memo);
-        const { file, args } = makeCaseInvocation(request.tool, memoPath);
+        const { file, args } = makeCaseInvocation(request.tool, memoPath, request.model, request.thinking);
         return {
             kind: 'ai',
-            command: makeCaseCommandLine(request.tool, memoPath),
+            command: makeCaseCommandLine(request.tool, memoPath, request.model, request.thinking),
             file,
             args,
             locks: ['ai:make-cases'],

package/dist/ui/server/ai-models.d.ts

@@ -0,0 +1,3 @@
+import type { AiTool } from '../shared/ai-commands.js';
+import type { AiModelsResponse } from '../shared/types.js';
+export declare function listAiModels(tool: AiTool, refresh?: boolean): Promise<AiModelsResponse>;

package/dist/ui/server/ai-models.js

@@ -0,0 +1,347 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnTarget } from '../../lib/command.js';
+import { ROOT } from '../../lib/paths.js';
+/**
+ * The models each AI CLI can be run with on this machine, read from the CLI itself rather than from a list we ship:
+ * OpenCode answers `opencode models`; Claude Code has no such command, so its rows come from its own configuration
+ * (the model settings, `modelPicker`, the custom-option and default-model variables) and, for a gateway, from the
+ * `/v1/models` endpoint the CLI itself would query when its model discovery is enabled.
+ *
+ * Nothing here reads or prints a credential: the environment is only used to build request headers.
+ */
+/** A provider added or signed in after the list was read changes it, so it is read again after this long. */
+const CACHE_MS = 30_000;
+const COMMAND_TIMEOUT_MS = 20_000;
+/** Claude Code's own discovery timeout is 3 s; an asrun page can wait a little longer. */
+const GATEWAY_TIMEOUT_MS = 5_000;
+const CACHE = new Map();
+export async function listAiModels(tool, refresh = false) {
+    const cached = CACHE.get(tool);
+    if (!refresh && cached && Date.now() - cached.at < CACHE_MS)
+        return cached.value;
+    const value = tool === 'opencode' ? await opencodeModels() : await claudeModels();
+    CACHE.set(tool, { at: Date.now(), value });
+    return value;
+}
+const nothingToDo = (tool, error) => ({
+    tool,
+    models: [],
+    clientDefault: null,
+    suggested: null,
+    notes: [],
+    error,
+});
+const firstLine = (text) => text.replace(/\s+/g, ' ').trim();
+/** Runs a CLI and collects its output; never rejects. */
+function run(file, args, timeoutMs) {
+    return new Promise((resolve) => {
+        const target = spawnTarget(file, args);
+        if (target === null) {
+            resolve({ code: null, stdout: '', stderr: `"${file}" was not found on PATH` });
+            return;
+        }
+        let stdout = '';
+        let stderr = '';
+        let done = false;
+        const finish = (code) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve({ code, stdout, stderr });
+        };
+        const timer = setTimeout(() => {
+            child.kill();
+            finish(null);
+        }, timeoutMs);
+        const child = spawn(target.file, target.args, {
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            ...(target.throughShell && { windowsVerbatimArguments: true }),
+        });
+        child.stdout?.on('data', (buffer) => (stdout += buffer.toString('utf8')));
+        child.stderr?.on('data', (buffer) => (stderr += buffer.toString('utf8')));
+        child.on('error', (error) => {
+            stderr += error.message;
+            finish(null);
+        });
+        child.on('close', (code) => finish(code));
+    });
+}
+/**
+ * `opencode models` prints one `provider/model` (or `provider/model@variant`) per line, which is exactly what
+ * `--model` takes apart from the variant separator: the CLI reads `#variant` there.
+ */
+async function opencodeModels() {
+    const result = await run('opencode', ['models'], COMMAND_TIMEOUT_MS);
+    if (result.code !== 0) {
+        const why = result.code === null
+            ? firstLine(result.stderr) || 'the command did not finish'
+            : `the command exited with code ${result.code}${firstLine(result.stderr) ? ` (${firstLine(result.stderr)})` : ''}`;
+        return nothingToDo('opencode', `Cannot read the OpenCode model list: ${why}.`);
+    }
+    const models = [];
+    const seen = new Set();
+    for (const raw of result.stdout.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === '' || line.startsWith('#') || !line.includes('/'))
+            continue;
+        const slash = line.indexOf('/');
+        const provider = line.slice(0, slash);
+        const rest = line.slice(slash + 1);
+        const at = rest.indexOf('@');
+        const name = at === -1 ? rest : rest.slice(0, at);
+        const variant = at === -1 ? '' : rest.slice(at + 1);
+        // `provider/model#variant` is what the CLI's own --model flag expects; a run without one gets the default variant.
+        const id = `${provider}/${name}${variant ? `#${variant}` : ''}`;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        models.push({
+            id,
+            label: variant ? `${name} (${variant})` : name,
+            group: provider,
+            ...(variant && { detail: `variant ${variant}` }),
+        });
+    }
+    if (models.length === 0)
+        return nothingToDo('opencode', 'OpenCode listed no models. Add a provider with "opencode auth login".');
+    models.sort((a, b) => (a.group === b.group ? a.label.localeCompare(b.label) : a.group.localeCompare(b.group)));
+    // OpenCode keeps nothing that a one-shot run reads: without --model it takes a built-in free model. Its TUI does
+    // remember the model of the last session, which is a better guess than the free one for the first run.
+    const lastUsed = opencodeLastUsed();
+    return {
+        tool: 'opencode',
+        models,
+        clientDefault: null,
+        suggested: lastUsed && models.some((model) => model.id === lastUsed || model.id.startsWith(`${lastUsed}#`)) ? lastUsed : null,
+        notes: [],
+        error: null,
+    };
+}
+/** `~/.local/state/opencode/model.json`, where the OpenCode TUI remembers its recent models. */
+function opencodeLastUsed() {
+    try {
+        const file = path.join(os.homedir(), '.local', 'state', 'opencode', 'model.json');
+        const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+        const first = data.recent?.[0];
+        return first?.providerID && first?.modelID ? `${first.providerID}/${first.modelID}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Every settings file Claude Code reads, lowest precedence first; the managed one comes last and wins. */
+function claudeSettingsFiles() {
+    const programData = process.env.ProgramData ?? 'C:\\ProgramData';
+    const managed = process.platform === 'win32'
+        ? path.join(programData, 'ClaudeCode', 'managed-settings.json')
+        : process.platform === 'darwin'
+            ? '/Library/Application Support/ClaudeCode/managed-settings.json'
+            : '/etc/claude-code/managed-settings.json';
+    return [
+        { path: path.join(os.homedir(), '.claude', 'settings.json'), label: 'user settings' },
+        { path: path.join(ROOT, '.claude', 'settings.json'), label: 'project settings' },
+        { path: path.join(ROOT, '.claude', 'settings.local.json'), label: 'local settings' },
+        { path: managed, label: 'managed settings' },
+    ];
+}
+/** The aliases Claude Code always accepts, whatever the provider. */
+const CLAUDE_ALIASES = [
+    { id: 'sonnet', env: 'ANTHROPIC_DEFAULT_SONNET_MODEL', what: 'the latest Sonnet for everyday coding' },
+    { id: 'opus', env: 'ANTHROPIC_DEFAULT_OPUS_MODEL', what: 'the latest Opus for complex reasoning' },
+    { id: 'haiku', env: 'ANTHROPIC_DEFAULT_HAIKU_MODEL', what: 'the fast and cheap model' },
+    { id: 'fable', env: 'ANTHROPIC_DEFAULT_FABLE_MODEL', what: 'the model for the hardest, longest tasks' },
+    { id: 'opusplan', env: null, what: 'opus in plan mode, then sonnet' },
+];
+/**
+ * Claude Code does not enumerate the models of a cloud provider (Vertex, Bedrock, Foundry): its picker shows a
+ * built-in lineup plus whatever the settings pin, and it sends a model id it does not know as it is. So the rows here
+ * are the models that are actually configured on this machine, not an invented catalogue.
+ */
+async function claudeModels() {
+    const notes = [];
+    const settings = [];
+    for (const file of claudeSettingsFiles()) {
+        try {
+            if (!fs.existsSync(file.path))
+                continue;
+            const data = JSON.parse(fs.readFileSync(file.path, 'utf8'));
+            if (data && typeof data === 'object')
+                settings.push({ ...file, data });
+        }
+        catch (error) {
+            notes.push(`Cannot read ${file.label} (${file.path}): ${firstLine(error.message)}.`);
+        }
+    }
+    // `env` blocks of the settings files, then the real environment on top: that is the order the CLI ends up with.
+    const env = {};
+    for (const file of settings) {
+        const block = file.data.env;
+        if (!block || typeof block !== 'object')
+            continue;
+        for (const [key, value] of Object.entries(block)) {
+            if (typeof value === 'string')
+                env[key] = value;
+        }
+    }
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined && (key.startsWith('ANTHROPIC_') || key.startsWith('CLAUDE_CODE_')))
+            env[key] = value;
+    }
+    const models = [];
+    const seen = new Set();
+    const add = (option) => {
+        if (option.id === '' || seen.has(option.id))
+            return;
+        seen.add(option.id);
+        models.push(option);
+    };
+    // The lineup the user wrote for the picker (user or managed settings only, as the CLI reads it). The highest of
+    // those that sets the key supplies the whole lineup, so the last file wins.
+    for (const file of [...settings].reverse()) {
+        const options = file.data.modelPicker?.options;
+        if (!Array.isArray(options))
+            continue;
+        for (const row of options) {
+            if (!row || typeof row.model !== 'string' || row.model === '')
+                continue;
+            add({
+                id: row.model,
+                label: typeof row.label === 'string' && row.label !== '' ? row.label : row.model,
+                group: 'settings',
+                detail: typeof row.description === 'string' && row.description !== '' ? row.description : 'from modelPicker',
+            });
+        }
+        break;
+    }
+    const defaultModel = [...settings].reverse().find((file) => typeof file.data.model === 'string')?.data.model;
+    if (typeof defaultModel === 'string' && defaultModel !== '') {
+        add({ id: defaultModel, label: defaultModel, group: 'settings', detail: 'the model new sessions start on' });
+    }
+    if (env.ANTHROPIC_CUSTOM_MODEL_OPTION) {
+        add({
+            id: env.ANTHROPIC_CUSTOM_MODEL_OPTION,
+            label: env.ANTHROPIC_CUSTOM_MODEL_OPTION_NAME || env.ANTHROPIC_CUSTOM_MODEL_OPTION,
+            group: 'settings',
+            detail: env.ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION || 'from ANTHROPIC_CUSTOM_MODEL_OPTION',
+        });
+    }
+    for (const alias of CLAUDE_ALIASES) {
+        const pinned = alias.env ? env[alias.env] : undefined;
+        if (!pinned)
+            continue;
+        add({ id: pinned, label: pinned, group: 'settings', detail: `what ${alias.id} runs here` });
+    }
+    const provider = claudeProvider(env);
+    if (provider === 'cloud') {
+        notes.push('Claude Code does not list the models of Vertex, Bedrock or Foundry: only the models configured in its settings ' +
+            'are listed here (modelPicker, ANTHROPIC_CUSTOM_MODEL_OPTION, ANTHROPIC_DEFAULT_*_MODEL), plus the aliases.');
+    }
+    else {
+        const discovered = await gatewayModels(env);
+        for (const option of discovered.models)
+            add(option);
+        notes.push(...discovered.notes);
+    }
+    for (const alias of CLAUDE_ALIASES) {
+        const pinned = alias.env ? env[alias.env] : undefined;
+        add({
+            id: alias.id,
+            label: alias.id,
+            group: 'alias',
+            detail: pinned ? `→ ${pinned}` : alias.what,
+        });
+    }
+    const clientDefault = env.ANTHROPIC_MODEL || defaultModel || env.ANTHROPIC_DEFAULT_MODEL || null;
+    return {
+        tool: 'claude',
+        models,
+        clientDefault,
+        suggested: clientDefault,
+        notes,
+        error: models.length === 0 ? 'Claude Code listed no models: no model is configured for it here.' : null,
+    };
+}
+/** `cloud` when a `CLAUDE_CODE_USE_*` provider is selected, `gateway`/`api` otherwise. */
+function claudeProvider(env) {
+    if (env.CLAUDE_CODE_USE_VERTEX || env.CLAUDE_CODE_USE_BEDROCK || env.CLAUDE_CODE_USE_FOUNDRY || env.CLAUDE_CODE_USE_MANTLE) {
+        return 'cloud';
+    }
+    return env.ANTHROPIC_BASE_URL ? 'gateway' : 'api';
+}
+/**
+ * The `/v1/models?limit=1000` request Claude Code makes when its gateway model discovery is on, with the same
+ * credentials and custom headers. Every id is kept: a gateway may serve models whose name says nothing about Claude,
+ * and those are exactly the ones a person cannot guess.
+ */
+async function gatewayModels(env) {
+    const base = (env.ANTHROPIC_BASE_URL || 'https://api.anthropic.com').replace(/\/+$/, '');
+    const host = (() => {
+        try {
+            return new URL(base).host;
+        }
+        catch {
+            return base;
+        }
+    })();
+    const headers = {};
+    if (env.ANTHROPIC_AUTH_TOKEN)
+        headers.Authorization = `Bearer ${env.ANTHROPIC_AUTH_TOKEN}`;
+    if (env.ANTHROPIC_API_KEY)
+        headers['x-api-key'] = env.ANTHROPIC_API_KEY;
+    for (const raw of (env.ANTHROPIC_CUSTOM_HEADERS ?? '').split(/\r?\n/)) {
+        const match = /^([^:]+):\s*(.*)$/.exec(raw.trim());
+        if (match)
+            headers[match[1].trim()] = match[2].trim();
+    }
+    if (!headers.Authorization && !headers['x-api-key']) {
+        return {
+            models: [],
+            notes: [
+                `${host} was not asked for its models: Claude Code authenticates it without ANTHROPIC_AUTH_TOKEN or ` +
+                    'ANTHROPIC_API_KEY, so there is no credential to send.',
+            ],
+        };
+    }
+    const timeout = Number(env.CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS) || GATEWAY_TIMEOUT_MS;
+    try {
+        const response = await fetch(`${base}/v1/models?limit=1000`, {
+            headers,
+            // A redirect is a failure: the credential must not travel to another host.
+            redirect: 'error',
+            signal: AbortSignal.timeout(timeout),
+        });
+        if (!response.ok) {
+            const body = firstLine(await response.text().catch(() => '')).slice(0, 200);
+            return { models: [], notes: [`${host} answered ${response.status} for its model list${body ? `: ${body}` : ''}.`] };
+        }
+        const data = (await response.json());
+        const rows = Array.isArray(data?.data) ? data.data : [];
+        const models = [];
+        for (const row of rows) {
+            if (!row || typeof row.id !== 'string' || row.id === '')
+                continue;
+            models.push({
+                id: row.id,
+                label: typeof row.display_name === 'string' && row.display_name !== '' ? row.display_name : row.id,
+                group: host,
+                ...(typeof row.description === 'string' && row.description !== '' && { detail: firstLine(row.description) }),
+            });
+        }
+        return {
+            models,
+            notes: models.length === 0 ? [`${host} listed no models.`] : [],
+        };
+    }
+    catch (error) {
+        const message = firstLine(error.message);
+        return {
+            models: [],
+            notes: [`${host} could not be asked for its model list (${message}).`],
+        };
+    }
+}

package/dist/ui/server/ai-stream.d.ts

@@ -1,4 +1,15 @@
 import type { AiTool } from '../shared/ai-commands.js';
+import type { JobChunkKind, JobChunkTool } from '../shared/types.js';
+/** One block of the job log; the server turns it into a `JobChunk` (`jobs.ts`). */
+export interface LogPart {
+    kind: JobChunkKind;
+    /** The block as a person reads it; also what Copy log and the log file hold. */
+    data: string;
+    /** When it was produced, in ms. */
+    at: number;
+    /** Set on a tool block: the UI colors the name, the outcome and the time it took. */
+    tool?: JobChunkTool;
+}
 /** The agent has put a handoff card in the browser window and waits for the person (see user-handoff.md). */
 export interface AwaitingUser {
     message: string | null;
@@ -10,32 +21,46 @@ export declare class AiStreamFormatter {
     private pending;
     private cardCalls;
     private waitingForUser;
+    /** The message of the last options call, kept so a card that runs after unrelated calls still carries it. */
+    private lastHandoffMessage;
     private lastEventAt;
     private lastWaitAt;
+    /** The last call the agent finished, so a quiet spell can say what it is doing instead of only that nothing came. */
+    private lastCall;
     private sandboxHinted;
     constructor(tool: AiTool);
-    /** Lines for a piece of stdout. Incomplete trailing lines wait for the next piece. */
-    feed(text: string): string;
+    /** Blocks for a piece of stdout. Incomplete trailing lines wait for the next piece. */
+    feed(text: string): LogPart[];
     /**
      * Set while a handoff card waits for the person. OpenCode reports a tool call only when it has finished, so the card
      * call itself is not visible while it waits: the options call before it (`__handoffCfg`) starts the state and the end
-     * of the card call, or any other call, ends it. The object changes on every new handoff, so `===` detects a change.
+     * of the card call, or a later call, ends it. The object changes on every new handoff, so `===` detects a change.
      */
     get awaiting(): AwaitingUser | null;
-    /** Called once for every tool call the agent makes, with the id the end of that call will carry. */
+    /**
+     * Called once for every tool call the agent makes, with the id the end of that call will carry. Returns a line for the
+     * log when a card came back that nobody was told about (`MISSED_HANDOFF_HINT`).
+     */
     private watchHandoff;
     /** What is left when the process ends. */
-    end(): string;
+    end(): LogPart[];
     /**
-     * A line about the oldest tool call that has not returned, when nothing has happened for `quietMs` (and again every
-     * `quietMs` after that).
+     * A block about the oldest tool call that has not returned, when nothing has happened for `quietMs` (and again every
+     * `quietMs` after that). It names the last call that did finish, so a long run never looks stuck.
      */
-    waiting(quietMs: number): string;
+    waiting(quietMs: number): LogPart | null;
     private line;
+    /** A call the agent has started and not finished yet (Claude reports both ends). */
     private start;
-    private end1;
+    /**
+     * The end of a call, plus the first lines of what it returned. `fallback` is for a CLI that reports a call only when
+     * it is over (OpenCode), which still knows when it started.
+     */
+    private finishCall;
     /** Said once per run, after the first tool call that Claude Code's sandbox refused (nobody is there to approve it). */
     private sandboxHint;
     private claude;
     private opencode;
+    /** `FAILED: <why>`, plus what to do about the two failures users actually hit. */
+    private opencodeError;
 }