@north-light/crouter 0.3.181 → 0.3.183

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;

package/dist/commands/search/exa.js

@@ -1,157 +0,0 @@
-// 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, {
-            // The transport status, never `received` — that slot names the caller's
-            // offending VALUE, and Exa is not complaining about the number 401.
-            http_status: 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');
-}

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

@@ -1,11 +0,0 @@
-export type PuremdResult = {
-    ok: true;
-    text: string;
-} | {
-    ok: false;
-    reason: string;
-};
-/** Fetch a single URL's content as markdown via pure.md, capped at maxChars.
- *  Never throws — any transport or HTTP failure becomes { ok: false, reason }
- *  so the caller can keep the URL in its failures list. */
-export declare function puremdFetch(url: string, maxChars: number): Promise<PuremdResult>;

package/dist/commands/search/puremd.js

@@ -1,53 +0,0 @@
-// Fallback content fetcher: when Exa cannot fetch a URL, we re-fetch it through
-// pure.md (https://pure.md), which renders any page to clean markdown. This is
-// the ONLY module that talks to pure.md. API-key resolution is optional — the
-// service works keyless (rate-limited); a key raises limits.
-import { join } from 'node:path';
-import { readFileSync, existsSync } from 'node:fs';
-import { userScopeRoot } from '../../core/scope.js';
-const PUREMD_BASE = 'https://pure.md';
-/** Resolve an optional pure.md API token: PUREMD_API_KEY env first, then
- *  ~/.crouter/puremd.key. Returns undefined when neither is set — pure.md is
- *  usable keyless, so a missing token is not an error. */
-function getApiKey() {
-    const env = process.env['PUREMD_API_KEY'];
-    if (env !== undefined && env.trim() !== '')
-        return env.trim();
-    const keyFile = join(userScopeRoot(), 'puremd.key');
-    if (existsSync(keyFile)) {
-        const fromFile = readFileSync(keyFile, 'utf8').trim();
-        if (fromFile !== '')
-            return fromFile;
-    }
-    return undefined;
-}
-/** Fetch a single URL's content as markdown via pure.md, capped at maxChars.
- *  Never throws — any transport or HTTP failure becomes { ok: false, reason }
- *  so the caller can keep the URL in its failures list. */
-export async function puremdFetch(url, maxChars) {
-    const headers = {};
-    const key = getApiKey();
-    if (key !== undefined)
-        headers['x-puremd-api-token'] = key;
-    let res;
-    try {
-        res = await fetch(`${PUREMD_BASE}/${url}`, { headers });
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return { ok: false, reason: `pure.md request failed: ${msg}` };
-    }
-    if (!res.ok) {
-        return { ok: false, reason: `pure.md returned ${res.status} ${res.statusText}` };
-    }
-    let text;
-    try {
-        text = (await res.text()).trim();
-    }
-    catch {
-        return { ok: false, reason: 'pure.md response body unreadable' };
-    }
-    if (text === '')
-        return { ok: false, reason: 'pure.md returned empty content' };
-    return { ok: true, text: text.slice(0, maxChars) };
-}

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

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

package/dist/commands/search/web.js

