@north-light/crouter 0.3.154

package/dist/commands/push.js

@@ -0,0 +1,166 @@
+// `crtr push` — the one verb up the graph.
+//
+//   crtr push update [body]   — routine progress to subscribers
+//   crtr push urgent [body]   — force-wake subscribers
+//   crtr push final  [body]   — finish: write result, mark node done, close window
+//
+// "push" is THE verb a node uses to talk to its managers; the tier is the
+// subcommand. The caller's node is resolved from CRTR_NODE_ID (injected by the
+// runtime into every node process). Absent ⇒ InputError — push is only
+// meaningful inside a live node.
+//
+// STAGE B-5: this verb is a PURE crtrd API client. Every tier goes through
+// `POST /nodes/{id}/reports` (`client.pushReport`); the report file write, the
+// per-subscriber inbox fan, and (final only) the lifecycle transition all happen
+// server-side inside feed `push()` (spec §7.4). This file reaches ZERO canvas
+// state-store code — no `core/feed`, no `core/canvas` accessors, no
+// `core/worktree`. The only node identity read is `CRTR_NODE_ID` (client-side).
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError, readStdinRaw } from '../core/io.js';
+import { ApiError } from '../api/index.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+import { markStopSignal } from '../core/runtime/stop-signals.js';
+function requireCallerNode() {
+    const id = process.env['CRTR_NODE_ID'];
+    if (id === undefined || id.trim() === '') {
+        throw new InputError({
+            error: 'no_node_context',
+            message: 'CRTR_NODE_ID is not set — push runs inside a canvas node.',
+            next: 'Run push from a node process spawned by the runtime.',
+        });
+    }
+    return id.trim();
+}
+const TIER_BLURB = {
+    update: 'routine progress — fans a pointer to subscribers, no forced wake',
+    urgent: 'force-wake subscribers (inbox tier urgent)',
+    final: 'finish: write the canonical result, mark the node done, close its window',
+};
+const TIER_WHENTOUSE = {
+    update: 'you have routine progress worth surfacing to your managers but nothing that needs them to act right now — a checkpoint, a finished sub-step, a status note while you keep working, a heads-up on a decision you made. Fans a lightweight pointer to every subscriber without forcing a wake. Nothing is pushed automatically — your managers see only what you push explicitly, so reach for this whenever you want a progress signal to reach them. Use push urgent instead when a manager must see it immediately, push final when the work is actually done.',
+    urgent: 'something your managers must see and act on immediately — you are blocked and need a decision, you hit an error that derails the plan, a discovery changes the scope, or a child reported something that has to travel further up the chain now. Same report mechanism as push update, but it force-wakes every subscriber instead of waiting for them to drain their feed on their own time. Use push update instead for progress that can wait, push final when you are handing back a finished result rather than raising an alarm.',
+    final: 'the work this node was spawned to do is complete and you are ready to hand back the canonical result — this writes that result, marks the node done, and closes its window, so it is the LAST thing you do here, not a progress note. Any node finishes this way. Use push update or push urgent instead while work is still in flight, and do not reach for this on a node working directly with the user: it has no manager to report up to and would close mid-conversation (the guard blocks it unless you pass --force after the user confirms).',
+};
+function makeTierLeaf(tier) {
+    return defineLeaf({
+        name: tier,
+        description: TIER_BLURB[tier],
+        whenToUse: TIER_WHENTOUSE[tier],
+        help: {
+            name: `push ${tier}`,
+            summary: TIER_BLURB[tier],
+            params: [
+                { kind: 'stdin', name: 'body', required: true, constraint: "Report body (markdown). Pipe it from a single-quoted heredoc (`<<'EOF'`) to preserve literal bytes." },
+                ...(tier === 'final'
+                    ? [{ kind: 'flag', name: 'force', type: 'bool', required: false, default: false, constraint: 'Override the guard that blocks `push final` on a human-attended node (a resident with no one to report up to). Only pass this after the user explicitly confirms they want this node finished.' }]
+                    : []),
+            ],
+            output: [
+                { name: 'report_path', type: 'string', required: true, constraint: 'Absolute path of the written report.' },
+                { name: 'notified', type: 'string[]', required: true, constraint: 'Subscriber node ids that received an inbox pointer.' },
+                ...(tier === 'final'
+                    ? [
+                        { name: 'transitioned', type: 'object', required: false, constraint: 'Present only for a final that flipped the node — { from, to } lifecycle-status transition applied server-side.' },
+                        { name: 'worktree_auto_dropped', type: 'boolean', required: false, constraint: 'Present only when this node owned a managed worktree with zero commits ahead of its base and no uncommitted changes — the server auto-dropped it instead of requiring `node worktree close` first (see worktree_auto_dropped_path).' },
+                        { name: 'worktree_auto_dropped_path', type: 'string', required: false, constraint: 'Present only alongside worktree_auto_dropped: the checkout path that was dropped.' },
+                    ]
+                    : []),
+            ],
+            outputKind: 'object',
+            effects: [
+                'Writes nodes/<nodeId>/reports/<ts>-<tier>.md (server-side).',
+                'Appends one inbox pointer per subscriber.',
+                ...(tier === 'final'
+                    ? [
+                        'Marks the node done (status + intent) server-side; its engine shuts down on next stop.',
+                        'When this node owns a managed worktree with zero commits ahead of its base and no uncommitted changes, the server auto-drops it instead of blocking on `node worktree close` (#327/#333); a worktree with real commits or real uncommitted changes still blocks with open_managed_worktree.',
+                    ]
+                    : []),
+            ],
+        },
+        run: async (input) => {
+            const nodeId = requireCallerNode();
+            let body = typeof input['body'] === 'string' ? input['body'].trim() : '';
+            if (body === '')
+                body = (await readStdinRaw()).trim();
+            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 client = cliClient();
+            // 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
+            // resident root conversation has none. Finishing it would shut its engine
+            // down mid-conversation. Block that unless the user confirms (--force).
+            // Keyed on lifecycle, NOT subscriber-count alone: a TERMINAL node with no
+            // subscribers was deliberately terminalized to owe a final — it
+            // self-completes server-side. This preflight reads the node through the
+            // API (NodeDetailDTO), never canvas.db — no state-store reach.
+            if (tier === 'final' && input['force'] !== true) {
+                let detail = null;
+                try {
+                    detail = await client.getNode(nodeId);
+                }
+                catch (err) {
+                    // A 404 here means the push itself will surface the canonical
+                    // unknown-node error — fall through and let it. Any other API failure
+                    // is a real problem worth surfacing now.
+                    if (!(err instanceof ApiError && err.status === 404)) {
+                        rethrowAsCliError(err);
+                    }
+                }
+                if (detail !== null && detail.lifecycle === 'resident' && detail.edges.subscribers.length === 0) {
+                    throw new InputError({
+                        error: 'no_final_recipient',
+                        message: 'This node is working directly with the user — it has no manager to submit a final result to. `push final` would end the conversation mid-stream.',
+                        next: 'You almost certainly do NOT need to finish here — just keep working with the user. If the user has explicitly asked you to finish and close this node, confirm with them first, then rerun with `crtr push final --force "<result>"`.',
+                    });
+                }
+            }
+            try {
+                const result = await client.pushReport(nodeId, { tier, body });
+                if (tier === 'final')
+                    markStopSignal(nodeId, 'pushedFinal');
+                return {
+                    report_path: result.report_path,
+                    notified: result.notified,
+                    ...(result.transitioned !== undefined ? { transitioned: result.transitioned } : {}),
+                    ...(result.worktree_auto_dropped === true
+                        ? { worktree_auto_dropped: true, worktree_auto_dropped_path: result.worktree_auto_dropped_path }
+                        : {}),
+                };
+            }
+            catch (err) {
+                rethrowAsCliError(err);
+            }
+        },
+        render: (r) => {
+            const n = Array.isArray(r['notified']) ? r['notified'].length : 0;
+            const line = tier === 'final'
+                ? 'Result recorded — node finished; its engine shuts down on next stop. Nothing more to do here: STOP your turn immediately. Reply with just "Done." and nothing else.'
+                : tier === 'urgent'
+                    ? `Urgent report fanned to ${n} subscriber(s) — they are force-woken.`
+                    : `Progress report fanned to ${n} subscriber(s).`;
+            const dropNote = r['worktree_auto_dropped'] === true ? `\n\nAuto-dropped a clean, zero-commit managed worktree at ${String(r['worktree_auto_dropped_path'])} — nothing to land.` : '';
+            return `${line}\n\n- report: ${r['report_path']}${dropNote}`;
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+export function registerPush() {
+    return defineBranch({
+        name: 'push',
+        rootEntry: {
+            concept: 'the one verb up the graph — a node reports to whoever subscribes to it',
+            desc: 'push a report (update / urgent / final) to your subscribers',
+            useWhen: 'sharing progress, raising an alert, or finishing your work',
+        },
+        help: {
+            name: 'push',
+            summary: 'push a report to your subscribers',
+            model: "A push writes a markdown report to the node's reports/ history and fans a lightweight pointer to every subscriber's inbox. Delivery inlines reports under 1,000 characters with their absolute path; larger reports remain pointers to dereference. Nothing is pushed automatically — the feed contains only what a node pushes explicitly, so push whenever you want a manager to see something. Pipe markdown via a single-quoted heredoc (`crtr push <tier> <<'EOF' … EOF`) so it reaches the report literally. `push final` is how ANY node finishes: write the canonical result, mark done, close the window.",
+        },
+        children: [makeTierLeaf('update'), makeTierLeaf('urgent'), makeTierLeaf('final')],
+    });
+}

package/dist/commands/revive.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const reviveLeaf: LeafDef;

package/dist/commands/revive.js

@@ -0,0 +1,174 @@
+// `crtr canvas revive` — mass node recovery.
+//
+// Sweeps EVERY disconnected node (engine not running, resumable session) in
+// one shot — the recovery for a reboot / mass-crash / daemon-down-a-while
+// event. It is a two-step gate: run it once to PREVIEW the candidates
+// (nothing is launched), then confirm to actually revive them.
+//
+// Reviving ONE named node is a per-node lifecycle action and lives instead at
+// `crtr node lifecycle revive <id>` (src/commands/node-lifecycle-revive.ts).
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { cliClient } from './api-client.js';
+import { routes } from '../api/index.js';
+// Purity (spec §1/§10, plan B-2): a `crtr` CLI process never opens canvas.db, so
+// this leaf's transitive RUNTIME import graph must not reach `core/canvas/db.ts`
+// or `core/canvas/canvas.ts`. The pre-API imports — `listDisconnected`/`reviveAll`
+// (revive-all.js) and `getNode`/`fullName` (the canvas barrel index.js) — all
+// reached `openDb`, so they are replaced by: the daemon client (`cliClient`),
+// `fullName` from labels.js DIRECTLY (labels.ts has zero runtime imports), and
+// `recordedPidLiveness` (pid.js → fs/ps only). The disconnected PREVIEW predicate
+// is re-implemented client-side over the API's node projections; the authoritative
+// sweep is the daemon's own `POST /nodes/revive-all` (which runs `reviveAll()`
+// server-side).
+import { fullName } from '../core/canvas/labels.js';
+import { recordedPidLiveness } from '../core/canvas/pid.js';
+// ---------------------------------------------------------------------------
+// revive --all
+// ---------------------------------------------------------------------------
+export const reviveLeaf = defineLeaf({
+    name: 'revive',
+    description: 'mass-reconnect every disconnected node',
+    whenToUse: 'you need 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 an ordinary crash — the daemon auto-revives those. To bring back ONE named node (a follow-up on a finished worker, a canceled node, or an on-demand kick of a hanging one), use `node lifecycle revive <id>` instead',
+    help: {
+        name: 'canvas revive',
+        summary: 'mass-reconnect every disconnected node (engine not running, resumable saved session)',
+        params: [
+            {
+                kind: 'flag',
+                name: 'all',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'Required (rejected without it) — confirms this is the graph-wide sweep, not a typo for a single-node revive (that lives at `node lifecycle revive <id>`). Excludes done/canceled (terminal-by-choice). Run it once to PREVIEW the candidates; nothing is launched until you confirm.',
+            },
+            // --force is a DELIBERATELY UNDOCUMENTED confirmation gate (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 discover a one-shot bypass by reading the schema. The unforced --all
+            // path PREVIEWS the candidates and instructs the agent to double-check
+            // with the USER before re-running; only then, having been told the flag,
+            // does it pass --force. Documenting it here would defeat that gate.
+            {
+                kind: 'flag',
+                name: 'force',
+                type: 'bool',
+                required: false,
+                default: false,
+                hidden: true,
+                constraint: 'Confirm the sweep (internal gate; see code comment).',
+            },
+        ],
+        output: [
+            { name: 'mode', type: 'string', required: true, constraint: '"preview" (the candidate list, nothing launched) or "revived" (the sweep ran).' },
+            { name: 'candidates', type: 'string', required: false, constraint: 'Preview: the node ids that WOULD be revived (newline-joined). Empty when none are disconnected.' },
+            { name: 'revived', type: 'string', required: false, constraint: 'Sweep: the node ids whose broker engine was relaunched (newline-joined).' },
+            { name: 'failed', type: 'string', required: false, constraint: 'Sweep: node ids whose relaunch threw, with the error (newline-joined). Absent when none failed.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Launches the detached headless broker engine (no tmux window) for every disconnected node.',
+            'Updates each revived node\'s canvas record: status=active, intent=null.',
+            'Without --force: launches NOTHING — only previews the disconnected candidates.',
+        ],
+    },
+    run: async (input) => {
+        if (input['all'] !== true) {
+            throw new InputError({
+                error: 'missing_parameter',
+                message: '`canvas revive` is the mass-recovery sweep and requires --all.',
+                next: 'Run `crtr canvas revive --all` to reconnect every disconnected node, or `crtr node lifecycle revive <id>` to bring back one named node.',
+            });
+        }
+        return runReviveAll(input);
+    },
+});
+/** Statuses a node lands in DELIBERATELY (`done`/`canceled`) — the daemon never
+ *  auto-revives these and neither does mass-revive. Mirrors
+ *  `runtime/revive-all.ts`'s `TERMINAL_BY_CHOICE`, inlined so this leaf never
+ *  imports that (db-reaching) module (plan B-2 purity). */
+const TERMINAL_BY_CHOICE = ['done', 'canceled'];
+/** Client-side re-implementation of `runtime/revive-all.ts`'s `isDisconnected`
+ *  PREVIEW predicate, over the API's `NodeSummaryDTO` (spec §6 parity is
+ *  structural, not byte-identical). Two differences from the server predicate,
+ *  both display-only — the --force sweep re-computes authoritatively server-side:
+ *   - liveness identity degrades to null (the summary omits `pi_pid_identity`),
+ *     so `recordedPidLiveness(pi_pid, null)` uses the trust-isPidAlive path.
+ *   - the resumable-session check is deferred to `sessionResumable` below (the
+ *     summary carries no session marker; detail carries `pi_session_id`). */
+function passesCheapDisconnectedFilter(s) {
+    if (s.kind === 'human')
+        return false; // the `crtr human` bridge is never a pi engine
+    if (recordedPidLiveness(s.pi_pid, null) === 'alive')
+        return false; // engine running → connected
+    // hasNoNaturalCycle: finished its own work, or terminal-by-choice — never mass-revive.
+    if (s.final_report != null || TERMINAL_BY_CHOICE.includes(s.status))
+        return false;
+    return true;
+}
+/** One line per candidate: `<id>  <full name>  [<status>]`. `fullName` needs the
+ *  node's description (its first-task label), which lives only on the detail
+ *  projection — so this renders from `NodeDetailDTO`s. */
+function describe(details) {
+    return details
+        .map((d) => `  ${d.node_id}  ${fullName(d)}  [${d.status}]`)
+        .join('\n');
+}
+/** The --all sweep, gated on confirmation. Without `--force` it PREVIEWS the
+ *  disconnected candidates and returns WITHOUT launching anything, telling the
+ *  agent to double-check with the user first (a mass revive can have large,
+ *  unforeseen consequences). With `--force` it delegates the authoritative sweep
+ *  to the daemon (`POST /nodes/revive-all` → `reviveAll()` server-side). */
+async function runReviveAll(input) {
+    const force = input['force'] ?? false;
+    const client = cliClient();
+    // Preview: replicate the disconnected set client-side. The cheap filter runs
+    // over the list projection; then each survivor's detail is fetched to confirm a
+    // resumable saved session (`pi_session_id`, the DTO's session proxy — the
+    // summary carries no session marker; `pi_session_file` is not projected, so a
+    // rare file-only node under-lists here, but the --force sweep still revives it).
+    const summaries = await client.listNodes();
+    const shortlist = summaries.filter(passesCheapDisconnectedFilter);
+    const details = [];
+    for (const s of shortlist) {
+        const detail = await client.getNode(s.node_id);
+        if (detail.pi_session_id != null)
+            details.push(detail);
+    }
+    if (details.length === 0) {
+        return {
+            mode: 'preview',
+            candidates: '',
+            message: 'No disconnected nodes — every node with a resumable session already has a running engine. Nothing to revive.',
+        };
+    }
+    if (!force) {
+        const list = describe(details);
+        return {
+            mode: 'preview',
+            candidates: details.map((d) => d.node_id).join('\n'),
+            // Directive for the AGENT (not a documented flag): this is a preview, and a
+            // mass revive can have large, unforeseen consequences — so confirm with the
+            // USER before proceeding, then re-run to actually revive.
+            message: `${details.length} disconnected node(s) WOULD be revived (RESUME). Nothing has been launched yet:\n\n` +
+                `${list}\n\n` +
+                `Reviving all of these at once can have large, unforeseen consequences (a flood of resumed engines, ` +
+                `cost, side effects from each node continuing its work). This is a preview only — DOUBLE-CHECK WITH THE ` +
+                `USER that they want every node above brought back before you proceed. Once they confirm, re-run the ` +
+                `revive with confirmation to actually relaunch them.`,
+        };
+    }
+    const res = await client.request('POST', routes.reviveAll());
+    const out = {
+        mode: 'revived',
+        revived: res.revived.join('\n'),
+        message: `Revived ${res.revived.length} disconnected node(s) (RESUME).`,
+    };
+    if (res.failed.length > 0) {
+        out['failed'] = res.failed.map((f) => `${f.node_id}: ${f.error}`).join('\n');
+        out['message'] =
+            `Revived ${res.revived.length} of ${res.revived.length + res.failed.length} disconnected node(s); ` +
+                `${res.failed.length} failed to relaunch (see failed).`;
+    }
+    return out;
+}

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;