@withbuddi/buddi 0.1.0-pre.17 → 0.1.0-pre.18

package/packages/gateway/dist/channels/local-notification.js

@@ -0,0 +1,154 @@
+/**
+ * This machine's system notification as a channel (docs/notifications.md).
+ *
+ * macOS: `terminal-notifier` when it is installed, because a click on it can
+ * open the dashboard; otherwise `osascript`'s `display notification`, which
+ * shows and opens nothing. Linux: `notify-send`, when it exists and there is
+ * a display to show on. Anywhere else there is nothing to show, so no channel
+ * is made and Settings never lists one.
+ *
+ * The service runs as a user LaunchAgent on macOS, which is in the owner's
+ * GUI session: `osascript -e 'display notification …'` works there without a
+ * TTY. A LaunchDaemon (root, no session) could not, and buddi installs none.
+ *
+ * Nothing leaves the machine. Routing already sends a `now` message here only
+ * when the owner is away from the dashboard or after the 10-minute wait, so
+ * this module checks nothing more.
+ */
+import { execFile } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import path from 'node:path';
+/** How long one notification may take before it is refused. */
+export const LOCAL_NOTIFY_TIMEOUT_MS = 5_000;
+/** The longest text shown; a system notification is a line or two. */
+export const LOCAL_NOTIFY_MAX_CHARS = 200;
+/** `execFile` with a timeout, answering instead of throwing. */
+export const execCommand = (file, args, opts) => new Promise((resolve) => {
+    execFile(file, [...args], { timeout: opts.timeoutMs, windowsHide: true }, (err, _stdout, stderr) => {
+        const text = String(stderr ?? '');
+        if (!err)
+            return resolve({ code: 0, stderr: text });
+        const e = err;
+        if (e.killed)
+            return resolve({ code: null, stderr: text, error: `it took longer than ${opts.timeoutMs / 1000} s` });
+        if (typeof e.code === 'number')
+            return resolve({ code: e.code, stderr: text });
+        resolve({ code: null, stderr: text, error: e.message });
+    });
+});
+/** A binary on PATH (and, on macOS, where Homebrew puts it: a service's PATH may lack it). */
+export function whichOn(env, platform) {
+    const dirs = (env.PATH ?? '').split(path.delimiter).filter(Boolean);
+    if (platform === 'darwin')
+        dirs.push('/opt/homebrew/bin', '/usr/local/bin', '/usr/bin');
+    return (bin) => {
+        for (const dir of dirs) {
+            const full = path.join(dir, bin);
+            try {
+                accessSync(full, constants.X_OK);
+                return full;
+            }
+            catch {
+                // not here
+            }
+        }
+        return null;
+    };
+}
+/** One line, at most `max` characters, cut with an ellipsis. */
+export function oneLine(text, max = LOCAL_NOTIFY_MAX_CHARS) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max - 1).trimEnd()}…`;
+}
+/** An AppleScript string literal's inside: backslashes and quotes escaped. */
+export function appleScriptString(text) {
+    return text.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/** The first line of a command's stderr, or what is known instead. */
+function reasonOf(what, result) {
+    const line = result.stderr.split('\n').map((l) => l.trim()).find(Boolean);
+    if (line)
+        return `${what}: ${line}`;
+    if (result.error)
+        return `${what} did not run: ${result.error}`;
+    return `${what} exited with code ${result.code}`;
+}
+/** Title and body as the notification shows them. With no text, the title is the body. */
+function parts(message) {
+    const text = message.text?.trim();
+    return text
+        ? { title: oneLine(message.title, 120), body: oneLine(text) }
+        : { title: oneLine(message.title), body: null };
+}
+/**
+ * The channel for this machine, or null when it has nothing to show on.
+ * The command is picked once, when the channel is made.
+ */
+export function createLocalNotificationChannel(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const env = opts.env ?? process.env;
+    const exec = opts.exec ?? execCommand;
+    const which = opts.which ?? whichOn(env, platform);
+    const run = async (what, file, args) => {
+        let result;
+        try {
+            result = await exec(file, args, { timeoutMs: LOCAL_NOTIFY_TIMEOUT_MS });
+        }
+        catch (err) {
+            result = { code: null, stderr: '', error: err instanceof Error ? err.message : String(err) };
+        }
+        return result.code === 0 ? { id: 'local' } : { refused: reasonOf(what, result) };
+    };
+    const base = {
+        kind: 'local.notification',
+        can: { offers: false, attachments: false, markdown: false },
+        // After Telegram, before a plugin's: nothing leaves the machine.
+        priority: 10,
+    };
+    if (platform === 'darwin') {
+        const notifier = which('terminal-notifier');
+        if (notifier) {
+            return {
+                ...base,
+                describe: () => ({ label: 'System notification', where: 'shows on this Mac; a click opens the dashboard' }),
+                async deliver(message) {
+                    const { title, body } = parts(message);
+                    const args = ['-title', 'buddi', ...(body ? ['-subtitle', title, '-message', body] : ['-message', title]), '-group', `buddi-${message.id}`];
+                    const url = opts.dashboardUrl?.(message.link?.route ?? '');
+                    if (url)
+                        args.push('-open', url);
+                    return run('terminal-notifier', notifier, args);
+                },
+            };
+        }
+        const osascript = which('osascript');
+        if (!osascript)
+            return null;
+        return {
+            ...base,
+            describe: () => ({ label: 'System notification', where: 'shows on this Mac; opens nothing' }),
+            async deliver(message) {
+                const { title, body } = parts(message);
+                const script = body
+                    ? `display notification "${appleScriptString(body)}" with title "buddi" subtitle "${appleScriptString(title)}"`
+                    : `display notification "${appleScriptString(title)}" with title "buddi"`;
+                return run('osascript', osascript, ['-e', script]);
+            },
+        };
+    }
+    if (platform === 'linux') {
+        const notifySend = which('notify-send');
+        if (!notifySend || !(env.DISPLAY?.trim() || env.WAYLAND_DISPLAY?.trim()))
+            return null;
+        return {
+            ...base,
+            describe: () => ({ label: 'System notification', where: 'shows on this computer; opens nothing' }),
+            async deliver(message) {
+                const { title, body } = parts(message);
+                return run('notify-send', notifySend, [`buddi: ${title}`, ...(body ? [body] : [])]);
+            },
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=local-notification.js.map

package/packages/gateway/dist/channels/local-notification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-notification.js","sourceRoot":"","sources":["../../src/channels/local-notification.ts"],"names":[],"mappings":"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"}

package/packages/gateway/dist/chat/approvals.d.ts

@@ -1,9 +1,9 @@
 /**
  * Approvals in the terminal.
  *
- * The rule from ARCHITECTURE.md does not change because the surface did: the
- * owner decides, core moves the row, and the Executor is the only thing that
- * runs the effect. So this file is deliberately thin — it calls exactly the
+ * The rule in docs/architecture.md ("Actions and approvals") does not change
+ * because the surface did: the owner decides, core moves the row, and the
+ * Executor is the only thing that runs the effect. So this file is deliberately thin — it calls exactly the
  * functions the Telegram surface calls, in exactly the same order:
  *
  *   decideApproval → executeApproved → resumeJobForAction

package/packages/gateway/dist/chat/approvals.js

@@ -1,9 +1,9 @@
 /**
  * Approvals in the terminal.
  *
- * The rule from ARCHITECTURE.md does not change because the surface did: the
- * owner decides, core moves the row, and the Executor is the only thing that
- * runs the effect. So this file is deliberately thin — it calls exactly the
+ * The rule in docs/architecture.md ("Actions and approvals") does not change
+ * because the surface did: the owner decides, core moves the row, and the
+ * Executor is the only thing that runs the effect. So this file is deliberately thin — it calls exactly the
  * functions the Telegram surface calls, in exactly the same order:
  *
  *   decideApproval → executeApproved → resumeJobForAction

package/packages/gateway/dist/cli.d.ts

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { type ActionRecord } from '@buddi/core';
+import type { ApprovalResume } from '@buddi/runtime';
 import { type TerminalStyle } from './chat/terminal.js';
 export type ParsedArgs = {
     command: 'chat' | 'ask' | 'agents' | 'help';
@@ -9,7 +11,17 @@ export type ParsedArgs = {
     last: boolean;
     /** `--quiet`: suppress the per-run footer. Absent means "show it". */
     quiet?: boolean;
+    /** `ask --json`: one object on stdout instead of the answer's text. */
+    json?: boolean;
+    /** `ask --file <path>`, repeatable: stored in the library, sent with the question. */
+    files?: string[];
+    /** `ask --wait <seconds>`: how long to wait for an approval given elsewhere. */
+    waitSeconds?: number;
 };
+/** An approval the run stopped on, polled every this often under `--wait`. */
+export declare const WAIT_POLL_MS = 2000;
+/** What `ask` says when it stops for an approval. */
+export declare function approvalStopText(actionId: string, conversationId: string): string;
 export declare function parseArgs(argv: string[]): ParsedArgs;
 /** Where the prompt remembers what was typed. Beside every other artifact. */
 export declare function historyFile(env?: NodeJS.ProcessEnv): string;
@@ -45,4 +57,6 @@ export declare function shouldPage(text: string, style: TerminalStyle, rows: num
  * calls this function instead of re-implementing it.
  */
 export declare function main(argv?: string[]): Promise<void>;
+/** How a decided action wakes the run that stopped on it. */
+export declare function approvalResumeFrom(action: ActionRecord): ApprovalResume;
 //# sourceMappingURL=cli.d.ts.map

package/packages/gateway/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA+CA,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAyB7E,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA+BpD;AAiBD,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAExE;AAED,wEAAwE;AACxE,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAWlD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAQ1E;AAMD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,CAwCvC;AAMD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAIpF;AAoBD;;;;GAIG;AACH,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CA+GhF"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA4BA,OAAO,EAML,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,gBAAgB,CAAC;AAepE,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AA2B7E,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,YAAY,OAAQ,CAAC;AAElC,qDAAqD;AACrD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAKjF;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAyCpD;AAiBD,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAExE;AAED,wEAAwE;AACxE,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAWlD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAQ1E;AAMD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,CAwCvC;AAMD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAIpF;AAoBD;;;;GAIG;AACH,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAwHhF;AAaD,6DAA6D;AAC7D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CASvE"}

package/packages/gateway/dist/cli.js

@@ -24,8 +24,9 @@ import { homedir } from 'node:os';
 import path from 'node:path';
 import readline from 'node:readline/promises';
 import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { resolveDataDir, CLI_SURFACE, UnknownAgentError, } from '@buddi/core';
+import { getAction, resolveDataDir, CLI_SURFACE, TERMINAL_STATES, UnknownAgentError, } from '@buddi/core';
 import { failedTurnReply } from './surfaces/failure.js';
 import { createConversation, runAgent } from '@buddi/runtime';
 import { nativeSearchRecorder } from '@buddi/tool-web';
@@ -41,6 +42,7 @@ import { ChatSession, QUIET_UNAVAILABLE_TEXT } from './chat/session.js';
 import { Spinner, silentSpinner } from './chat/spinner.js';
 import { bold, dim, styleFor } from './chat/terminal.js';
 import { describeDatabaseError } from './db-ready.js';
+import { attachFile } from './chat/attach.js';
 import { createInlineMissionRunner } from './missions/inline.js';
 import { createEngagementHooks } from './missions/engagement.js';
 import { recapMissionId } from './missions/recap.js';
@@ -56,12 +58,20 @@ const USAGE = `buddi — your personal agents
   buddi ask "<question>"     one turn, then exit
   buddi ask "<question>" --agent <handle>
   buddi ask "<question>" --resume <id>
