fixo-cli 1.0.0

package/dist/agent/search/index.d.ts

@@ -0,0 +1,61 @@
+export interface SearchResult {
+    readonly title: string;
+    readonly url: string;
+    readonly snippet: string;
+    readonly score?: number;
+}
+export interface SearchOptions {
+    readonly maxResults?: number;
+    readonly signal?: AbortSignal;
+}
+export interface SearchProvider {
+    readonly id: 'brave' | 'tavily' | 'ddg';
+    /**
+     * True if the provider can run right now (key configured, not
+     * currently rate-limited). The chain uses this to skip a
+     * provider without paying the cost of an HTTP round-trip.
+     */
+    isAvailable(): Promise<boolean>;
+    search(query: string, opts?: SearchOptions): Promise<SearchResult[]>;
+}
+export declare class SearchExhaustedError extends Error {
+    readonly query: string;
+    readonly attempts: ReadonlyArray<{
+        provider: string;
+        error: string;
+    }>;
+    constructor(query: string, attempts: ReadonlyArray<{
+        provider: string;
+        error: string;
+    }>);
+}
+/**
+ * Default provider chain: Brave → Tavily → DDG fallback. The
+ * order is hard-coded; if you need a different order, construct
+ * a custom {@link SearchProviderChain} via the named-arg form.
+ */
+export declare class SearchProviderChain {
+    private readonly providers;
+    private readonly onProviderTried?;
+    constructor(providers?: SearchProvider[], hooks?: {
+        onProviderTried?: (provider: string, results: number, durationMs: number) => void;
+    });
+    search(query: string, opts?: SearchOptions): Promise<{
+        results: SearchResult[];
+        provider: SearchProvider['id'] | null;
+        attempts: Array<{
+            provider: string;
+            error: string;
+        }>;
+    }>;
+}
+export declare function getDefaultSearchChain(): SearchProviderChain;
+/** Test hook — drop the cached chain. */
+export declare function resetDefaultSearchChain(): void;
+/**
+ * High-level "search the web" entry point. Backwards-compatible
+ * with the legacy `webSearch(query)` signature so existing tool
+ * dispatch and tests keep working.
+ */
+export declare function webSearch(query: string): Promise<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/search/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agent/search/index.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;IACxC;;;;OAIG;IACH,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CACtE;AAID,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,QAAQ,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;gBAE3E,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAU/D;AAmOD;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAkE;gBAGjG,SAAS,CAAC,EAAE,cAAc,EAAE,EAC5B,KAAK,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE;IAOlF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC;QACpE,OAAO,EAAE,YAAY,EAAE,CAAC;QACxB,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACtC,QAAQ,EAAE,KAAK,CAAC;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACtD,CAAC;CA4BH;AAID,wBAAgB,qBAAqB,IAAI,mBAAmB,CAG3D;AAED,yCAAyC;AACzC,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAkBD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAU9D"}

package/dist/agent/search/index.js

