@north-light/crouter 0.3.182 → 0.3.184

package/dist/daemon/__tests__/subtree-filter-freshness.test.js

@@ -0,0 +1,63 @@
+// Regression: crtrd served a PERMANENTLY stale `GET /v1/nodes?under=<id>`.
+//
+// `handleList`'s subtree scope came from nav-model's `subtreeIds`, whose reads
+// memoized into module-global Maps that only a `beginFrame()` cleared — and
+// `beginFrame()` had no call sites anywhere. In a TUI that re-renders, a memo is
+// one frame stale; in crtrd, which lives for hours, it is forever. The first
+// `?under=X` request that arrived BEFORE X had spawned children pinned `[]`
+// under X, and every later request returned that `[]` — Northlight's onboarding
+// progress bar sat at 0/100 for the life of the daemon while the unfiltered list
+// showed all 23 children with correct parents.
+//
+// This drives the real route handler against a real canvas db in exactly that
+// order: list the subtree while it is genuinely empty, THEN spawn children, then
+// list again. Nothing here would have failed with a hand-checked subtree walk —
+// only the request-order sequence catches it.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, subscribe } from '../../core/canvas/canvas.js';
+import { closeDb } from '../../core/canvas/db.js';
+import { nodeRoutes } from '../api/handlers/nodes.js';
+let home;
+function node(id, parent) {
+    return {
+        node_id: id, name: id, created: new Date().toISOString(), cwd: '/tmp/work',
+        kind: 'general', mode: 'base', lifecycle: 'terminal', status: 'active',
+        ...(parent !== undefined ? { parent } : {}),
+    };
+}
+/** GET /v1/nodes?under=<id> through the registered route, as crtrd serves it. */
+async function listUnder(id) {
+    const route = nodeRoutes.find((r) => r.method === 'GET' && r.pattern === '/v1/nodes');
+    const ctx = {
+        method: 'GET', path: '/v1/nodes', params: {},
+        query: new URLSearchParams({ under: id }), body: undefined,
+    };
+    const res = (await route.handler(ctx));
+    assert.equal(res.status, 200);
+    return res.body.map((r) => r.node_id);
+}
+before(() => { home = mkdtempSync(join(tmpdir(), 'crtr-subtree-')); process.env['CRTR_HOME'] = home; });
+beforeEach(() => { closeDb(); rmSync(home, { recursive: true, force: true }); });
+after(() => { closeDb(); rmSync(home, { recursive: true, force: true }); delete process.env['CRTR_HOME']; });
+test('a subtree query answered before any child exists does not poison later queries on the same daemon process', async () => {
+    const coordinator = 'coordinator';
+    createNode(node(coordinator));
+    // The poisoning request: the gateway polls within a second of the coordinator
+    // being created, before it has spawned anything.
+    assert.deepEqual(await listUnder(coordinator), [], 'an empty subtree is genuinely empty');
+    // The coordinator now spawns its children (parent subscribes_to child).
+    createNode(node('research-gmail', coordinator));
+    createNode(node('research-misc', coordinator));
+    subscribe(coordinator, 'research-gmail');
+    subscribe(coordinator, 'research-misc');
+    assert.deepEqual((await listUnder(coordinator)).sort(), ['research-gmail', 'research-misc'], 'the same long-lived process must see children spawned after its first subtree query');
+    // A grandchild spawned later still surfaces — the walk is re-read at every
+    // level, not just the root's direct edges.
+    createNode(node('writer-connectivity', 'research-gmail'));
+    subscribe('research-gmail', 'writer-connectivity');
+    assert.deepEqual((await listUnder(coordinator)).sort(), ['research-gmail', 'research-misc', 'writer-connectivity'], 'a grandchild spawned after an earlier query surfaces too');
+});

package/dist/pi-extensions/canvas-context-intro.d.ts

@@ -68,7 +68,7 @@ interface PiLike {
 }
 /** Build the full bearings baseline for a conversation without inherited
  *  crouter context. Exported for testing. */