@@ -1,65 +0,0 @@
-import { defineLeaf } from '../../core/command.js';
-import { exaSearch, parseDomains, renderResult, TEXT_MAX_CHARACTERS, } from './exa.js';
-const SEARCH_TYPES = ['auto', 'fast', 'instant', 'deep-lite', 'deep', 'deep-reasoning'];
-export const webLeaf = defineLeaf({
-    name: 'web',
-    description: 'find web pages relevant to a query, with highlight excerpts',
-    whenToUse: 'you need to discover web pages relevant to a query and read query-matched excerpts from them — the default web search. Use this for open-ended research, finding sources, or gathering current information. Reach for `answer` instead when you want one synthesized, cited answer to a specific question rather than a ranked list of pages; reach for `contents` when you already hold the URLs and only need their content.',
-    help: {
-        name: 'search web',
-        summary: 'web search via Exa — ranked results with query-relevant highlight excerpts (or full text)',
-        params: [
-            { kind: 'positional', name: 'query', required: true, constraint: 'The search query. Natural language; be specific.' },
-            { kind: 'flag', name: 'type', type: 'enum', choices: [...SEARCH_TYPES], required: false, default: 'auto', constraint: 'Search depth. auto balances relevance and speed; fast/instant trade depth for latency; deep-lite/deep/deep-reasoning run multi-query expansion and rank the combined set for harder synthesis.' },
-            { kind: 'flag', name: 'num', type: 'int', required: false, default: 10, constraint: 'Number of results to return.' },
-            { kind: 'flag', name: 'text', type: 'bool', required: false, constraint: `Return cleaned full page text (capped at ${TEXT_MAX_CHARACTERS} characters per result) instead of highlight excerpts. Off by default; highlights keep token usage predictable.` },
-            { kind: 'flag', name: 'include-domains', type: 'string', required: false, constraint: 'Comma-separated domain allowlist — restrict results to these domains.' },
-            { kind: 'flag', name: 'exclude-domains', type: 'string', required: false, constraint: 'Comma-separated domain blocklist — drop results from these domains.' },
-        ],
-        output: [
-            { name: 'query', type: 'string', required: true, constraint: 'Echo of the query searched.' },
-            { name: 'results', type: 'object[]', required: true, constraint: 'Ranked best-first, each: title, url, published date and author when present, and either highlight excerpts (default) or capped full text (--text).' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Decision road sign: either read selected result URLs through the contents leaf after checking its schema, or refine the query.' },
-        ],
-        outputKind: 'object',
-        effects: ['Sends one search request to the Exa API (network). No local state changes.'],
-    },
-    run: async (input) => {
-        const query = input['query'];
-        const type = input['type'];
-        const num = input['num'];
-        const wantText = input['text'];
-        const contents = wantText
-            ? { text: { maxCharacters: TEXT_MAX_CHARACTERS } }
-            : { highlights: true };
-        const body = { query, type, numResults: num, contents };
-        const include = parseDomains(input['includeDomains']);
-        const exclude = parseDomains(input['excludeDomains']);
-        if (include !== undefined)
-            body['includeDomains'] = include;
-        if (exclude !== undefined)
-            body['excludeDomains'] = exclude;
-        const res = await exaSearch(body);
-        const results = res.results ?? [];
-        return {
-            query,
-            results,
-            follow_up: 'Fetch full content for selected result URLs with the contents leaf after checking its schema. No good hits? Broaden the query, drop domain filters, or try --type deep.',
-        };
-    },
-    render: (result) => {
-        const query = result['query'];
-        const results = result['results'];
-        const followUp = result['follow_up'];
-        if (results.length === 0) {
-            return `No results for "${query}".\n\n${followUp}`;
-        }
-        const lines = [`${results.length} results for "${query}":`, ''];
-        results.forEach((r, i) => {
-            lines.push(renderResult(r, i + 1));
-            lines.push('');
-        });
-        lines.push(followUp);
-        return lines.join('\n');
-    },
-});

package/dist/commands/search.d.ts

@@ -1,2 +0,0 @@
-import type { BranchDef } from '../core/command.js';
-export declare function registerSearch(): BranchDef;

package/dist/commands/search.js

@@ -1,24 +0,0 @@
-// `crtr search` subtree — web search for agents, backed by the Exa API. Three
-// leaves: web (find pages), answer (one grounded cited answer), contents
-// (extract from URLs you already have). API key resolves from EXA_API_KEY or
-// ~/.crouter/exa.key (see ./search/exa.ts).
-import { defineBranch } from '../core/command.js';
-import { webLeaf } from './search/web.js';
-import { answerLeaf } from './search/answer.js';
-import { contentsLeaf } from './search/contents.js';
-export function registerSearch() {
-    return defineBranch({
-        name: 'search',
-        rootEntry: {
-            concept: 'web search for agents — find pages, get grounded answers, extract page content (Exa)',
-            desc: 'search the web, answer a question with citations, or extract content from known URLs',
-            useWhen: 'you need information from the live web — current events, documentation, sources, facts beyond your training. Use web for relevant pages with excerpts, answer for one synthesized cited answer, and contents for clean text from URLs you already hold. This reaches public pages read-only, not logged-in pages or service APIs. Needs an Exa API key (EXA_API_KEY or ~/.crouter/exa.key).',
-        },
-        help: {
-            name: 'search',
-            summary: 'web search via the Exa API — find pages, answer questions with citations, extract page content',
-            model: 'Three leaves split by what you have and what you want. `web` is the default: a query in, ranked pages out with query-relevant highlight excerpts (or full text with --text) — use it for discovery and research. `answer` collapses a question into one synthesized, source-cited answer — use it when you want the conclusion, not a reading list. `contents` does no searching; it extracts cleaned content from URLs you already hold. Highlights are the default content mode everywhere (token-predictable); full text is opt-in and length-capped. Every leaf needs an Exa API key from EXA_API_KEY or ~/.crouter/exa.key.',
-        },
-        children: [webLeaf, answerLeaf, contentsLeaf],
-    });
-}

package/dist/commands/sys/panels/keys-panel.d.ts

@@ -1,16 +0,0 @@
-import { type SetupPanel } from "./panel.js";
-export declare class KeysPanel implements SetupPanel {
-    private readonly input;
-    private _focused;
-    private notice;
-    onSubmit?: () => void;
-    onCancel?: () => void;
-    constructor();
-    set focused(value: boolean);
-    get focused(): boolean;
-    get value(): string;
-    setNotice(notice: string, clearValue?: boolean): void;
-    badge(): string;
-    handleInput(data: string): boolean;
-    render(width: number): string[];
-}