@@ -0,0 +1,314 @@
+/**
+ * Reliable web search — provider chain.
+ *
+ * The original `src/agent/web.ts` (Phase 0) reached DuckDuckGo
+ * directly via HTML scraping. The DDG endpoint is rate-limited,
+ * geo-fenced, and silently changes its DOM. Phase 2 replaces
+ * it with a typed provider chain that prefers first-party
+ * search APIs (Brave, then Tavily) and falls back to DDG
+ * only when no API key is configured. The chain records
+ * per-provider quality scores so the cooldown manager can
+ * prefer whichever provider is currently responding fastest.
+ *
+ * Pillar 4 (credential vault) is preserved by reading every
+ * API key through {@link getProviderKeyVault}.withApiKey so
+ * the key never escapes the callback scope and never
+ * appears in tool results, telemetry, or error messages.
+ */
+import { withRetry, defaultIsRetryable } from '../retry.js';
+import { getProviderKeyVault, ProviderNotInVaultError } from '../../runtime/credential-vault.js';
+import { recordProviderError, recordProviderQuality, } from '../provider-cooldown.js';
+import * as cheerio from 'cheerio';
+/* ──────────────────────── Errors ──────────────────────── */
+export class SearchExhaustedError extends Error {
+    query;
+    attempts;
+    constructor(query, attempts) {
+        super(`All search providers failed for query "${query}". ` +
+            `Tried: ${attempts.map((a) => a.provider).join(' → ')}.`);
+        this.name = 'SearchExhaustedError';
+        this.query = query;
+        this.attempts = attempts;
+    }
+}
+/* ──────────────────────── Brave ──────────────────────── */
+const BRAVE_PROVIDER_NAME = 'search.brave';
+const BRAVE_ENDPOINT = 'https://api.search.brave.com/res/v1/web/search';
+const BRAVE_KEY_NOT_CONFIGURED = '__not_configured__';
+class BraveProvider {
+    id = 'brave';
+    async isAvailable() {
+        try {
+            return await getProviderKeyVault().hasProvider(BRAVE_PROVIDER_NAME);
+        }
+        catch {
+            return false;
+        }
+    }
+    async search(query, opts = {}) {
+        const maxResults = opts.maxResults ?? 10;
+        const t0 = Date.now();
+        return await withRetry(async (signal) => {
+            const headers = await getProviderKeyVault().buildAuthHeaders(BRAVE_PROVIDER_NAME, (cred) => ({
+                'X-Subscription-Token': cred.apiKey,
+                'Accept': 'application/json',
+                'User-Agent': 'FixO-CLI/2.0 (search)',
+            }));
+            const url = new URL(BRAVE_ENDPOINT);
+            url.searchParams.set('q', query);
+            url.searchParams.set('count', String(Math.min(maxResults, 20)));
+            const response = await fetch(url.toString(), {
+                method: 'GET',
+                headers,
+                signal,
+            });
+            if (!response.ok) {
+                const status = response.status;
+                recordProviderError('brave', status, `HTTP ${status} ${response.statusText}`);
+                if (status === 401 || status === 403) {
+                    throw new ProviderNotInVaultError(BRAVE_PROVIDER_NAME);
+                }
+                throw new Error(`Brave HTTP ${status}`);
+            }
+            const json = (await response.json());
+            const results = (json.web?.results ?? [])
+                .filter((r) => r.title && r.url)
+                .slice(0, maxResults)
+                .map((r) => ({
+                title: r.title ?? '',
+                url: r.url ?? '',
+                snippet: r.description ?? '',
+            }));
+            recordProviderQuality('brave', Date.now() - t0, results.length);
+            return results;
+        }, {
+            maxAttempts: 2,
+            baseDelayMs: 500,
+            maxDelayMs: 4_000,
+            jitter: 'full',
+            isRetryable: (err) => {
+                if (err instanceof ProviderNotInVaultError)
+                    return false;
+                return defaultIsRetryable(err);
+            },
+        }, opts.signal);
+    }
+}
+/* ──────────────────────── Tavily ──────────────────────── */
+const TAVILY_PROVIDER_NAME = 'search.tavily';
+const TAVILY_ENDPOINT = 'https://api.tavily.com/search';
+class TavilyProvider {
+    id = 'tavily';
+    async isAvailable() {
+        try {
+            return await getProviderKeyVault().hasProvider(TAVILY_PROVIDER_NAME);
+        }
+        catch {
+            return false;
+        }
+    }
+    async search(query, opts = {}) {
+        const maxResults = opts.maxResults ?? 10;
+        const t0 = Date.now();
+        return await withRetry(async (signal) => {
+            const apiKey = await getProviderKeyVault().withApiKey(TAVILY_PROVIDER_NAME, async (key) => key);
+            const response = await fetch(TAVILY_ENDPOINT, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'User-Agent': 'FixO-CLI/2.0 (search)',
+                },
+                body: JSON.stringify({
+                    api_key: apiKey,
+                    query,
+                    max_results: Math.min(maxResults, 20),
+                    include_answer: false,
+                    search_depth: 'basic',
+                }),
+                signal,
+            });
+            if (!response.ok) {
+                const status = response.status;
+                recordProviderError('tavily', status, `HTTP ${status} ${response.statusText}`);
+                if (status === 401 || status === 403) {
+                    throw new ProviderNotInVaultError(TAVILY_PROVIDER_NAME);
+                }
+                throw new Error(`Tavily HTTP ${status}`);
+            }
+            const json = (await response.json());
+            const results = (json.results ?? [])
+                .filter((r) => r.title && r.url)
+                .slice(0, maxResults)
+                .map((r) => ({
+                title: r.title ?? '',
+                url: r.url ?? '',
+                snippet: r.content ?? '',
+                score: r.score,
+            }));
+            recordProviderQuality('tavily', Date.now() - t0, results.length);
+            return results;
+        }, {
+            maxAttempts: 2,
+            baseDelayMs: 500,
+            maxDelayMs: 4_000,
+            jitter: 'full',
+            isRetryable: (err) => {
+                if (err instanceof ProviderNotInVaultError)
+                    return false;
+                return defaultIsRetryable(err);
+            },
+        }, opts.signal);
+    }
+}
+/* ──────────────────────── DDG fallback ──────────────────────── */
+/**
+ * Original DDG HTML scraping path, refactored to implement
+ * {@link SearchProvider} so it can sit in the chain. Returns
+ * an empty result (not an error) when the page structure
+ * changes — a structural-change error is logged via
+ * `recordProviderError` and the chain moves to the next
+ * provider.
+ */
+class DdgProvider {
+    id = 'ddg';
+    async isAvailable() {
+        return true; // always available, no key required
+    }
+    async search(query, opts = {}) {
+        const maxResults = opts.maxResults ?? 10;
+        const t0 = Date.now();
+        const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+                    '(KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36',
+                Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+            },
+            signal: opts.signal,
+        });
+        if (!response.ok) {
+            const status = response.status;
+            recordProviderError('ddg', status, `HTTP ${status} ${response.statusText}`);
+            throw new Error(`DDG HTTP ${status}`);
+        }
+        const html = await response.text();
+        const $ = cheerio.load(html);
+        const results = [];
+        $('.result').each((_i, elem) => {
+            if (results.length >= maxResults)
+                return false;
+            const titleElem = $(elem).find('.result__title a');
+            const snippetElem = $(elem).find('.result__snippet');
+            if (titleElem.length === 0)
+                return;
+            let rawUrl = titleElem.attr('href') ?? '';
+            if (rawUrl.startsWith('//duckduckgo.com/l/?')) {
+                const m = rawUrl.match(/uddg=([^&]+)/);
+                if (m && m[1]) {
+                    try {
+                        rawUrl = decodeURIComponent(m[1]);
+                    }
+                    catch {
+                        rawUrl = '';
+                    }
+                }
+            }
+            if (!rawUrl)
+                return;
+            results.push({
+                title: titleElem.text().trim(),
+                url: rawUrl,
+                snippet: snippetElem.text().trim(),
+            });
+        });
+        recordProviderQuality('ddg', Date.now() - t0, results.length);
+        return results;
+    }
+}
+/* ──────────────────────── Chain ──────────────────────── */
+/**
+ * Default provider chain: Brave → Tavily → DDG fallback. The
+ * order is hard-coded; if you need a different order, construct
+ * a custom {@link SearchProviderChain} via the named-arg form.
+ */
+export class SearchProviderChain {
+    providers;
+    onProviderTried;
+    constructor(providers, hooks) {
+        this.providers =
+            providers ?? [new BraveProvider(), new TavilyProvider(), new DdgProvider()];
+        this.onProviderTried = hooks?.onProviderTried;
+    }
+    async search(query, opts = {}) {
+        const attempts = [];
+        for (const provider of this.providers) {
+            const available = await provider.isAvailable();
+            if (!available) {
+                attempts.push({ provider: provider.id, error: 'not_configured' });
+                continue;
+            }
+            const t0 = Date.now();
+            try {
+                const results = await provider.search(query, opts);
+                const duration = Date.now() - t0;
+                this.onProviderTried?.(provider.id, results.length, duration);
+                if (results.length > 0) {
+                    return { results, provider: provider.id, attempts };
+                }
+                attempts.push({ provider: provider.id, error: 'no_results' });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                attempts.push({ provider: provider.id, error: msg });
+                // Auth errors short-circuit — no point trying the next
+                // provider with a key the user hasn't configured.
+                if (err instanceof ProviderNotInVaultError)
+                    continue;
+                // Otherwise keep trying the next provider.
+            }
+        }
+        throw new SearchExhaustedError(query, attempts);
+    }
+}
+let cachedChain = null;
+export function getDefaultSearchChain() {
+    if (!cachedChain)
+        cachedChain = new SearchProviderChain();
+    return cachedChain;
+}
+/** Test hook — drop the cached chain. */
+export function resetDefaultSearchChain() {
+    cachedChain = null;
+}
+/* ──────────────────────── Markdown formatter (legacy surface) ───── */
+function formatAsMarkdown(results, providerId) {
+    if (results.length === 0) {
+        return 'No results found.';
+    }
+    const header = providerId ? `_via ${providerId}_\n\n` : '';
+    const body = results
+        .map((r) => `### [${r.title}](${r.url})\n${r.snippet}\n`)
+        .join('\n');
+    return header + body;
+}
+/**
+ * High-level "search the web" entry point. Backwards-compatible
+ * with the legacy `webSearch(query)` signature so existing tool
+ * dispatch and tests keep working.
+ */
+export async function webSearch(query) {
+    try {
+        const { results, provider } = await getDefaultSearchChain().search(query);
+        return formatAsMarkdown(results, provider);
+    }
+    catch (err) {
+        if (err instanceof SearchExhaustedError) {
+            return `No results found. Tried: ${err.attempts.map((a) => a.provider).join(', ')}.`;
+        }
+        return `Error performing web search: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+// Suppress unused-warning for the constant we keep around for symmetry.
+void BRAVE_KEY_NOT_CONFIGURED;
+//# sourceMappingURL=index.js.map

package/dist/agent/search/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/search/index.ts"],"names":[],"mappings":"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"}

package/dist/agent/single-agent.d.ts

@@ -0,0 +1,76 @@
+import { AgentClient } from './agent-client.js';
+import { ConversationManager } from './conversation.js';
+import type { AgentContext, AgentResult } from '../types.js';
+import * as p from '@clack/prompts';
+export declare const promptsWrapper: {
+    select: <Value>(opts: p.SelectOptions<Value>) => Promise<symbol | Value>;
+    confirm: (opts: p.ConfirmOptions) => Promise<boolean | symbol>;
+    spinner: () => {
+        start: (msg?: string) => void;
+        stop: (msg?: string, code?: number) => void;
+        message: (msg?: string) => void;
+    };
+    isCancel: typeof p.isCancel;
+};
+import type readline from 'readline';
+export declare function evaluateInputIntent(task: string): 'CHAT_ONLY' | 'MUTATION';
+export declare class SingleAgent {
+    private client;
+    private verbose;
+    private allowAll;
+    constructor(verbose?: boolean);
+    /** Expose the underlying client for direct API calls (e.g. compaction). */
+    getClient(): AgentClient;
+    runStreaming(context: AgentContext, conversation: ConversationManager, rl?: readline.Interface): Promise<AgentResult>;
+    /**
+     * Ask the user for permission to execute a tool.
+     * Prompts for every state-mutating tool: write_file,
+     * run_command, apply_patch, replace_range, insert_after,
+     * rename_file, delete_file, create_branch, commit_changes,
+     * push_branch, create_pull_request. Read-only tools (read_file,
+     * search_code, list_dir, extract_symbols, extract_imports)
+     * are auto-allowed.
+     */
+    private askPermission;
+    /**
+     * Stream a text-only response to the terminal.
+     *
+     * Selects the resumable streaming path when `preferences.resilience.
+     * streamResume === 'auto'` (the default). Set it to `'never'` to
+     * fall back to the legacy non-resumable path — useful for tests
+     * that want to observe raw stream cuts.
+     */
+    private streamResponse;
+    private executePureChatStream;
+    /**
+     * Auto-compact the conversation if the next request would approach the context limit.
+     * This is the core of the auto-context-management system.
+     */
+    private autoCompactIfNeeded;
+    /**
+     * Pillar 4 — proactive context-budget enforcement.
+     *
+     * Runs the {@link ContextBudgetEnforcer} against the conversation
+     * history right before the LLM call. Honours the kill-switch in
+     * `preferences.resilience.contextBudget`:
+     *
+     *   - `never`    — no-op, returns immediately.
+     *   - `truncate` — runs the enforcer; if it asks for compaction,
+     *                  we skip the LLM call (the next request will
+     *                  likely 413) and let the caller see a smaller
+     *                  prompt.
+     *   - `auto`     — runs the enforcer; if it asks for compaction,
+     *                  we additionally call `ConversationManager.compact`
+     *                  to summarise the oldest turns via the LLM.
+     *
+     * Returns a short report so callers can log what happened.
+     */
+    enforceContextBudget(conversation: ConversationManager, systemPrompt: string, userMessage: string, model: string): Promise<{
+        trimmed: boolean;
+        compacted: boolean;
+        tokensAfter: number;
+    }>;
+    /** Proxy health check passthrough. */
+    ping(): Promise<boolean>;
+}
+//# sourceMappingURL=single-agent.d.ts.map

package/dist/agent/single-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-agent.d.ts","sourceRoot":"","sources":["../../src/agent/single-agent.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,WAAW,EAAqC,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAIxD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAmB7D,OAAO,KAAK,CAAC,MAAM,gBAAgB,CAAC;AACpC,eAAO,MAAM,cAAc;;;;mBAqDb,CAAC;kBAAiC,CAAC,cAAe,CAAA;qBAC5D,CAAJ;;;CAjDC,CAAC;AACF,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AA2BrC,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,CAiC1E;AAkJD,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,UAAQ;IAM3B,2EAA2E;IAC3E,SAAS,IAAI,WAAW;IAIlB,YAAY,CAChB,OAAO,EAAE,YAAY,EACrB,YAAY,EAAE,mBAAmB,EACjC,EAAE,CAAC,EAAE,QAAQ,CAAC,SAAS,GACtB,OAAO,CAAC,WAAW,CAAC;IAsYvB;;;;;;;;OAQG;YACW,aAAa;IAuD3B;;;;;;;OAOG;YACW,cAAc;YA0Cd,qBAAqB;IAqCnC;;;OAGG;YACW,mBAAmB;IA2BjC;;;;;;;;;;;;;;;;;OAiBG;IACG,oBAAoB,CACxB,YAAY,EAAE,mBAAmB,EACjC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAyCzE,sCAAsC;IAChC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;CAG/B"}