+  buddi ask "<question>" --file <path> --wait <seconds> --json
   buddi agents               every agent, its engine and whether it can run
   buddi agents show <handle> | set <handle> [--provider p] [--model m]
   buddi agents models | test <handle>
 
 In chat: /help lists every command. Exit codes for ask: 0 answered, 1 failed,
-2 stopped awaiting your approval.`;
+2 usage, 3 stopped awaiting your approval (or no database, or no such agent).`;
+/** An approval the run stopped on, polled every this often under `--wait`. */
+export const WAIT_POLL_MS = 2_000;
+/** What `ask` says when it stops for an approval. */
+export function approvalStopText(actionId, conversationId) {
+    return (`This run is waiting for your approval (action ${actionId}).\n` +
+        `Approve it on the dashboard or Telegram, then run buddi ask again with --resume ${conversationId}`);
+}
 export function parseArgs(argv) {
     const [raw, ...rest] = argv;
     const command = raw === 'chat' ? 'chat' : raw === 'ask' ? 'ask' : raw === 'agents' ? 'agents' : 'help';
@@ -90,6 +100,21 @@ export function parseArgs(argv) {
         else if (arg === '--quiet' || arg === '-q') {
             parsed.quiet = true;
         }
+        else if (arg === '--json' && command === 'ask') {
+            parsed.json = true;
+        }
+        else if (arg === '--file' && command === 'ask') {
+            const value = rest[++i];
+            if (!value)
+                throw new Error('--file needs a path');
+            parsed.files = [...(parsed.files ?? []), value];
+        }
+        else if (arg === '--wait' && command === 'ask') {
+            const value = Number(rest[++i]);
+            if (!Number.isFinite(value) || value <= 0)
+                throw new Error('--wait needs a number of seconds');
+            parsed.waitSeconds = value;
+        }
         else if (arg.startsWith('--')) {
             throw new Error(`unknown option: ${arg}`);
         }
@@ -245,7 +270,7 @@ export async function main(argv = process.argv.slice(2)) {
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
+        process.exit(2);
     }
     if (args.command === 'help') {
         console.log(USAGE);
@@ -253,9 +278,16 @@ export async function main(argv = process.argv.slice(2)) {
     }
     await loadEnvironment();
     const style = styleFor(process.env, process.stdout);
-    if (args.command === 'ask' && !args.question) {
+    // A script pipes its question in: `echo "…" | buddi ask`.
+    if (args.command === 'ask' && !args.question && process.stdin.isTTY !== true) {
+        const piped = (await readStdin()).trim();
+        if (piped !== '')
+            args.question = piped;
+    }
+    // With no question, `--resume` finishes a run that stopped for an approval.
+    if (args.command === 'ask' && !args.question && !args.resume) {
         console.error('buddi ask needs a question: buddi ask "can I afford a bike?"');
-        process.exit(1);
+        process.exit(2);
     }
     /*
      * The composition root, vault included. `createWiringAsync` hydrates the
@@ -269,9 +301,9 @@ export async function main(argv = process.argv.slice(2)) {
     }
     catch (err) {
         // A person is waiting at a prompt: fail fast, with the sentence that says
-        // what to do about it.
+        // what to do about it. No database is something to fix first: 3.
         console.error(describeDatabaseError(err, process.env.DATABASE_URL));
-        process.exit(1);
+        process.exit(3);
     }
     const { pool, registry, catalog, now, timezone, ctx } = wiring;
     // Fails closed: an unknown --agent is never coerced into the default. A
@@ -284,7 +316,7 @@ export async function main(argv = process.argv.slice(2)) {
         if (err instanceof UnknownAgentError) {
             console.error(err.message);
             console.error(`agents live in ${AGENTS_DIR}; run "buddi agents" to list them`);
-            process.exit(1);
+            process.exit(3);
         }
         throw err;
     }
@@ -292,8 +324,8 @@ export async function main(argv = process.argv.slice(2)) {
     // The *selected* agent's provider, not the process's: an agent pinned to
     // another provider is run on that provider or not at all.
     if (!selected.available) {
-        console.error(`@${selected.handle} cannot run: ${selected.unavailableReason}. Configure its account in dashboard Providers.`);
-        process.exit(1);
+        console.error(`@${selected.handle} cannot run: ${String(selected.unavailableReason).replace(/\.$/, '')}. Configure its account in dashboard Providers.`);
+        process.exit(3);
     }
     // The cause chain of every failed attempt, on stderr. At a terminal that is
     // where an operator looks, and it is the only record `buddi chat` keeps.
@@ -325,6 +357,9 @@ export async function main(argv = process.argv.slice(2)) {
                 wiring,
                 provider,
                 memoryPreamble,
+                json: args.json === true,
+                files: args.files ?? [],
+                waitSeconds: args.waitSeconds,
             });
             return;
         }
@@ -339,33 +374,166 @@ export async function main(argv = process.argv.slice(2)) {
 /* ------------------------------------------------------------------ *
  * ask — one turn, for a script
  * ------------------------------------------------------------------ */
+/** All of stdin, for a question piped in. */
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** How a decided action wakes the run that stopped on it. */
+export function approvalResumeFrom(action) {
+    const outcome = (action.outcome ?? {});
+    return {
+        actionId: action.id,
+        tool: action.tool,
+        state: action.state,
+        ...(outcome.result === undefined ? {} : { result: outcome.result }),
+        ...(typeof outcome.error === 'string' ? { error: outcome.error } : {}),
+    };
+}
+/**
+ * The action a conversation's last run stopped on, once it is decided and not
+ * yet taken up again. Only actions that belong to no queue job: those the
+ * queue wakes on its own.
+ */
+async function decidedButNotResumed(pool, conversationId) {
+    const { rows } = await pool.query(`select a.id from core.actions a
+      where a.conversation_id = $1 and a.job_id is null
+        and not exists (
+          select 1 from core.events e
+           where e.kind = 'run.resumed' and e.conversation_id = a.conversation_id
+             and e.payload->>'actionId' = a.id::text)
+      order by a.created_at desc
+      limit 1`, [conversationId]);
+    const id = rows[0]?.id;
+    if (!id)
+        return undefined;
+    const action = await getAction(pool, id);
+    if (!action)
+        return undefined;
+    return { action, decided: TERMINAL_STATES.includes(action.state) };
+}
+/** Poll an action until it is decided, or the time is up. */
+async function waitForDecision(pool, actionId, seconds) {
+    const deadline = Date.now() + seconds * 1000;
+    for (;;) {
+        const action = await getAction(pool, actionId);
+        if (action && TERMINAL_STATES.includes(action.state))
+            return action;
+        if (Date.now() >= deadline)
+            return undefined;
+        await new Promise((resolve) => setTimeout(resolve, Math.min(WAIT_POLL_MS, Math.max(0, deadline - Date.now()))));
+    }
+}
 /**
- * Unchanged in shape since the first version: the answer on stdout, everything
- * else on stderr, no spinner and no ANSI. The only addition is the exit code,
- * so a script can tell "answered" from "waiting for you".
+ * `ask` — one turn, for a script.
+ *
+ * The answer on stdout (or one JSON object with `--json`), everything else on
+ * stderr, no spinner and no ANSI. Exit 0 answered, 1 failed, 3 stopped for an
+ * approval: with `--wait` the run waits for a decision made elsewhere and
+ * finishes; without it, the sentence says how to finish it later.
  */
 async function ask(question, conversationId, deps) {
     const { wiring } = deps;
-    console.error(`conversation: ${conversationId}`);
+    const runId = randomUUID();
+    const startedAt = new Date();
+    if (!deps.json)
+        console.error(`conversation: ${conversationId}`);
+    const store = createCoreArtifactStore({ pool: wiring.pool, env: process.env });
+    const attachments = [];
+    for (const file of deps.files) {
+        try {
+            const saved = await attachFile(path.resolve(file), {
+                store,
+                readFile: (candidate) => readFile(candidate),
+                createdBy: wiring.ctx.ownerId,
+            });
+            attachments.push({
+                artifactId: saved.artifactId,
+                mime: saved.mime,
+                kind: saved.kind,
+                filename: saved.filename,
+                sizeBytes: saved.sizeBytes,
+            });
+        }
+        catch (err) {
+            console.error(`Could not attach ${file}: ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // No question: finish the run this conversation stopped on, if it can be.
+    let resume;
+    if (question === undefined) {
+        const found = await decidedButNotResumed(wiring.pool, conversationId);
+        if (!found) {
+            console.error('Nothing in that conversation is waiting to be finished. Ask a question: buddi ask "…" --resume <id>.');
+            process.exitCode = 2;
+            return;
+        }
+        let action = found.action;
+        if (!found.decided) {
+            action = deps.waitSeconds === undefined ? undefined : await waitForDecision(wiring.pool, found.action.id, deps.waitSeconds);
+            if (!action) {
+                report({ text: '', pendingActionId: found.action.id });
+                return;
+            }
+        }
+        resume = approvalResumeFrom(action);
+    }
+    function report(result, artifacts = []) {
+        if (deps.json) {
+            console.log(JSON.stringify({
+                text: result.text,
+                runId,
+                conversationId,
+                artifacts,
+                ...(result.pendingActionId ? { pendingActionId: result.pendingActionId } : {}),
+            }, null, 2));
+        }
+        else if (result.text !== '') {
+            console.log(result.text);
+        }
+        if (result.pendingActionId) {
+            console.error(`\n${approvalStopText(result.pendingActionId, conversationId)}`);
+            process.exitCode = 3;
+        }
+    }
+    const run = (turn) => runAgent({
+        agent: deps.agent.definition(wiring.now(), wiring.timezone),
+        provider: deps.provider,
+        registry: wiring.registry,
+        ctx: wiring.ctx,
+        pool: wiring.pool,
+        // The provider's own web search leaves the same audit row `web.search`
+        // does; see @buddi/tool-web's native.ts.
+        onNativeSearch: nativeSearchRecorder(wiring.pool),
+        conversationId,
+        runId,
+        ...turn,
+        loadArtifact: (id) => store.load(id),
+        surface: CLI_SURFACE,
+        memoryPreamble: deps.memoryPreamble,
+        onToolCall: (name, input) => {
+            if (!deps.json)
+                console.error(`⚙ ${name} ${JSON.stringify(input)}`);
+        },
+    });
     let result;
     try {
-        result = await runAgent({
-            agent: deps.agent.definition(wiring.now(), wiring.timezone),
-            provider: deps.provider,
-            registry: wiring.registry,
-            ctx: wiring.ctx,
-            pool: wiring.pool,
-            // The provider's own web search leaves the same audit row `web.search`
-            // does; see @buddi/tool-web's native.ts.
-            onNativeSearch: nativeSearchRecorder(wiring.pool),
-            conversationId,
-            userMessage: question,
-            surface: CLI_SURFACE,
-            memoryPreamble: deps.memoryPreamble,
-            onToolCall: (name, input) => {
-                console.error(`⚙ ${name} ${JSON.stringify(input)}`);
-            },
-        });
+        result = await run(resume
+            ? { resume }
+            : { userMessage: question, ...(attachments.length > 0 ? { attachments } : {}) });
+        // `--wait`: the owner decides on another surface, and this run finishes.
+        while (result.stopped === 'awaiting-approval' && result.pendingActionId && deps.waitSeconds !== undefined) {
+            if (!deps.json)
+                console.error(`waiting up to ${deps.waitSeconds}s for your decision on action ${result.pendingActionId}`);
+            const decided = await waitForDecision(wiring.pool, result.pendingActionId, deps.waitSeconds);
+            if (!decided)
+                break;
+            result = await run({ resume: approvalResumeFrom(decided) });
+        }
     }
     catch (err) {
         // A script still deserves the human sentence: `fetch failed` on stderr and
@@ -388,14 +556,17 @@ async function ask(question, conversationId, deps) {
         process.exitCode = 1;
         return;
     }
+    // What the run made: files an agent saved in this conversation since it began.
+    const { rows } = await wiring.pool.query(`select id, filename from core.artifacts
+      where conversation_id = $1 and created_at >= $2 and created_by <> $3 and deleted_at is null
+      order by created_at`, [conversationId, startedAt, wiring.ctx.ownerId]);
+    const made = rows.map((r) => ({ id: String(r.id), filename: r.filename }));
     // Safety net, not the mechanism: tool names are internal and nothing asks the
     // model to print one. This catches the answer of a model that did anyway.
-    console.log(stripToolNames(result.text));
-    if (result.stopped === 'awaiting-approval' && result.pendingActionId) {
-        console.error(`\nthis run is waiting for your approval (action ${result.pendingActionId}).\n` +
-            'Decide it with: buddi chat, then /approvals');
-        process.exitCode = 2;
-    }
+    report({
+        text: stripToolNames(result.text),
+        ...(result.stopped === 'awaiting-approval' && result.pendingActionId ? { pendingActionId: result.pendingActionId } : {}),
+    }, made);
 }
 /* ------------------------------------------------------------------ *
  * chat — the REPL