-export declare function buildContextIntro(nodeId: string): Promise<string>;
+export declare function buildContextIntro(nodeId: string, seen?: Set<string>): Promise<string>;
 /** Build the compact node-scoped update for a fork whose copied branch already
  *  carries a full crouter baseline. Exported for testing. */
 export declare function buildForkContextIntro(nodeId: string): Promise<string>;

package/dist/pi-extensions/canvas-context-intro.js

@@ -30,6 +30,7 @@ import { CONTEXT_INTRO_CUSTOM_TYPE } from '../shared/generated-context.js';
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { buildContextBearingsFromState, buildForkBearingsFromState, buildProjectContextBlockForBroker } from '../core/runtime/broker-extension-render.js';
 import { situationalContextBlock } from '../core/runtime/situational-context.js';
+import { saveInjectedDocs, sharedInjectedDocs } from '../core/substrate/injected-store.js';
 import { truncateToWidth } from './truncate.js';
 /** The `customType` stamped on the injected session message. Used both to write
  *  the entry and to detect it on resume (the idempotency guard). Defined beside
@@ -41,9 +42,9 @@ export { CONTEXT_INTRO_CUSTOM_TYPE };
 // ---------------------------------------------------------------------------
 /** Build the full bearings baseline for a conversation without inherited
  *  crouter context. Exported for testing. */
-export async function buildContextIntro(nodeId) {
+export async function buildContextIntro(nodeId, seen) {
     const state = await brokerExtensionState(nodeId);
-    return buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextBlock(nodeId));
+    return buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextBlock(nodeId), seen);
 }
 /** Build the compact node-scoped update for a fork whose copied branch already
  *  carries a full crouter baseline. Exported for testing. */
@@ -160,15 +161,25 @@ export function registerCanvasContextIntro(pi) {
         // this fork's new node-scoped facts. A non-crouter branch has no such entry.
         const inherited = contextEntries.length > 0;
         const forked = state.node.fork_from !== null;
+        // The baseline branch renders workspace-open docs, so it threads the
+        // PROCESS-SHARED dedup set: the on-read hook (canvas-doc-substrate) holds
+        // the same Set instance, so a front door delivered here never re-delivers
+        // on a later read beneath its store. The fork branch renders no workspace
+        // docs and needs no set.
+        const seen = inherited && forked ? undefined : sharedInjectedDocs(nodeId);
         const content = inherited && forked
             ? buildForkBearingsFromState(state, situationalContextBlock(nodeId))
-            : buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextBlock(nodeId));
+            : buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextBlock(nodeId), seen);
         pi.sendMessage({
             customType: CONTEXT_INTRO_CUSTOM_TYPE,
             content,
             display: true,
             details: { nodeId },
         });
+        // Persist what the baseline delivered so the dedup survives a later
+        // dormancy → revive(resume) into a fresh process.
+        if (seen !== undefined)
+            saveInjectedDocs(nodeId, seen);
     });
 }
 export default registerCanvasContextIntro;

package/dist/pi-extensions/canvas-doc-substrate.js

@@ -36,7 +36,7 @@ import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { renderPreferencesFromState } from '../core/runtime/broker-extension-render.js';
 import { renderOnReadDocsForSubject } from '../core/substrate/on-read.js';
 import { clearSessionCache } from '../core/substrate/session-cache.js';
-import { loadInjectedDocs, saveInjectedDocs } from '../core/substrate/injected-store.js';
+import { loadInjectedDocs, saveInjectedDocs, sharedInjectedDocs } from '../core/substrate/injected-store.js';
 import { autoLoadedContextInner, mergeAutoLoadedContext } from './envelope-merge.js';
 // ---------------------------------------------------------------------------
 // Extension
