@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/commands/push.js

@@ -14,7 +14,7 @@ import { defineBranch, defineLeaf } from '../core/command.js';
 import { InputError, readStdinRaw } from '../core/io.js';
 import { push } from '../core/feed/feed.js';
 import { getNode, subscribersOf, subscriptionsOf, fullName } from '../core/canvas/index.js';
-import { readInboxSince, readCursor, writeCursor, coalesce, } from '../core/feed/inbox.js';
+import { readInboxSince, readInboxEntryById, readCursor, writeCursor, coalesce, } from '../core/feed/inbox.js';
 function requireCallerNode() {
     const id = process.env['CRTR_NODE_ID'];
     if (id === undefined || id.trim() === '') {
@@ -26,6 +26,25 @@ function requireCallerNode() {
     }
     return id.trim();
 }
+// ---------------------------------------------------------------------------
+// push <tier> — one leaf per tier, sharing body resolution
+// ---------------------------------------------------------------------------
+function alreadyFinalizedError(nodeStatus) {
+    return new InputError({
+        error: 'already_finalized',
+        message: `This node is already ${nodeStatus} — \`push final\` finishes a node once and cannot finalize it again.`,
+        next: 'Nothing to do here: the node is already finished. Do not push again from this node.',
+    });
+}
+export function mapFinalizeTransitionRaceError(nodeStatus, err) {
+    if (!(err instanceof Error))
+        return null;
+    if (!err.message.startsWith("illegal lifecycle transition: 'finalize' from status='"))
+        return null;
+    if (nodeStatus !== 'done' && nodeStatus !== 'dead' && nodeStatus !== 'canceled')
+        return null;
+    return alreadyFinalizedError(nodeStatus);
+}
 const TIER_BLURB = {
     update: 'routine progress — fans a pointer to subscribers, no forced wake',
     urgent: 'force-wake subscribers (inbox tier urgent)',
@@ -70,19 +89,15 @@ function makeTierLeaf(tier) {
             if (body === '') {
                 throw new InputError({ error: 'missing_body', message: 'no report body', field: 'body', next: 'Pass the body as an argument or on stdin.' });
             }
+            const node = tier === 'final' ? getNode(nodeId) : null;
             if (tier === 'final') {
-                const node = getNode(nodeId);
                 // A 2nd `push final` in one turn (or finalizing an already dead/canceled
                 // node) is an illegal finalize-from-terminal: the underlying transition()
                 // throws a raw Error that surfaces as an `internal` "crtr bug" on stderr.
                 // Catch it here as a CLEAN user-facing error — the node is simply already
                 // finished, so there is nothing to do.
                 if (node !== null && node.status !== 'active' && node.status !== 'idle') {
-                    throw new InputError({
-                        error: 'already_finalized',
-                        message: `This node is already ${node.status} — \`push final\` finishes a node once and cannot finalize it again.`,
-                        next: 'Nothing to do here: the node is already finished. Do not push again from this node.',
-                    });
+                    throw alreadyFinalizedError(node.status);
                 }
                 // A RESIDENT node with no subscribers is human-driven and has no one to
                 // submit a canonical result to: `push final` fans to subscribers, and a
@@ -102,8 +117,18 @@ function makeTierLeaf(tier) {
                     }
                 }
             }
-            const result = await push(nodeId, { kind: tier, body });
-            return { report_path: result.reportPath, delivered_to: result.deliveredTo, status: tier === 'final' ? 'done' : 'active' };
+            try {
+                const result = await push(nodeId, { kind: tier, body });
+                return { report_path: result.reportPath, delivered_to: result.deliveredTo, status: tier === 'final' ? 'done' : 'active' };
+            }
+            catch (err) {
+                if (tier === 'final') {
+                    const mapped = mapFinalizeTransitionRaceError(getNode(nodeId)?.status ?? node?.status ?? null, err);
+                    if (mapped !== null)
+                        throw mapped;
+                }
+                throw err;
+            }
         },
         render: (r) => {
             const n = Array.isArray(r['delivered_to']) ? r['delivered_to'].length : 0;
@@ -174,6 +199,49 @@ const feedReadLeaf = defineLeaf({
     },
 });
 // ---------------------------------------------------------------------------
+// feed message — read one inbox message's full body back from the jsonl
+// ---------------------------------------------------------------------------
+const feedMessageLeaf = defineLeaf({
+    name: 'message',
+    description: 'print one inbox entry\'s full body by id',
+    whenToUse: 'a digest line ended in `… (clipped — full message: crtr feed message <id>)` — run it to read the rest of that direct message. The full body lives in your inbox.jsonl; this prints it verbatim by the entry\'s short id. Read-only: it does NOT advance your inbox cursor.',
+    help: {
+        name: 'feed message',
+        summary: 'print the full body of one inbox entry, addressed by the short id shown in a clipped digest line',
+        params: [
+            { kind: 'positional', name: 'id', required: true, constraint: 'The short entry id from the digest\'s `… (full message: …)` pointer.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Whose inbox to read. Defaults to CRTR_NODE_ID; pass to read another node\'s inbox as an orchestrator.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'Node whose inbox was read.' },
+            { name: 'id', type: 'string', required: true, constraint: 'The requested entry id.' },
+            { name: 'found', type: 'boolean', required: true, constraint: 'True when an entry with that id exists.' },
+            { name: 'from', type: 'string', required: false, constraint: 'Sender of the message, when found.' },
+            { name: 'body', type: 'string', required: false, constraint: 'Full message body, when found.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: scans inbox.jsonl. Does NOT advance the cursor.'],
+    },
+    run: async (input) => {
+        const nodeId = typeof input['node'] === 'string' && input['node'].trim() !== ''
+            ? input['node'].trim()
+            : requireCallerNode();
+        const id = input['id'].trim();
+        const entry = readInboxEntryById(nodeId, id);
+        if (entry === undefined) {
+            return { node_id: nodeId, id, found: false };
+        }
+        const body = typeof entry.data?.['body'] === 'string' ? entry.data['body'] : entry.label;
+        return { node_id: nodeId, id, found: true, from: entry.from ?? 'system', body };
+    },
+    render: (r) => {
+        if (r['found'] !== true) {
+            return `No inbox entry with id ${r['id']} in ${r['node_id']}'s inbox. Re-read the digest with \`crtr feed read --all\`, or list raw entries to find the right id.`;
+        }
+        return `Full message ${r['id']} (from ${r['from']}):\n\n${r['body']}`;
+    },
+});
+// ---------------------------------------------------------------------------
 // feed peek — live state of the nodes below you, without draining anything
 // ---------------------------------------------------------------------------
 const STATUS_GLYPH = {
@@ -310,8 +378,8 @@ export function registerFeed() {
         help: {
             name: 'feed',
             summary: 'read the per-node inbox feed',
-            model: 'Each node has an inbox.jsonl that accumulates ~30-token pointers from publishers it subscribes to. The watcher drains this inbox to wake you, so the wake message you receive ALREADY IS the coalesced digest \u2014 dereference the reports that matter by reading their ref paths (a push carries a ref; a direct message inlines its full body). `feed read` is for PROACTIVELY polling before a wake (it advances the cursor); after a wake it reads empty because the cursor already moved \u2014 use `--all` to re-read history. An empty feed is normal while workers run \u2014 a worker that has not pushed leaves no pointer \u2014 so use `feed peek` to see the live state of the nodes below you (and whether to yield) without draining anything.',
+            model: 'Each node has an inbox.jsonl that accumulates ~30-token pointers from publishers it subscribes to. The watcher drains this inbox to wake you, so the wake message you receive ALREADY IS the coalesced digest \u2014 dereference the reports that matter by reading their ref paths (a push carries a ref; a direct message inlines a bounded body preview, and when that clips it ends in `crtr feed message <id>` to read the full text back from the jsonl). `feed read` is for PROACTIVELY polling before a wake (it advances the cursor); after a wake it reads empty because the cursor already moved \u2014 use `--all` to re-read history. An empty feed is normal while workers run \u2014 a worker that has not pushed leaves no pointer \u2014 so use `feed peek` to see the live state of the nodes below you (and whether to yield) without draining anything.',
         },
-        children: [feedReadLeaf, feedPeekLeaf],
+        children: [feedReadLeaf, feedMessageLeaf, feedPeekLeaf],
     });
 }

package/dist/commands/revive.js

@@ -1,8 +1,10 @@
 // `crtr canvas revive` — explicit node revival.
 //
 // Bypasses the daemon: directly relaunches the broker engine for a node that is
-// done, idle, or dead. Default behavior resumes the saved pi conversation
-// (--session <id>); pass --fresh to start a clean pi session against the context dir.
+// done, idle, or dead. Default behavior resumes the saved pi conversation by its
+// absolute session-file path (--session <path>) when that .jsonl still exists,
+// else falls through to a fresh launch; pass --fresh to force a clean pi session
+// against the context dir.
 //
 // `--all` sweeps EVERY disconnected node (engine not running, resumable session)
 // in one shot — the recovery for a reboot / mass-crash / daemon-down-a-while
@@ -14,13 +16,16 @@ import { reviveNode } from '../core/runtime/revive.js';
 import { listDisconnected, reviveAll } from '../core/runtime/revive-all.js';
 import { waitForBrokerViewSocket } from '../core/runtime/placement.js';
 import { getNode, fullName } from '../core/canvas/index.js';
+import { isPidAlive } from '../core/canvas/pid.js';
+import { readFault } from '../core/runtime/fault.js';
+import { isBusy } from '../core/runtime/busy.js';
 // ---------------------------------------------------------------------------
 // revive node
 // ---------------------------------------------------------------------------
 export const reviveLeaf = defineLeaf({
     name: 'revive',
     description: 'reopen a window for a done/idle/dead/canceled node, or --all disconnected nodes',
-    whenToUse: 'you want to bring a dormant node back yourself — reopen a window for one that is done, idle, dead, or canceled: resume a node you closed with `node close`, reopen a finished worker for a follow-up, or restart a crashed one now instead of waiting. It resumes the saved conversation by default, or can restart the node clean. Pass `--all` instead of a node id to bring back EVERY disconnected node at once (engine not running but a saved session intact) — the recovery after a reboot, a killed login/tmux session, a mass crash, or the daemon being down a while. You rarely need this for crashes — the daemon auto-revives those; reach for it to bring a node back on demand, to revive a canceled node the daemon will never touch on its own, or to mass-reconnect survivors after a disconnect event',
+    whenToUse: 'you want to bring a dormant node back yourself — reopen a window for one that is done, idle, dead, or canceled: resume a node you closed with `node lifecycle close`, reopen a finished worker for a follow-up, or restart a crashed one now instead of waiting. It resumes the saved conversation by default, or can restart the node clean. Pass `--all` instead of a node id to bring back EVERY disconnected node at once (engine not running but a saved session intact) — the recovery after a reboot, a killed login/tmux session, a mass crash, or the daemon being down a while. You rarely need this for crashes — the daemon auto-revives those; reach for it to bring a node back on demand, to revive a canceled node the daemon will never touch on its own, or to mass-reconnect survivors after a disconnect event',
     help: {
         name: 'canvas revive',
         summary: 'relaunch a node\'s broker engine (resuming its saved conversation), or --all disconnected nodes',
@@ -47,6 +52,14 @@ export const reviveLeaf = defineLeaf({
                 default: false,
                 constraint: 'When set, start a clean pi session (no --session). Default: resume the saved conversation. Ignored with --all (which always resumes).',
             },
+            {
+                kind: 'flag',
+                name: 'now',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'On-demand kick of an active-fault node (parked on a provider-owned fault, broker still alive). Its broker pid is alive, so an ordinary revive no-ops (double-launch guard) — --now SIGTERMs the live broker instead, so the daemon\'s crash→grace→resume path brings it back in ~20s instead of waiting out the auto-recovery grace. Only valid for a node that has a live daemon-owned auto provider fault and a live pid. Mutually exclusive with --all/--fresh.',
+            },
             // --force is a DELIBERATELY UNDOCUMENTED confirmation gate for --all (hidden
             // from -h; see FlagParam.hidden). Silas's intent (2026-06-13): a mass revive
             // can have large, unforeseen consequences, so the agent must NOT be able to
@@ -73,6 +86,7 @@ export const reviveLeaf = defineLeaf({
             { name: 'candidates', type: 'string', required: false, constraint: '--all preview: the node ids that WOULD be revived (newline-joined). Empty when none are disconnected.' },
             { name: 'revived', type: 'string', required: false, constraint: '--all sweep: the node ids whose broker engine was relaunched (newline-joined).' },
             { name: 'failed', type: 'string', required: false, constraint: '--all sweep: node ids whose relaunch threw, with the error (newline-joined). Absent when none failed.' },
+            { name: 'kicked', type: 'boolean', required: false, constraint: '--now only: true when the hanging node\'s live broker was SIGTERM\'d (the daemon resumes it on the saved session within ~20s). Absent for an ordinary revive.' },
         ],
         outputKind: 'object',
         effects: [
@@ -84,8 +98,16 @@ export const reviveLeaf = defineLeaf({
     },
     run: async (input) => {
         const all = input['all'] ?? false;
+        const now = input['now'] ?? false;
         const nodeId = input['node'];
         if (all) {
+            if (now) {
+                throw new InputError({
+                    error: 'conflicting_args',
+                    message: '`--now` kicks ONE hanging node; it cannot combine with `--all`.',
+                    next: 'Run `crtr canvas revive <node> --now` for the hanging node, or `crtr canvas revive --all` (no --now).',
+                });
+            }
             if (nodeId !== undefined) {
                 throw new InputError({
                     error: 'conflicting_args',
@@ -103,6 +125,13 @@ export const reviveLeaf = defineLeaf({
             });
         }
         const fresh = input['fresh'] ?? false;
+        if (now && fresh) {
+            throw new InputError({
+                error: 'conflicting_args',
+                message: '`--now` kicks a live hanging broker (SIGTERM → daemon resumes the SAVED session); `--fresh` is meaningless there.',
+                next: 'Run `crtr canvas revive <node> --now` (resumes), or `crtr canvas revive <node> --fresh` (no --now) to relaunch clean.',
+            });
+        }
         // Validate the node exists before attempting revival.
         const meta = getNode(nodeId);
         if (meta === null) {
@@ -112,11 +141,57 @@ export const reviveLeaf = defineLeaf({
                 next: 'List nodes with `crtr node inspect list`.',
             });
         }
+        // --now: the on-demand kick for an active fault. The broker is ALIVE (so
+        // reviveNode would no-op the double-launch guard) — SIGTERM it so the daemon's
+        // ordinary crash→grace→resume path recovers it on the saved session, the same
+        // thing the daemon does at the auto-recovery grace, just on demand. Gated on
+        // a live pid and a daemon-owned provider fault so it can't be used to nuke a
+        // healthy node.
+        if (now) {
+            const pid = meta.pi_pid;
+            const stall = readFault(nodeId);
+            if (pid == null || !isPidAlive(pid)) {
+                throw new InputError({
+                    error: 'not_hanging',
+                    message: `${nodeId} has no live broker — nothing to kick. --now is for a HANGING node (live broker parked on an active fault).`,
+                    next: 'Revive a dormant node with `crtr canvas revive ' + nodeId + '` (no --now).',
+                });
+            }
+            if (stall === null || stall.link !== 'pi→provider' || stall.retry.by !== 'daemon' || stall.retry.disposition !== 'auto') {
+                throw new InputError({
+                    error: 'not_hanging',
+                    message: `${nodeId} is live but not an active daemon-owned provider fault — --now refuses to SIGTERM a healthy node.`,
+                    next: 'Use --now only on a node the canvas shows as hanging (⚠). For a routine relaunch, omit --now.',
+                });
+            }
+            // Mirror the daemon's faultRecoveryVerdict, which never kills a BUSY engine: a
+            // node mid-turn (busy marker present) is making progress, not wedged —
+            // refuse rather than SIGTERM it mid-flight.
+            if (isBusy(nodeId)) {
+                throw new InputError({
+                    error: 'busy',
+                    message: `${nodeId} is mid-turn right now (busy) — --now refuses to SIGTERM a working engine; it has recovered on its own.`,
+                    next: 'Re-check the canvas — if it\'s no longer marked hanging (⚠), nothing to do.',
+                });
+            }
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch {
+                /* best-effort: the broker may have just died; the daemon owns the resume */
+            }
+            return {
+                window: null,
+                session: meta.tmux_session ?? null,
+                kicked: true,
+                message: `Sent SIGTERM to ${fullName(meta)} (${nodeId}, pid ${pid}). The daemon will resume it on the saved session within ~20s (crash→grace→resume).`,
+            };
+        }
         const result = reviveNode(nodeId, { resume: !fresh });
         // Revive returns once the broker process is launched, which can be seconds
         // before its view.sock listens. Callers (attach, the web shell's Wake) dial
         // immediately on return, so block here until the socket accepts.
-        const ready = waitForBrokerViewSocket(nodeId);
+        const ready = await waitForBrokerViewSocket(nodeId, result.launch?.exited);
         return {
             window: result.window ?? undefined,
             session: result.session,

package/dist/commands/search/answer.d.ts

@@ -0,0 +1 @@
+export declare const answerLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/search/answer.js

@@ -0,0 +1,50 @@
+import { defineLeaf } from '../../core/command.js';
+import { exaAnswer } from './exa.js';
+export const answerLeaf = defineLeaf({
+    name: 'answer',
+    description: 'get one grounded, cited answer to a question',
+    whenToUse: 'you have a specific question and want a single synthesized answer grounded in sources, rather than a ranked list of pages to read yourself. Best for factual lookups and "what/who/when" questions where you want the conclusion plus its citations. Reach for `web` instead when you want to browse and judge the raw results, or when the task is open-ended research rather than one answerable question.',
+    help: {
+        name: 'search answer',
+        summary: 'grounded answer via Exa — one synthesized natural-language answer plus the sources it cites',
+        params: [
+            { kind: 'positional', name: 'question', required: true, constraint: 'The question to answer. Natural language; phrase it as a question.' },
+        ],
+        output: [
+            { name: 'answer', type: 'string', required: true, constraint: 'The synthesized natural-language answer grounded in the cited sources.' },
+            { name: 'citations', type: 'object[]', required: true, constraint: 'The sources the answer draws on, each: title and url.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next command — read a citation in full, or fall back to raw results.' },
+        ],
+        outputKind: 'object',
+        effects: ['Sends one answer request to the Exa API (network). No local state changes.'],
+    },
+    run: async (input) => {
+        const question = input['question'];
+        const res = await exaAnswer({ query: question });
+        return {
+            answer: res.answer ?? '',
+            citations: res.citations ?? [],
+            follow_up: 'Read any cited source in full with the contents leaf after checking its schema. Want raw ranked results instead of a synthesized answer? Use the web leaf.',
+        };
+    },
+    render: (result) => {
+        const answer = result['answer'];
+        const citations = result['citations'];
+        const followUp = result['follow_up'];
+        if (answer.trim() === '') {
+            return `No answer was returned.\n\n${followUp}`;
+        }
+        const lines = [answer.trim(), ''];
+        if (citations.length > 0) {
+            lines.push(`Sources (${citations.length}):`);
+            citations.forEach((c, i) => {
+                const title = c.title !== undefined && c.title !== '' ? c.title : '(untitled)';
+                const url = c.url !== undefined ? ` — ${c.url}` : '';
+                lines.push(`${i + 1}. ${title}${url}`);
+            });
+            lines.push('');
+        }
+        lines.push(followUp);
+        return lines.join('\n');
+    },
+});

package/dist/commands/search/contents.d.ts

@@ -0,0 +1 @@
+export declare const contentsLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/search/contents.js

@@ -0,0 +1,96 @@
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { exaContents, parseUrls, renderResult, TEXT_MAX_CHARACTERS, } from './exa.js';
+import { puremdFetch } from './puremd.js';
+export const contentsLeaf = defineLeaf({
+    name: 'contents',
+    description: 'extract clean content from URLs you already have',
+    whenToUse: 'you already hold one or more URLs — from a prior `search web`/`answer`, a database, an RSS feed, or user input — and need their cleaned content or highlights. This does NOT search; it only extracts from the URLs you give it. Reach for `web` when you still need to find the pages, and `answer` when you want a synthesized response rather than raw page content.',
+    help: {
+        name: 'search contents',
+        summary: 'content extraction via Exa — cleaned highlights or full text for URLs you already have',
+        params: [
+            { kind: 'positional', name: 'urls', required: true, constraint: 'One or more URLs to extract, separated by commas or whitespace.' },
+            { kind: 'flag', name: 'text', type: 'bool', required: false, constraint: `Return cleaned full page text (capped at ${TEXT_MAX_CHARACTERS} characters per URL) instead of highlight excerpts. Off by default.` },
+            { kind: 'flag', name: 'max-age-hours', type: 'int', required: false, constraint: 'Maximum acceptable age of cached content, in hours; content older than this is freshly crawled. 0 forces a fresh crawl every time. Omit to use cache when available and crawl as fallback.' },
+        ],
+        output: [
+            { name: 'results', type: 'object[]', required: true, constraint: 'One per successfully extracted URL, each: title, url, and either highlight excerpts (default) or capped full text (--text).' },
+            { name: 'failures', type: 'object[]', required: true, constraint: 'URLs that could not be fetched by Exa or the pure.md fallback, each: url and reason.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next command for retrying failures or refreshing stale content.' },
+        ],
+        outputKind: 'object',
+        effects: ['Sends one contents request to the Exa API (network). URLs Exa fails to fetch are retried through the pure.md markdown service. No local state changes.'],
+    },
+    run: async (input) => {
+        const urls = parseUrls(input['urls']);
+        if (urls.length === 0)
+            throw usage('no URLs provided', { next: 'Pass one or more URLs separated by commas or whitespace.' });
+        const wantText = input['text'];
+        const maxAgeHours = input['maxAgeHours'];
+        const body = { urls };
+        if (wantText)
+            body['text'] = { maxCharacters: TEXT_MAX_CHARACTERS };
+        else
+            body['highlights'] = true;
+        if (maxAgeHours !== undefined)
+            body['maxAgeHours'] = maxAgeHours;
+        const res = await exaContents(body);
+        const results = res.results ?? [];
+        const fetched = new Set(results.map((r) => r.url).filter((u) => u !== undefined));
+        const exaFailures = [];
+        for (const s of res.statuses ?? []) {
+            if (s.status === 'success')
+                continue;
+            const url = s.id ?? '(unknown url)';
+            if (fetched.has(url))
+                continue;
+            const reason = typeof s.error === 'string'
+                ? s.error
+                : s.error?.tag ?? s.status ?? 'unknown error';
+            exaFailures.push({ url, reason });
+        }
+        // Fall back to pure.md for every URL Exa could not fetch. A pure.md success
+        // becomes a normal text result (flagged so the renderer can show its source);
+        // only URLs both services miss remain genuine failures.
+        const failures = [];
+        const fallbacks = await Promise.all(exaFailures.map(async (f) => ({ failure: f, pure: await puremdFetch(f.url, TEXT_MAX_CHARACTERS) })));
+        for (const { failure, pure } of fallbacks) {
+            if (pure.ok) {
+                results.push({ url: failure.url, title: failure.url, text: pure.text, source: 'pure.md' });
+            }
+            else {
+                failures.push({ url: failure.url, reason: `${failure.reason} (pure.md fallback: ${pure.reason})` });
+            }
+        }
+        return {
+            results,
+            failures,
+            follow_up: 'Stale or empty content? Re-run with --max-age-hours 0 to force a fresh crawl. Need to find more pages? Use the web leaf after checking its schema.',
+        };
+    },
+    render: (result) => {
+        const results = result['results'];
+        const failures = result['failures'];
+        const followUp = result['follow_up'];
+        const lines = [];
+        if (results.length === 0) {
+            lines.push('No content extracted.');
+        }
+        else {
+            lines.push(`Extracted ${results.length} URL${results.length === 1 ? '' : 's'}:`, '');
+            results.forEach((r, i) => {
+                lines.push(renderResult(r, i + 1));
+                lines.push('');
+            });
+        }
+        if (failures.length > 0) {
+            lines.push(`Failed (${failures.length}):`);
+            for (const f of failures)
+                lines.push(`- ${f.url} — ${f.reason}`);
+            lines.push('');
+        }
+        lines.push(followUp);
+        return lines.join('\n');
+    },
+});

package/dist/commands/search/exa.d.ts

@@ -0,0 +1,53 @@
+/** Resolve the Exa API key: EXA_API_KEY env first, then ~/.crouter/exa.key.
+ *  Never prompts and never proceeds keyless — throws a usage error naming both
+ *  options when neither is present. */
+export declare function getApiKey(): string;
+/** One Exa result row as returned by /search and /contents. Fields are present
+ *  only when the API supplies them. */
+export interface ExaResult {
+    title?: string;
+    url?: string;
+    publishedDate?: string;
+    author?: string;
+    highlights?: string[];
+    text?: string;
+    score?: number;
+    /** Set when the row came from a fallback fetcher (e.g. 'pure.md') rather than Exa. */
+    source?: string;
+}
+export interface ExaSearchResponse {
+    results?: ExaResult[];
+}
+export interface ExaAnswerResponse {
+    answer?: string;
+    citations?: Array<{
+        title?: string;
+        url?: string;
+    }>;
+}
+/** Per-URL fetch status returned by /contents (and /search livecrawls). */
+export interface ExaStatus {
+    id?: string;
+    status?: string;
+    error?: {
+        tag?: string;
+        httpStatusCode?: number;
+    } | string;
+}
+export interface ExaContentsResponse {
+    results?: ExaResult[];
+    statuses?: ExaStatus[];
+}
+export declare function exaSearch(body: Record<string, unknown>): Promise<ExaSearchResponse>;
+export declare function exaAnswer(body: Record<string, unknown>): Promise<ExaAnswerResponse>;
+export declare function exaContents(body: Record<string, unknown>): Promise<ExaContentsResponse>;
+/** Cap (characters) applied to full-text extraction so a single call cannot
+ *  blow up the caller's context. Highlights remain the default content mode. */
+export declare const TEXT_MAX_CHARACTERS = 4000;
+/** Split a positional URL argument on commas or whitespace into a clean list. */
+export declare function parseUrls(raw: string): string[];
+/** Split a comma-separated domain flag into a clean list, or undefined when empty. */
+export declare function parseDomains(raw: string | undefined): string[] | undefined;
+/** Render one result as agent-ready markdown: a numbered heading with title +
+ *  metadata line, then highlights as bullets or capped text as a blockquote. */
+export declare function renderResult(r: ExaResult, index: number): string;

package/dist/commands/search/exa.js

@@ -0,0 +1,155 @@
+// The only module that talks to api.exa.ai. Owns API-key resolution, the three
+// endpoint calls (/search, /answer, /contents), request shaping, and translation
+// of HTTP/transport failures into the crtr error taxonomy. Leaves never build
+// HTTP requests directly. Uses the Node global fetch — no HTTP dependency.
+import { join } from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
+import { usage, network } from '../../core/errors.js';
+import { classify } from '../../core/fault-classifier.js';
+import { clearFaultForCurrentNode, recordFaultForCurrentNode } from '../../core/runtime/fault.js';
+import { userScopeRoot } from '../../core/scope.js';
+const EXA_BASE = 'https://api.exa.ai';
+function endpointToOp(endpoint) {
+    switch (endpoint) {
+        case '/search':
+            return 'search /search';
+        case '/answer':
+            return 'search /answer';
+        case '/contents':
+            return 'search /contents';
+        default:
+            return `search ${endpoint}`;
+    }
+}
+/** Resolve the Exa API key: EXA_API_KEY env first, then ~/.crouter/exa.key.
+ *  Never prompts and never proceeds keyless — throws a usage error naming both
+ *  options when neither is present. */
+export function getApiKey() {
+    const env = process.env['EXA_API_KEY'];
+    if (env !== undefined && env.trim() !== '')
+        return env.trim();
+    const keyFile = join(userScopeRoot(), 'exa.key');
+    if (existsSync(keyFile)) {
+        const fromFile = readFileSync(keyFile, 'utf8').trim();
+        if (fromFile !== '')
+            return fromFile;
+    }
+    throw usage('no Exa API key found', {
+        next: `Set the EXA_API_KEY environment variable, or write the key to ${keyFile}.`,
+    });
+}
+/** POST a JSON body to an Exa endpoint and return the parsed JSON. Any non-2xx
+ *  response or transport failure becomes a crtr network error carrying Exa's
+ *  status/message and a concrete recovery hint. */
+async function exaPost(endpoint, body) {
+    const apiKey = getApiKey();
+    let res;
+    try {
+        res = await fetch(`${EXA_BASE}${endpoint}`, {
+            method: 'POST',
+            headers: { 'x-api-key': apiKey, 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const message = `Exa request failed: ${msg}`;
+        const classified = classify('cli→exa', err);
+        recordFaultForCurrentNode({
+            link: 'cli→exa',
+            op: endpointToOp(endpoint),
+            kind: classified.kind,
+            retry: { disposition: classified.disposition },
+            message,
+        });
+        throw network(message, {
+            next: 'Check network connectivity and retry. If it persists, simplify the query or reduce --num.',
+        });
+    }
+    if (!res.ok) {
+        let detail = '';
+        try {
+            detail = (await res.text()).slice(0, 500);
+        }
+        catch {
+            /* body unreadable — status line is enough */
+        }
+        const message = `Exa returned ${res.status} ${res.statusText}${detail ? `: ${detail}` : ''}`;
+        const classified = classify('cli→exa', {
+            status: res.status,
+            statusText: res.statusText,
+            ok: res.ok,
+            message: detail,
+        });
+        recordFaultForCurrentNode({
+            link: 'cli→exa',
+            op: endpointToOp(endpoint),
+            kind: classified.kind,
+            retry: { disposition: classified.disposition },
+            message,
+        });
+        throw network(message, {
+            received: `HTTP ${res.status}`,
+            next: res.status === 401
+                ? 'The API key was rejected. Verify EXA_API_KEY or ~/.crouter/exa.key.'
+                : 'Retry; if it persists, simplify the query, reduce --num, or drop domain filters.',
+        });
+    }
+    clearFaultForCurrentNode({ link: 'cli→exa' });
+    return (await res.json());
+}
+export function exaSearch(body) {
+    return exaPost('/search', body);
+}
+export function exaAnswer(body) {
+    return exaPost('/answer', body);
+}
+export function exaContents(body) {
+    return exaPost('/contents', body);
+}
+/** Cap (characters) applied to full-text extraction so a single call cannot
+ *  blow up the caller's context. Highlights remain the default content mode. */
+export const TEXT_MAX_CHARACTERS = 4000;
+/** Split a positional URL argument on commas or whitespace into a clean list. */
+export function parseUrls(raw) {
+    return raw
+        .split(/[\s,]+/)
+        .map((u) => u.trim())
+        .filter((u) => u !== '');
+}
+/** Split a comma-separated domain flag into a clean list, or undefined when empty. */
+export function parseDomains(raw) {
+    if (raw === undefined)
+        return undefined;
+    const list = raw
+        .split(',')
+        .map((d) => d.trim())
+        .filter((d) => d !== '');
+    return list.length > 0 ? list : undefined;
+}
+/** Render one result as agent-ready markdown: a numbered heading with title +
+ *  metadata line, then highlights as bullets or capped text as a blockquote. */
+export function renderResult(r, index) {
+    const lines = [];
+    const title = r.title !== undefined && r.title !== '' ? r.title : '(untitled)';
+    lines.push(`### ${index}. ${title}`);
+    const meta = [];
+    if (typeof r.url === 'string' && r.url !== '')
+        meta.push(r.url);
+    if (typeof r.publishedDate === 'string' && r.publishedDate !== '')
+        meta.push(r.publishedDate.slice(0, 10));
+    if (typeof r.author === 'string' && r.author !== '')
+        meta.push(r.author);
+    if (typeof r.source === 'string' && r.source !== '')
+        meta.push(`via ${r.source}`);
+    if (meta.length > 0)
+        lines.push(meta.join(' · '));
+    if (r.highlights !== undefined && r.highlights.length > 0) {
+        for (const h of r.highlights)
+            lines.push(`- ${h.replace(/\s+/g, ' ').trim()}`);
+    }
+    else if (r.text !== undefined && r.text !== '') {
+        lines.push(r.text.trim());
+    }
+    return lines.join('\n');
+}