@mjasnikovs/pi-task 0.18.4 → 0.18.6

package/dist/task/repo-health-check.js

@@ -32,6 +32,23 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
+/** How much of a failing command's output to keep — bounded so a wedged tool that
+ *  spews megabytes cannot bloat the trail. stderr leads (a crash trace lives there). */
+const HEALTH_OUTPUT_MAX_LINES = 40;
+const HEALTH_OUTPUT_MAX_CHARS = 4000;
+/** Combine a failing command's stderr+stdout into a bounded, first-N-lines snippet. */
+export function captureHealthOutput(stdout, stderr) {
+    const combined = [stderr, stdout]
+        .map(s => (s ?? '').trim())
+        .filter(s => s.length > 0)
+        .join('\n');
+    if (combined.length === 0)
+        return '';
+    let snippet = combined.split('\n').slice(0, HEALTH_OUTPUT_MAX_LINES).join('\n');
+    if (snippet.length > HEALTH_OUTPUT_MAX_CHARS)
+        snippet = `${snippet.slice(0, HEALTH_OUTPUT_MAX_CHARS)}…`;
+    return snippet;
+}
 function packageScripts(cwd) {
     try {
         const j = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
@@ -103,7 +120,12 @@ export function discoverHealthCommands(cwd) {
 export function runRepoHealthCheck(cwd, timeoutMs = 600_000) {
     const { ecosystem, cmds } = discoverHealthCommands(cwd);
     if (!ecosystem || cmds.length === 0) {
-        return { ok: true, reason: 'no repo-wide static-analysis command found', ecosystem };
+        return {
+            ok: true,
+            reason: 'no repo-wide static-analysis command found',
+            ecosystem,
+            output: ''
+        };
     }
     for (const [bin, args] of cmds) {
         const r = spawnSync(bin, args, { cwd, encoding: 'utf8', timeout: timeoutMs });
@@ -119,9 +141,10 @@ export function runRepoHealthCheck(cwd, timeoutMs = 600_000) {
             return {
                 ok: false,
                 reason: `\`${bin} ${args.join(' ')}\` exited ${r.status}`,
-                ecosystem
+                ecosystem,
+                output: captureHealthOutput(r.stdout, r.stderr)
             };
         }
     }
-    return { ok: true, reason: `${ecosystem}: static checks passed`, ecosystem };
+    return { ok: true, reason: `${ecosystem}: static checks passed`, ecosystem, output: '' };
 }

package/dist/task/service-blocks.d.ts

@@ -1,3 +1,3 @@
-import type { BraveResult } from '../workers/brave-search.js';
-export declare function formatServiceBlock(name: string, fullQuery: string, results: BraveResult[]): string;
+import type { SearchResult } from '../workers/search-types.js';
+export declare function formatServiceBlock(name: string, fullQuery: string, results: SearchResult[]): string;
 export declare function formatFreshnessSkippedBlock(names: string[]): string;

package/dist/task/service-blocks.js

@@ -5,6 +5,8 @@ export function formatServiceBlock(name, fullQuery, results) {
     const bullets = results.map(r => `- **${r.title}** — ${r.url}\n  ${r.description}`).join('\n');
     return `${header}\n${bullets}`;
 }
+// Only the brave provider can be unconfigured (exa/ddg are keyless), so the
+// skip reason names its missing key directly.
 export function formatFreshnessSkippedBlock(names) {
-    return `### freshness-check skipped\nCould not verify external services (BRAVE_SEARCH_API_KEY not set):\n${names.map(n => `- ${n}`).join('\n')}`;
+    return `### freshness-check skipped\nCould not verify external services (search provider is brave but BRAVE_SEARCH_API_KEY is not set):\n${names.map(n => `- ${n}`).join('\n')}`;
 }

package/dist/task/task-gates.d.ts

@@ -101,6 +101,7 @@ export interface GateDeps {
     repoHealth?: (cwd: string) => Promise<{
         ok: boolean;
         reason: string;
+        output?: string;
     }>;
     /** Does the working tree hold changes (excluding .pi-tasks)? Lets the pre-commit
      *  health check run only when the enforce pass actually edited something. */
@@ -118,6 +119,29 @@ export interface GateDeps {
      * swallowed by the implementation, never by this sequence.
      */
     record?: (cwd: string, taskId: string, line: string) => Promise<void>;
+    /**
+     * Record a durable ACCEPT-despite-verify-FAIL debt (task id + FAIL reason) to the
+     * run-level ledger (`.pi-tasks/accept-debt.md`, see accept-debt.ts). Called only on
+     * the picker's ACCEPT branch — the human blessed a failing artifact as-is, so the
+     * defect is real and recorded; the final integration gate re-checks it at run end
+     * and surfaces it if still open. Best-effort; absent in tests → no ledger written.
+     */
+    recordAcceptDebt?: (cwd: string, taskId: string, reason: string) => Promise<void>;
+    /**
+     * The concrete paths this task's spec forbids modifying (its `Do NOT modify`
+     * CONSTRAINTS — see frozen-path-guard.ts / prohibition-probe.ts). Used to
+     * write-deny the enforce EDIT pass: a violating edit is reverted before it can
+     * be committed. Empty when the spec froze nothing → the guard is a no-op.
+     * Absent in tests / on a bare `/task` → the guard is skipped.
+     */
+    frozenPaths?: (cwd: string, taskId: string) => Promise<string[]>;
+    /**
+     * Restore the given frozen paths to their committed (HEAD) state, discarding a
+     * gate child's edits to them, and return the files actually reverted. Prompt
+     * framing is A/B-proven insufficient for this class, so the deny is mechanical:
+     * the write is undone, not merely warned about. Absent → the guard warns only.
+     */
+    revertFrozenPaths?: (cwd: string, paths: string[]) => Promise<string[]>;
 }
 /** Inputs the sequence needs that vary per caller. */
 export interface GateParams {

package/dist/task/task-gates.js

@@ -10,6 +10,18 @@ import { SessionUI } from '../remote/bridge.js';
  * regardless of this count (blessing an artifact as-is is a human's call).
  */
 export const MAX_AUTO_AUTOFIX = 3;
+/**
+ * Bound a captured health-check output before it is embedded in a gate-trail line.
+ * appendGateRecord flattens newlines to spaces, so the trail stays one line per
+ * entry; this just caps the volume (a wedged tool can emit megabytes). The health
+ * check already trims to its own first-N lines — this is the trail-side ceiling.
+ */
+const TRAIL_OUTPUT_MAX_CHARS = 1200;
+function clampOutput(output) {
+    return output.length > TRAIL_OUTPUT_MAX_CHARS ?
+        `${output.slice(0, TRAIL_OUTPUT_MAX_CHARS)}…`
+        : output;
+}
 /**
  * Show the boxed two-choice picker after a verify FAIL and return what the user
  * decided. The model-recommended card is placed first so the renderer tints it
@@ -135,6 +147,16 @@ export async function runGatesForTask(ctxIn, deps, p) {
             }
             if (choice.action === 'accept') {
                 await rec('resolution: user ACCEPTED the work despite verify FAIL');
+                // Durable debt: the human blessed a FAILing artifact as-is, so the
+                // defect ships and nothing else revisits it (mx5 run 4 B3 / run 8
+                // TASK_0012). Record it to the run ledger; the final integration gate
+                // re-checks it at run end and surfaces it if still open. Best-effort.
+                try {
+                    await deps.recordAcceptDebt?.(p.cwd, p.taskId, failReason);
+                }
+                catch {
+                    // recording must never break the gate sequence
+                }
                 active.ui.notify(`${p.tag}: accepted "${p.title}" despite verify FAIL (${failReason.slice(0, 120)}) — proceeding.`, 'warning');
                 break;
             }
@@ -202,13 +224,40 @@ export async function runGatesForTask(ctxIn, deps, p) {
     // with no enforce dep.
     if (deps.enforce && commit.committed) {
         const mode = verifyCleanPass ? 'edit' : 'flag';
-        active.ui.notify(mode === 'edit' ?
-            `${p.tag}: enforcing AGENTS.md/CLAUDE.md on "${p.title}"…`
-            : `${p.tag}: reviewing "${p.title}" against AGENTS.md/CLAUDE.md (no verify signal — report only)…`, 'info');
+        // BASELINE repo health, captured BEFORE the edit pass touches the tree, so the
+        // pre-commit gate below is DIFFERENTIAL: it can tell an enforce-CAUSED
+        // regression (was clean, now fails) from a repo that was ALREADY unhealthy
+        // (run-8 F8: five enforce passes were discarded on a lint that was already
+        // crashing — exit 2 — before enforce edited anything; the discard threw away
+        // good work for a fault it did not cause). Only meaningful in edit mode (flag
+        // makes no edits); the task's work is already committed so this reflects the
+        // committed state the pass is about to build on.
+        const healthBefore = mode === 'edit' && deps.repoHealth ? await deps.repoHealth(p.cwd) : undefined;
         const verdict = await deps.enforce(active, p.cwd, p.title, mode);
+        // FROZEN-PATH WRITE-DENY (mechanical, not prompt — the "MUST NOT edit"
+        // instruction is A/B-proven ~0–1/5 reliable on the weak model): the enforce
+        // EDIT pass runs read,edit and has been seen mutating a path the spec froze.
+        // Before its edits are inspected/committed below, restore any frozen path it
+        // touched to the committed task state, so the violating write cannot land in
+        // the ENFORCE GUIDELINES commit regardless of what the model intended. The
+        // task's OWN frozen-path edits (if any) are already in HEAD and are the verify
+        // prohibition-probe's job — this only undoes the gate child's edits on top.
+        // No-op when the spec froze nothing or the deps are absent (bare /task, tests).
+        if (mode === 'edit' && deps.frozenPaths && deps.revertFrozenPaths) {
+            const frozen = await deps.frozenPaths(p.cwd, p.taskId);
+            if (frozen.length > 0) {
+                const reverted = await deps.revertFrozenPaths(p.cwd, frozen);
+                if (reverted.length > 0) {
+                    await rec(`enforce: frozen-path write DENIED — reverted ${reverted.length} spec-frozen file(s) the edit pass modified: ${reverted.join(', ')}`);
+                    active.ui.notify(`${p.tag}: guideline edits on "${p.title}" touched spec-frozen path(s) (${reverted.join(', ').slice(0, 120)}) — reverted before commit.`, 'warning');
+                }
+            }
+        }
         // The child's verdict and its edits are independent facts: the pass has been
         // observed declaring "clean" while having edited files (which then get
         // committed as fixes) — record both so the trail cannot contradict itself.
+        // `editsMade` is read AFTER the frozen-path revert so a pass whose only edit
+        // was to a frozen path correctly shows a clean tree (nothing left to commit).
         const editsMade = mode === 'edit' && deps.dirty ? await deps.dirty(p.cwd) : undefined;
         await rec(`enforce(${mode}): ${verdict.ok ? `clean${verdict.reason ? ` (${verdict.reason})` : ''}` : (verdict.reason ?? 'not clean')}${editsMade ? ' — edits in tree' : ''}`);
         if (!verdict.ok) {
@@ -220,19 +269,40 @@ export async function runGatesForTask(ctxIn, deps, p) {
         // and discards the bad edits outright. Only runs when the tree is actually
         // dirty (or dirtiness is unknowable); the differential guard below still
         // catches behavioral regressions the static check cannot see.
+        //
+        // The gate is DIFFERENTIAL, not absolute (run-8 F8): discard the edits only
+        // when they REGRESSED the health signal — clean before, failing after. A repo
+        // that was already failing before enforce ran is not enforce's fault, so its
+        // edits are KEPT (and the pre-existing failure is recorded, to be caught by the
+        // final integration gate, not blamed on this pass). The failing command's
+        // output is captured into the trail so the discard is explainable — F8 was
+        // unreproducible precisely because only the exit code was recorded.
         let enforceEditsBlocked = false;
         if (mode === 'edit' && deps.repoHealth && editsMade !== false) {
-            const h = await deps.repoHealth(p.cwd);
-            if (!h.ok) {
+            const after = await deps.repoHealth(p.cwd);
+            // A regression needs a clean (or unknown) baseline turning to a fail. If
+            // healthBefore is undefined (repoHealth was absent at baseline time) treat
+            // the baseline as clean — the conservative absolute behavior.
+            const wasHealthyBefore = healthBefore?.ok ?? true;
+            const regressed = !after.ok && wasHealthyBefore;
+            if (regressed) {
                 enforceEditsBlocked = true;
+                const outputTail = after.output ? ` — output:\n${clampOutput(after.output)}` : '';
                 if (deps.discardEdits) {
                     await deps.discardEdits(p.cwd);
-                    await rec(`enforce: edits discarded pre-commit (repo health: ${h.reason})`);
+                    await rec(`enforce: edits discarded pre-commit — REGRESSED repo health (${after.reason})${outputTail}`);
                 }
                 else {
-                    await rec(`enforce: edits FAILED repo health pre-commit (${h.reason}) — no discard available, left uncommitted`);
+                    await rec(`enforce: edits REGRESSED repo health pre-commit (${after.reason}) — no discard available, left uncommitted${outputTail}`);
                 }
-                active.ui.notify(`${p.tag}: guideline edits on "${p.title}" failed repo health (${h.reason.slice(0, 120)}) — discarded before commit.`, 'warning');
+                active.ui.notify(`${p.tag}: guideline edits on "${p.title}" regressed repo health (${after.reason.slice(0, 120)}) — discarded before commit.`, 'warning');
+            }
+            else if (!after.ok) {
+                // Failing both before and after → not enforce's fault. Keep the edits;
+                // record that the repo entered the gate already unhealthy so the trail
+                // explains why a still-failing repo did NOT trigger a discard here.
+                const outputTail = after.output ? ` — output:\n${clampOutput(after.output)}` : '';
+                await rec(`enforce: repo health still failing after edits but was ALREADY failing before the pass (${after.reason}) — pre-existing, edits kept${outputTail}`);
             }
         }
         if (mode === 'edit' && !enforceEditsBlocked && editsMade === false) {

package/dist/workers/brave-search.d.ts

@@ -1,8 +1,5 @@
-export interface BraveResult {
-    title: string;
-    url: string;
-    description: string;
-}
+import type { SearchResult } from './search-types.js';
+export type BraveResult = SearchResult;
 export interface BraveSearchOpts {
     apiKey: string;
     count?: number;

package/dist/workers/brave-warning.d.ts

@@ -1,10 +1,8 @@
 /**
- * One-line startup hint shown when no Brave Search key is configured.
- *
- * pi-task's web-search worker needs BRAVE_SEARCH_API_KEY (or BRAVE_API_KEY).
- * When neither is set we surface a single, unobtrusive widget line on session
- * start so the user knows search is disabled — it never blocks work and clears
- * itself on the first interaction (any keystroke).
+ * One-line startup hint shown when Brave is the selected search provider but
+ * no key is configured (Brave is the only provider that needs one — exa and
+ * ddg are keyless, so no hint renders for them). It never blocks work and
+ * clears itself on the first interaction (any keystroke).
  */
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 export declare function registerBraveKeyWarning(pi: ExtensionAPI): void;

package/dist/workers/brave-warning.js

@@ -1,14 +1,14 @@
 /**
- * One-line startup hint shown when no Brave Search key is configured.
- *
- * pi-task's web-search worker needs BRAVE_SEARCH_API_KEY (or BRAVE_API_KEY).
- * When neither is set we surface a single, unobtrusive widget line on session
- * start so the user knows search is disabled — it never blocks work and clears
- * itself on the first interaction (any keystroke).
+ * One-line startup hint shown when Brave is the selected search provider but
+ * no key is configured (Brave is the only provider that needs one — exa and
+ * ddg are keyless, so no hint renders for them). It never blocks work and
+ * clears itself on the first interaction (any keystroke).
  */
+import { getConfig } from '../config/config.js';
 const WIDGET_KEY = 'pi-task-brave-warning';
-const WARNING = '⚠ pi-task: BRAVE_SEARCH_API_KEY not set — web search is disabled. '
-    + 'Get a free key at https://api.search.brave.com/app/keys';
+const WARNING = '⚠ pi-task: search provider is brave but BRAVE_SEARCH_API_KEY is not set — web search '
+    + 'is disabled. Get a free key at https://api.search.brave.com/app/keys or switch '
+    + 'provider in /task-config';
 /** Mirrors the lookup in search-core so the hint matches what the worker reads. */
 function hasBraveKey() {
     return Boolean(process.env.BRAVE_SEARCH_API_KEY ?? process.env.BRAVE_API_KEY);
@@ -16,8 +16,9 @@ function hasBraveKey() {
 export function registerBraveKeyWarning(pi) {
     pi.on('session_start', (_event, ctx) => {
         // Terminal-only hint: needs an interactive TUI to render and to catch the
-        // keystroke that dismisses it. Skip when a key is already present.
-        if (ctx.mode !== 'tui' || hasBraveKey())
+        // keystroke that dismisses it. Only the brave provider can be misconfigured;
+        // skip whenever another provider is selected or a key is already present.
+        if (ctx.mode !== 'tui' || getConfig().searchProvider !== 'brave' || hasBraveKey())
             return;
         let unsubscribe = null;
         const clear = () => {

package/dist/workers/ddg-search.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Web search via DuckDuckGo's HTML endpoint — no API key required.
+ *
+ * DDG has no official web-results API; html.duckduckgo.com/html serves plain
+ * HTML result pages that parse cleanly with linkedom. Result links are wrapped
+ * in a `duckduckgo.com/l/?uddg=<encoded>` redirect that we unwrap so callers
+ * get the destination URL. Ad rows redirect through duckduckgo.com itself and
+ * are dropped.
+ */
+import type { FetchLike } from './exa-search.js';
+import type { SearchResult } from './search-types.js';
+export interface DdgSearchOpts {
+    count?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    fetchImpl?: FetchLike;
+}
+export declare class DdgSearchError extends Error {
+    readonly kind: 'http' | 'network' | 'aborted' | 'rate-limit';
+    readonly status?: number | undefined;
+    constructor(message: string, kind: 'http' | 'network' | 'aborted' | 'rate-limit', status?: number | undefined);
+}
+export declare function ddgSearch(query: string, opts?: DdgSearchOpts): Promise<SearchResult[]>;
+export declare function parseDdgHtml(html: string): SearchResult[];

package/dist/workers/ddg-search.js

@@ -0,0 +1,130 @@
+/**
+ * Web search via DuckDuckGo's HTML endpoint — no API key required.
+ *
+ * DDG has no official web-results API; html.duckduckgo.com/html serves plain
+ * HTML result pages that parse cleanly with linkedom. Result links are wrapped
+ * in a `duckduckgo.com/l/?uddg=<encoded>` redirect that we unwrap so callers
+ * get the destination URL. Ad rows redirect through duckduckgo.com itself and
+ * are dropped.
+ */
+import { parseHTML } from 'linkedom';
+const DDG_ENDPOINT = 'https://html.duckduckgo.com/html/';
+const DEFAULT_COUNT = 10;
+const MAX_COUNT = 20;
+const DEFAULT_TIMEOUT_MS = 15_000;
+// DDG serves a bot-challenge page to clients without a browser-ish UA.
+const USER_AGENT = 'Mozilla/5.0 (X11; Linux x86_64; rv:127.0) Gecko/20100101 Firefox/127.0';
+export class DdgSearchError extends Error {
+    kind;
+    status;
+    constructor(message, kind, status) {
+        super(message);
+        this.kind = kind;
+        this.status = status;
+        this.name = 'DdgSearchError';
+    }
+}
+export async function ddgSearch(query, opts = {}) {
+    const count = Math.max(1, Math.min(MAX_COUNT, opts.count ?? DEFAULT_COUNT));
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const url = `${DDG_ENDPOINT}?q=${encodeURIComponent(query)}`;
+    const internalController = new AbortController();
+    let userAborted = false;
+    const timeoutHandle = setTimeout(() => internalController.abort(), timeoutMs);
+    const onUserAbort = () => {
+        userAborted = true;
+        internalController.abort();
+    };
+    if (opts.signal) {
+        if (opts.signal.aborted)
+            onUserAbort();
+        else
+            opts.signal.addEventListener('abort', onUserAbort, { once: true });
+    }
+    try {
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                method: 'GET',
+                headers: {
+                    'user-agent': USER_AGENT,
+                    accept: 'text/html'
+                },
+                signal: internalController.signal
+            });
+        }
+        catch (err) {
+            if (userAborted)
+                throw new DdgSearchError('Search aborted.', 'aborted');
+            throw new DdgSearchError(`DuckDuckGo request failed: ${describeError(err)}`, 'network');
+        }
+        if (response.status === 429 || response.status === 403) {
+            throw new DdgSearchError(`DuckDuckGo is rate-limiting this client (HTTP ${response.status}). Try again in a moment.`, 'rate-limit', response.status);
+        }
+        if (!response.ok) {
+            throw new DdgSearchError(`DuckDuckGo HTTP ${response.status} ${response.statusText}`, 'http', response.status);
+        }
+        return parseDdgHtml(await response.text()).slice(0, count);
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+        if (opts.signal)
+            opts.signal.removeEventListener('abort', onUserAbort);
+    }
+}
+export function parseDdgHtml(html) {
+    const { document } = parseHTML(html);
+    const doc = document;
+    const results = [];
+    for (const anchor of doc.querySelectorAll('a.result__a')) {
+        if (anchor.closest('.result--ad'))
+            continue;
+        const href = anchor.getAttribute('href');
+        const targetUrl = href === null ? null : unwrapDdgRedirect(href);
+        // A row whose link never leaves duckduckgo.com is an ad/module, not a hit.
+        if (targetUrl === null)
+            continue;
+        const title = collapse(anchor.textContent ?? '');
+        if (!title)
+            continue;
+        const row = anchor.closest('.result');
+        const snippet = row?.querySelector('.result__snippet')?.textContent ?? '';
+        results.push({ title, url: targetUrl, description: collapse(snippet) });
+    }
+    return results;
+}
+/**
+ * Result hrefs look like `//duckduckgo.com/l/?uddg=<encoded-destination>&rut=…`;
+ * return the decoded destination, a non-DDG href unchanged, or null for links
+ * that stay on duckduckgo.com (ad click-trackers).
+ */
+function unwrapDdgRedirect(href) {
+    let parsed;
+    try {
+        parsed = new URL(href, 'https://duckduckgo.com');
+    }
+    catch {
+        return null;
+    }
+    if (parsed.hostname.endsWith('duckduckgo.com')) {
+        const uddg = parsed.searchParams.get('uddg');
+        if (!uddg)
+            return null;
+        try {
+            return new URL(uddg).toString();
+        }
+        catch {
+            return null;
+        }
+    }
+    return parsed.toString();
+}
+function collapse(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function describeError(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}

package/dist/workers/exa-search.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Web search via Exa's public MCP endpoint — no API key required.
+ *
+ * Exa hosts https://mcp.exa.ai/mcp as an intentionally keyless entry point: a
+ * single JSON-RPC `tools/call` of `web_search_exa` returns search results with
+ * content snippets. The response is SSE-framed (`data:` lines) or plain JSON,
+ * and the result payload is one text blob of `Title:`/`URL:`/`Text:` blocks
+ * separated by `---`, which we parse back into structured results.
+ */
+import type { SearchResult } from './search-types.js';
+/** Injectable fetch — the narrow signature keeps test fakes free of Bun's extras. */
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export interface ExaSearchOpts {
+    count?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    fetchImpl?: FetchLike;
+}
+export declare class ExaSearchError extends Error {
+    readonly kind: 'http' | 'network' | 'aborted' | 'protocol';
+    readonly status?: number | undefined;
+    constructor(message: string, kind: 'http' | 'network' | 'aborted' | 'protocol', status?: number | undefined);
+}
+export declare function exaSearch(query: string, opts?: ExaSearchOpts): Promise<SearchResult[]>;

package/dist/workers/exa-search.js

@@ -0,0 +1,164 @@
+/**
+ * Web search via Exa's public MCP endpoint — no API key required.
+ *
+ * Exa hosts https://mcp.exa.ai/mcp as an intentionally keyless entry point: a
+ * single JSON-RPC `tools/call` of `web_search_exa` returns search results with
+ * content snippets. The response is SSE-framed (`data:` lines) or plain JSON,
+ * and the result payload is one text blob of `Title:`/`URL:`/`Text:` blocks
+ * separated by `---`, which we parse back into structured results.
+ */
+const EXA_MCP_ENDPOINT = 'https://mcp.exa.ai/mcp';
+const DEFAULT_COUNT = 10;
+const MAX_COUNT = 20;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_DESCRIPTION_CHARS = 400;
+export class ExaSearchError extends Error {
+    kind;
+    status;
+    constructor(message, kind, status) {
+        super(message);
+        this.kind = kind;
+        this.status = status;
+        this.name = 'ExaSearchError';
+    }
+}
+export async function exaSearch(query, opts = {}) {
+    const count = Math.max(1, Math.min(MAX_COUNT, opts.count ?? DEFAULT_COUNT));
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const internalController = new AbortController();
+    let userAborted = false;
+    const timeoutHandle = setTimeout(() => internalController.abort(), timeoutMs);
+    const onUserAbort = () => {
+        userAborted = true;
+        internalController.abort();
+    };
+    if (opts.signal) {
+        if (opts.signal.aborted)
+            onUserAbort();
+        else
+            opts.signal.addEventListener('abort', onUserAbort, { once: true });
+    }
+    try {
+        let response;
+        try {
+            response = await fetchImpl(EXA_MCP_ENDPOINT, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/json, text/event-stream'
+                },
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: 1,
+                    method: 'tools/call',
+                    params: {
+                        name: 'web_search_exa',
+                        arguments: {
+                            query,
+                            numResults: count,
+                            type: 'auto',
+                            livecrawl: 'fallback',
+                            contextMaxCharacters: 3000
+                        }
+                    }
+                }),
+                signal: internalController.signal
+            });
+        }
+        catch (err) {
+            if (userAborted)
+                throw new ExaSearchError('Search aborted.', 'aborted');
+            throw new ExaSearchError(`Exa search request failed: ${describeError(err)}`, 'network');
+        }
+        if (!response.ok) {
+            throw new ExaSearchError(`Exa search HTTP ${response.status} ${response.statusText}`, 'http', response.status);
+        }
+        const rpc = parseRpcBody(await response.text());
+        if (rpc.error) {
+            throw new ExaSearchError(`Exa MCP error${rpc.error.code !== undefined ? ` ${rpc.error.code}` : ''}: ${rpc.error.message ?? 'unknown error'}`, 'protocol');
+        }
+        const text = rpc.result?.content?.find(c => c.type === 'text' && typeof c.text === 'string' && c.text.trim().length > 0)?.text;
+        if (rpc.result?.isError) {
+            throw new ExaSearchError(text?.trim() || 'Exa MCP returned an error result.', 'protocol');
+        }
+        if (!text)
+            throw new ExaSearchError('Exa MCP returned no text content.', 'protocol');
+        return parseResultBlocks(text).slice(0, count);
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+        if (opts.signal)
+            opts.signal.removeEventListener('abort', onUserAbort);
+    }
+}
+/**
+ * The endpoint answers either as a text/event-stream (`data: {json}` lines) or
+ * as a plain JSON body; accept both and take the first frame carrying a
+ * JSON-RPC result or error.
+ */
+function parseRpcBody(body) {
+    for (const line of body.split('\n')) {
+        if (!line.startsWith('data:'))
+            continue;
+        const payload = line.slice(5).trim();
+        if (!payload)
+            continue;
+        try {
+            const candidate = JSON.parse(payload);
+            if (candidate.result || candidate.error)
+                return candidate;
+        }
+        catch {
+            /* not this frame */
+        }
+    }
+    try {
+        const candidate = JSON.parse(body);
+        if (candidate.result || candidate.error)
+            return candidate;
+    }
+    catch {
+        /* fall through */
+    }
+    throw new ExaSearchError('Exa MCP returned an unparseable response.', 'protocol');
+}
+/**
+ * Split the tool's text payload into `Title:`/`URL:` blocks. The per-result
+ * content lives after a `Text:` label (full text) or a `Highlights:` line
+ * (snippet mode); either becomes the description, whitespace-collapsed and
+ * capped so a result line stays a snippet, not a page dump.
+ */
+function parseResultBlocks(text) {
+    const blocks = text.split(/(?=^Title: )/m).filter(b => b.trim().length > 0);
+    const results = [];
+    for (const block of blocks) {
+        const title = block.match(/^Title: (.+)/m)?.[1]?.trim() ?? '';
+        const url = block.match(/^URL: (.+)/m)?.[1]?.trim() ?? '';
+        if (!url)
+            continue;
+        let content = '';
+        const textStart = block.indexOf('\nText: ');
+        if (textStart >= 0) {
+            content = block.slice(textStart + '\nText: '.length);
+        }
+        else {
+            const highlights = block.match(/\nHighlights:[ \t]*\n/);
+            if (highlights?.index !== undefined) {
+                content = block.slice(highlights.index + highlights[0].length);
+            }
+        }
+        const description = content
+            .replace(/\n---\s*$/, '')
+            .replace(/\s+/g, ' ')
+            .trim()
+            .slice(0, MAX_DESCRIPTION_CHARS);
+        results.push({ title: title || url, url, description });
+    }
+    return results;
+}
+function describeError(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}