@@ -65,7 +65,12 @@ export function registerCanvasDocSubstrate(pi) {
     // dedup must carry forward. The one launch path that begins a FRESH transcript
     // (reviveNode with resume=false) deletes the file, so a new conversation
     // rehydrates empty here. See core/substrate/injected-store.ts.
-    const injectedDocs = loadInjectedDocs(nodeId);
+    //
+    // The set is the PROCESS-SHARED instance (sharedInjectedDocs), so the
+    // context-intro extension's workspace-open render grows the same set this
+    // hook dedups against — a front door delivered at boot never re-delivers on
+    // a later read beneath its store.
+    const injectedDocs = sharedInjectedDocs(nodeId);
     pi.on('session_start', () => {
         // Only the per-session substrate PARSE cache resets each session (so the
         // corpus is re-scanned, picking up memory writes). injectedDocs is
@@ -112,6 +117,12 @@ export function registerCanvasDocSubstrate(pi) {
             const expanded = rawPath.startsWith('~') ? join(homedir(), rawPath.slice(1)) : rawPath;
             const absFile = resolve(cwd, expanded);
             const state = await brokerExtensionState(nodeId);
+            // Merge the on-disk set: an out-of-process delivery (the daemon's
+            // warm-spare claim pushes bearings — including workspace-open docs —
+            // into the live session and persists what it delivered) must dedup here
+            // too. Cheap: one tiny JSON read per `read`.
+            for (const real of loadInjectedDocs(nodeId))
+                injectedDocs.add(real);
             const injected = renderOnReadDocsForSubject(state.subject, absFile, injectedDocs);
             if (injected === '')
                 return; // nothing surfaced — pass the read through unchanged

package/dist/shared/generated-context.d.ts

@@ -46,6 +46,10 @@ export declare function generatedContextText(message: GeneratedContextMessageLik
 export declare function formatContextNudge(note: string): string;
 export declare function isInboxDigest(text: string): boolean;
 export declare function extractInboxSender(text: string): string | null;
+/** Node ids whose section of this digest reports a finished node. Sections are
+ *  delimited by their `From <sender>` headers, so a final never attaches to the
+ *  neighbouring sender. */
+export declare function inboxFinishedSenders(text: string): string[];
 /** Exact producer-owned marker for the continuation a successor broker inserts
  * after a runtime restart. Other recovery bodies intentionally do not match. */
 export declare function isRuntimeRestartContinuation(message: GeneratedContextMessageLike): boolean;

package/dist/shared/generated-context.js

@@ -101,14 +101,33 @@ function nudgeSummary(body) {
 // Senders are node ids, the two reserved words, or the daemon itself (crtrd —
 // review notes and other daemon-originated node messages).
 const INBOX_HEADER_RE = /^From ([a-z0-9]+(?:-[a-z0-9]+)+|system|human|crtrd) — (\d+) update/m;
+const INBOX_HEADERS_RE = /^From ([a-z0-9]+(?:-[a-z0-9]+)+|system|human|crtrd) — (\d+) update/gm;
+// Entry lines inside a section, rendered by core/runtime/broker/inbox.ts as
+// `  [<kind>]`. A final is the one kind that ends the sender's node.
+const FINISHED_ENTRY_RE = /^ {2}\[(?:final|completed)\]/m;
 export function isInboxDigest(text) {
     return INBOX_HEADER_RE.test(text);
 }
 export function extractInboxSender(text) {
     return INBOX_HEADER_RE.exec(text)?.[1] ?? null;
 }
+/** Node ids whose section of this digest reports a finished node. Sections are
+ *  delimited by their `From <sender>` headers, so a final never attaches to the
+ *  neighbouring sender. */
+export function inboxFinishedSenders(text) {
+    const headers = [...text.matchAll(INBOX_HEADERS_RE)];
+    const senders = [];
+    for (const [index, header] of headers.entries()) {
+        const start = header.index ?? 0;
+        const end = headers[index + 1]?.index ?? text.length;
+        const sender = header[1];
+        if (sender !== undefined && FINISHED_ENTRY_RE.test(text.slice(start, end)))
+            senders.push(sender);
+    }
+    return senders;
+}
 function inboxSummary(body) {
-    const headers = [...body.matchAll(/^From ([a-z0-9]+(?:-[a-z0-9]+)+|system|human|crtrd) — (\d+) update/gm)];
+    const headers = [...body.matchAll(INBOX_HEADERS_RE)];
     if (headers.length === 0)
         return 'node update';
     const updates = headers.reduce((total, match) => total + Number(match[2] ?? 0), 0);

package/dist/shared/tool-groups.d.ts

@@ -1,9 +1,9 @@
 /** Broker-generated activity recap for one completed tool-call group. Changed
- * files are counted deterministically by the viewer's GroupActivityRecorder;
- * deletions have no tool of their own, so only the model can evidence them. */
+ * files and spawned/finished nodes are counted deterministically by the viewer's
+ * GroupActivityRecorder; deletions have no tool of their own, so only the model
+ * can evidence them. */
 export interface ToolGroupSummary {
     bullets: string[];
-    nodesSpawned: number;
     filesDeleted: number;
 }
 export interface ToolGroupMessageLike {

package/dist/shared/tool-groups.js

@@ -2,7 +2,7 @@
 // Keep this independent of renderer state: both live event tracking and snapshot
 // reconstruction must agree on which prose closes a run of tools.
 import { generatedContextPresentation, generatedContextText } from './generated-context.js';
-const TOOL_GROUP_SUMMARY_KEYS = new Set(['bullets', 'nodesSpawned', 'filesDeleted']);
+const TOOL_GROUP_SUMMARY_KEYS = new Set(['bullets', 'filesDeleted']);
 const MAX_TOOL_GROUP_BULLETS = 5;
 const MAX_TOOL_GROUP_BULLET_LENGTH = 1_000;
 /** Validate the one durable summary shape and cap its display-sized fields.
@@ -19,15 +19,12 @@ export function normalizeToolGroupSummary(value) {
         return null;
     if (!record.bullets.every((bullet) => typeof bullet === 'string' && bullet.trim() !== ''))
         return null;
-    if (typeof record.nodesSpawned !== 'number' || !Number.isSafeInteger(record.nodesSpawned) || record.nodesSpawned < 0)
-        return null;
     if (typeof record.filesDeleted !== 'number' || !Number.isSafeInteger(record.filesDeleted) || record.filesDeleted < 0)
         return null;
     return {
         bullets: record.bullets
             .slice(0, MAX_TOOL_GROUP_BULLETS)
             .map((bullet) => bullet.trim().slice(0, MAX_TOOL_GROUP_BULLET_LENGTH).trimEnd()),
-        nodesSpawned: record.nodesSpawned,
         filesDeleted: record.filesDeleted,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.182",
+  "version": "0.3.184",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.182",
+  "version": "0.3.184",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.182",
+      "version": "0.3.184",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/scripts/postinstall.mjs

@@ -40,7 +40,7 @@ async function main() {
     console.warn('[crtr postinstall] runtime installation failed (non-fatal); no runtime generation was produced. Run `crtr` for remediation guidance or reinstall:', error?.message ?? error);
   }
   await provisionRenderer();
-  console.log('crouter installed. Run `crtr sys setup` to install the companion pi extensions, Claude OAuth, tmux/nvim, and your Exa key.');
+  console.log('crouter installed. Run `crtr sys setup` to install the companion pi extensions, Claude OAuth, and tmux/nvim.');
 }
 
 await main();

package/dist/clients/attach/render/markdown-headings.js

@@ -1,93 +0,0 @@
-// Terminal-specific Markdown heading hierarchy for the attach viewer.
-//
-// pi-tui's MarkdownTheme exposes one `heading(text)` callback without the
-// heading depth. Its renderer does know the depth, but does not pass it to the
-// theme, so every heading otherwise receives the same yellow mdHeading paint.
-// Decorate only the source text of H3–H6 before it reaches pi-tui: pi still
-// owns parsing, wrapping, inline formatting, and H1/H2's established styling.
-// This stays attach-local — persisted messages and copied text remain ordinary
-// Markdown without terminal escape sequences.
-//
-// The same per-block copy carries the viewer's other source-text transform:
-// private-use `U+XXXX` references become their glyphs (see glyph-codepoints.ts),
-// so an agent that cannot type a Nerd Font character can still put one on
-// screen.
-import { expandGlyphCodepoints } from './glyph-codepoints.js';
-const ATX_HEADING = /^(\s{0,3})(#{3,6})(?:[ \t]+|$)(.*?)([ \t]+#+[ \t]*)?$/;
-const FENCE_OPEN = /^\s{0,3}(`{3,}|~{3,})/;
-// A constant-lightness ramp from warm yellow to cool blue, with saturation
-// deliberately reduced at each step so the hierarchy recedes rather than
-// becoming a tour of unrelated accent colors.
-const HEADING_COLORS = [
-    [232, 194, 104],
-    [207, 194, 145],
-    [181, 184, 174],
-    [157, 170, 180],
-    [135, 153, 164],
-    [116, 135, 147],
-];
-function headingColor(level) {
-    const [r, g, b] = HEADING_COLORS[level - 1];
-    return (text) => `\x1b[1;38;2;${r};${g};${b}m${text}\x1b[22;39m`;
-}
-/** Style ATX headings with a scan-friendly terminal hierarchy. The Markdown
- * markers are syntax, not content, so omit them from the rendered line.
- * Fenced examples remain literal Markdown, never decorated terminal output. */
-export function styleAttachMarkdownHeadings(markdown) {
-    let fence;
-    return markdown.split('\n').map((line) => {
-        const fenceMatch = FENCE_OPEN.exec(line);
-        if (fence !== undefined) {
-            if (fenceMatch?.[1][0] === fence)
-                fence = undefined;
-            return line;
-        }
-        if (fenceMatch) {
-            fence = fenceMatch[1][0];
-            return line;
-        }
-        const match = ATX_HEADING.exec(line);
-        if (!match)
-            return line;
-        const [, indent, hashes, body, closing = ''] = match;
-        if (body === '')
-            return line;
-        return `${indent}${headingColor(hashes.length)(body)}`;
-    }).join('\n');
-}
-/** Every source-text transform the viewer applies to a Markdown-bearing block,
- *  in one place: heading hierarchy, then glyph expansion. */
-function renderableText(markdown) {
-    return expandGlyphCodepoints(styleAttachMarkdownHeadings(markdown));
-}
-/** Copy a pi message for terminal rendering and decorate only Markdown-bearing
- * text/thinking blocks. The broker's source event is never mutated. */
-export function styleAttachMessageMarkdown(message) {
-    if (typeof message !== 'object' || message === null || !('content' in message))
-        return message;
-    const candidate = message;
-    if (typeof candidate.content === 'string') {
-        return { ...candidate, content: renderableText(candidate.content) };
-    }
-    if (!Array.isArray(candidate.content))
-        return message;
-    return {
-        ...candidate,
-        content: candidate.content.map((part) => {
-            if (typeof part !== 'object' || part === null)
-                return part;
-            const block = part;
-            if (block.type === 'text' && typeof block.text === 'string') {
-                return { ...block, text: renderableText(block.text) };
-            }
-            if (block.type === 'thinking' && typeof block.thinking === 'string') {
-                return { ...block, thinking: renderableText(block.thinking) };
-            }
-            return part;
-        }),
-    };
-}
-/** Copy an expanded pi summary without changing its persisted source. */
-export function styleAttachSummaryMarkdown(message) {
-    return { ...message, summary: renderableText(message.summary) };
-}

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

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

package/dist/commands/search/answer.js

@@ -1,50 +0,0 @@
-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

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

package/dist/commands/search/contents.js

@@ -1,96 +0,0 @@
-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', repeatable: true, required: true, constraint: 'One or more URL tokens to extract. Each token may contain URLs 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 = input['urls'].flatMap(parseUrls);
-        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

@@ -1,53 +0,0 @@
-/** 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;