@x-code-cli/core 0.1.3 → 0.1.4

package/dist/tools/save-knowledge.d.ts

@@ -1,7 +1,7 @@
 export declare const saveKnowledge: import("ai").Tool<{
-    category: "tech-stack" | "commands" | "conventions" | "preferences" | "context";
-    key: string;
+    category: "user" | "feedback" | "project" | "reference";
     action: "add" | "delete";
+    key: string;
     fact: string;
     scope: "project" | "global";
 }, string>;

package/dist/tools/save-knowledge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"save-knowledge.d.ts","sourceRoot":"","sources":["../../src/tools/save-knowledge.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,aAAa;;;;;;UA+BxB,CAAA"}
+{"version":3,"file":"save-knowledge.d.ts","sourceRoot":"","sources":["../../src/tools/save-knowledge.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,aAAa;;;;;;UAyDxB,CAAA"}

package/dist/tools/save-knowledge.js

@@ -1,19 +1,44 @@
-// @x-code-cli/core — saveKnowledge tool (knowledge CRUD)
+// @x-code-cli/core — saveKnowledge tool (AI-written persistent memory)
 import { tool } from 'ai';
 import { z } from 'zod';
 import { getAutoMemory } from '../knowledge/auto-memory.js';
 export const saveKnowledge = tool({
-    description: 'Save, update, or delete a project/user knowledge fact in persistent memory. Use when you discover project conventions, user preferences, or important facts worth remembering for future sessions.',
+    description: `Save or delete a persistent memory that should survive across sessions.
+
+Before calling this tool, ask yourself: **"Will a future session plausibly act better because I save this?"** If not — do NOT call the tool. No-op is the default; saving is the exception. This tool is strictly for durable, cross-session knowledge.
+
+Every memory MUST be filed under one of four categories — pick the one that describes the TYPE of knowledge, not the topic:
+
+  user       — Facts about the human user: their role, expertise, goals, long-term constraints. Example: "user is a senior Go engineer new to this frontend".
+  feedback   — Corrections or validated approaches the user has given. Save both when the user corrects you AND when they confirm a non-obvious choice worked. Include WHY so edge cases are judgeable. Example: "integration tests must hit real DB, not mocks — prior incident where mocks masked broken migration".
+  project    — Ongoing work, initiatives, deadlines, non-obvious project state that would NOT be derivable from reading code or git log. Example: "merge freeze begins 2026-03-05 for mobile release cut".
+  reference  — Pointers to external systems. Example: "pipeline bugs tracked in Linear project INGEST".
+
+Do NOT save any of these (these are the common failure modes):
+- The user's current task or request ("user asked me to build a snake game") — this is transient, not durable
+- Summaries of code you just wrote, bugs you just fixed, or findings from the current turn
+- Anything derivable from the code or git log (tech stack, package.json scripts, dependencies, directory layout) — future sessions can read the code
+- Content already in AGENTS.md / CLAUDE.md
+- Debugging solutions (the fix is in the code; the commit has the context)
+- Duplicates or near-duplicates of an existing memory — update the existing one instead
+
+Even if the user says "remember X" — if X is one-off task context (a specific request, a game they wanted), still decline. Ask yourself what is *surprising* or *durable* about it; if nothing, no-op.
+
+Scope: project = this repo only; global = applies across all repos.`,
     inputSchema: z.object({
         action: z
             .enum(['add', 'delete'])
             .describe('add = create or update (auto-replaces conflicting old fact), delete = remove outdated fact'),
         key: z
             .string()
-            .describe('A short unique identifier for this fact, e.g. "package-manager", "test-framework". Same key = same fact.'),
-        fact: z.string().describe('The fact value, e.g. "pnpm (workspace mode)", "Vitest 4"'),
-        scope: z.enum(['project', 'global']).describe('project = this repo (.x-code/), global = all repos (~/.xcode/)'),
-        category: z.enum(['tech-stack', 'commands', 'conventions', 'preferences', 'context']),
+            .describe('Short unique slug identifying this fact. Same key under same category auto-replaces. Example: "testing-db-policy", "user-role".'),
+        fact: z
+            .string()
+            .describe('The fact itself. For feedback, lead with the rule and include a one-line reason so future edge cases are judgeable.'),
+        scope: z.enum(['project', 'global']).describe('project = this repo (.x-code/), global = all repos (~/.x-code/)'),
+        category: z
+            .enum(['user', 'feedback', 'project', 'reference'])
+            .describe('user | feedback | project | reference — see tool description for when to pick each'),
     }),
     execute: ({ action, key, fact, scope, category }) => {
         try {

package/dist/tools/save-knowledge.js.map

@@ -1 +1 @@
-{"version":3,"file":"save-knowledge.js","sourceRoot":"","sources":["../../src/tools/save-knowledge.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AAEzB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAE3D,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;IAChC,WAAW,EACT,oMAAoM;IACtM,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,MAAM,EAAE,CAAC;aACN,IAAI,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;aACvB,QAAQ,CAAC,4FAA4F,CAAC;QACzG,GAAG,EAAE,CAAC;aACH,MAAM,EAAE;aACR,QAAQ,CACP,0GAA0G,CAC3G;QACH,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0DAA0D,CAAC;QACrF,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,gEAAgE,CAAC;QAC/G,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;KACtF,CAAC;IACF,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE;QAClD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAA;YACnC,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;gBACrB,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAA;gBAChF,OAAO,qBAAqB,QAAQ,KAAK,GAAG,KAAK,IAAI,EAAE,CAAA;YACzD,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;gBAC5B,OAAO,uBAAuB,QAAQ,KAAK,GAAG,EAAE,CAAA;YAClD,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAC5D,OAAO,2BAA2B,GAAG,EAAE,CAAA;QACzC,CAAC;IACH,CAAC;CACF,CAAC,CAAA"}
+{"version":3,"file":"save-knowledge.js","sourceRoot":"","sources":["../../src/tools/save-knowledge.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AAEzB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAE3D,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;IAChC,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;oEAqBqD;IAClE,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,MAAM,EAAE,CAAC;aACN,IAAI,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;aACvB,QAAQ,CAAC,4FAA4F,CAAC;QACzG,GAAG,EAAE,CAAC;aACH,MAAM,EAAE;aACR,QAAQ,CACP,iIAAiI,CAClI;QACH,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,QAAQ,CACP,qHAAqH,CACtH;QACH,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,iEAAiE,CAAC;QAChH,QAAQ,EAAE,CAAC;aACR,IAAI,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;aAClD,QAAQ,CAAC,oFAAoF,CAAC;KAClG,CAAC;IACF,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE;QAClD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAA;YACnC,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;gBACrB,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAA;gBAChF,OAAO,qBAAqB,QAAQ,KAAK,GAAG,KAAK,IAAI,EAAE,CAAA;YACzD,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;gBAC5B,OAAO,uBAAuB,QAAQ,KAAK,GAAG,EAAE,CAAA;YAClD,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAC5D,OAAO,2BAA2B,GAAG,EAAE,CAAA;QACzC,CAAC;IACH,CAAC;CACF,CAAC,CAAA"}

package/dist/tools/shell-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shell-utils.d.ts","sourceRoot":"","sources":["../../src/tools/shell-utils.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,MAAM,GAAG,KAAK,CAAA;AAErD,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,IAAI,EAAE,SAAS,CAAA;CAChB;AAED,wBAAgB,cAAc,IAAI,WAAW,CAO5C;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CA0CxD;AAkDD,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGlD"}
+{"version":3,"file":"shell-utils.d.ts","sourceRoot":"","sources":["../../src/tools/shell-utils.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,MAAM,GAAG,KAAK,CAAA;AAErD,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,IAAI,EAAE,SAAS,CAAA;CAChB;AAED,wBAAgB,cAAc,IAAI,WAAW,CAc5C;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CA0CxD;AAkDD,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGlD"}

package/dist/tools/shell-utils.js

@@ -2,6 +2,13 @@
 import os from 'node:os';
 export function getShellConfig() {
     if (os.platform() === 'win32') {
+        // Git Bash / MSYS2 / Cygwin set SHELL to a Unix-style path (e.g. /usr/bin/bash).
+        // Prefer that shell when available so the Unix tool ecosystem works as expected.
+        const shell = process.env.SHELL;
+        if (shell && /\b(bash|zsh)$/i.test(shell)) {
+            const type = shell.endsWith('zsh') ? 'zsh' : 'bash';
+            return { executable: shell, args: ['-c'], type };
+        }
         return { executable: 'powershell.exe', args: ['-NoProfile', '-Command'], type: 'powershell' };
     }
     const userShell = process.env.SHELL ?? '/bin/bash';

package/dist/tools/shell-utils.js.map

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

package/dist/tools/web-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web-fetch.d.ts","sourceRoot":"","sources":["../../src/tools/web-fetch.ts"],"names":[],"mappings":"AAkBA,eAAO,MAAM,QAAQ;;;UAkDnB,CAAA"}
+{"version":3,"file":"web-fetch.d.ts","sourceRoot":"","sources":["../../src/tools/web-fetch.ts"],"names":[],"mappings":"AAmFA,eAAO,MAAM,QAAQ;;;UAsEnB,CAAA"}

package/dist/tools/web-fetch.js

@@ -1,40 +1,111 @@
-// @x-code-cli/core — webFetch tool (HTTP fetch + HTML→Markdown)
+// @x-code-cli/core — webFetch tool (HTTP fetch + HTML→Markdown, with LRU cache + CF fallback)
 import * as cheerio from 'cheerio';
 // @ts-expect-error turndown has no types
 import TurndownService from 'turndown';
 import { tool } from 'ai';
 import { z } from 'zod';
-const FETCH_TIMEOUT_MS = 15000;
-const MAX_CONTENT_CHARS = 30000;
-// eslint-disable-next-line @typescript-eslint/no-unsafe-call
+import { reportProgress } from './progress.js';
+const FETCH_TIMEOUT_MS = 15_000;
+// Markdown returned to the model. Bumped from 30 KB (which cut docs pages in half)
+// but kept well under the model's context budget: ~100 KB ≈ ~25 K tokens, roughly
+// 12% of a Sonnet 200 K window, so a single fetch can't blow context.
+// This is a per-call cap; the model can always fetch again with a narrower prompt.
+const MAX_CONTENT_CHARS = 100_000;
+// Raw HTML ceiling before turndown. 10 MB is comfortable for any real doc page;
+// enforced via content-length header (best-effort — chunked responses skip this,
+// in which case the 15 s fetch timeout bounds the download).
+const MAX_HTTP_BYTES = 10 * 1024 * 1024;
+const CACHE_TTL_MS = 15 * 60 * 1000;
+const CACHE_MAX_ENTRIES = 50;
+const BROWSER_UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36';
+// Used as Cloudflare fallback: aggressive bot rules often let honest CLI UAs through
+// while blocking browser impersonators that fail TLS-fingerprint checks.
+const FALLBACK_UA = 'x-code-cli/0.1 (+https://github.com/woai3c/x-code-cli)';
+const YEAR = new Date().getFullYear();
+const fetchCache = new Map();
+function cacheGet(url) {
+    const entry = fetchCache.get(url);
+    if (!entry)
+        return null;
+    if (Date.now() - entry.at > CACHE_TTL_MS) {
+        fetchCache.delete(url);
+        return null;
+    }
+    // LRU: re-insert to move this entry to the tail (most-recently-used)
+    fetchCache.delete(url);
+    fetchCache.set(url, entry);
+    return entry.markdown;
+}
+function cacheSet(url, markdown) {
+    if (fetchCache.size >= CACHE_MAX_ENTRIES) {
+        const oldest = fetchCache.keys().next().value;
+        if (oldest !== undefined)
+            fetchCache.delete(oldest);
+    }
+    fetchCache.set(url, { markdown, at: Date.now() });
+}
 const turndown = new TurndownService({
     headingStyle: 'atx',
     codeBlockStyle: 'fenced',
 });
+async function doFetch(url, userAgent) {
+    return fetch(url, {
+        headers: {
+            'User-Agent': userAgent,
+            Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,text/plain;q=0.8,*/*;q=0.5',
+            'Accept-Language': 'en-US,en;q=0.9',
+        },
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+}
+function formatOutput(url, markdown, prompt) {
+    if (prompt) {
+        return `# Content from ${url}\n\n${markdown}\n\n---\nExtract instruction: ${prompt}`;
+    }
+    return markdown;
+}
 export const webFetch = tool({
-    description: 'Fetch a web page and extract its content as markdown. No API key needed.',
+    description: `Fetch a web page and extract its content as markdown. No API key needed. ` +
+        `When summarizing the returned content for the user, preserve key details, concrete examples, ` +
+        `section structure, and numbers — don't over-compress. ` +
+        `Results are cached for 15 minutes per URL, so repeated reads of the same page are free. ` +
+        `The current year is ${YEAR} — use it whenever the user asks for recent/latest/current information.`,
     inputSchema: z.object({
         url: z.string().url().describe('The URL to fetch'),
         prompt: z.string().optional().describe('What information to extract from the page'),
     }),
-    execute: async ({ url, prompt }) => {
+    execute: async ({ url, prompt }, { toolCallId }) => {
         try {
-            const response = await fetch(url, {
-                headers: {
-                    'User-Agent': 'Mozilla/5.0 (compatible; X-Code-CLI/0.1)',
-                    Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
-                },
-                signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-            });
+            const cached = cacheGet(url);
+            if (cached) {
+                reportProgress(toolCallId, 'Using cached copy');
+                return formatOutput(url, cached, prompt);
+            }
+            reportProgress(toolCallId, `Fetching ${url}`);
+            let response = await doFetch(url, BROWSER_UA);
+            // Cloudflare bot-challenge fallback: on 403 + cf-mitigated header, retry with
+            // an honest CLI UA. Many CF rules whitelist identified crawlers while blocking
+            // anything that fails the browser TLS fingerprint check.
+            if (response.status === 403 && response.headers.get('cf-mitigated') !== null) {
+                response = await doFetch(url, FALLBACK_UA);
+            }
             if (!response.ok) {
                 return `Error: HTTP ${response.status} ${response.statusText}`;
             }
+            // Best-effort size guard: content-length is optional under chunked encoding,
+            // so we also rely on fetch's 15s timeout to bound pathological pages.
+            const contentLength = Number(response.headers.get('content-length') ?? '0');
+            if (contentLength > MAX_HTTP_BYTES) {
+                const mb = Math.round(contentLength / 1024 / 1024);
+                return `Error: Content too large (${mb} MB, limit ${MAX_HTTP_BYTES / 1024 / 1024} MB)`;
+            }
             const contentType = response.headers.get('content-type') ?? '';
             const body = await response.text();
             if (contentType.includes('application/json')) {
-                return body.slice(0, MAX_CONTENT_CHARS);
+                const json = body.slice(0, MAX_CONTENT_CHARS);
+                cacheSet(url, json);
+                return formatOutput(url, json, prompt);
             }
-            // HTML → Markdown
             const $ = cheerio.load(body);
             $('script, style, nav, footer, header, aside, .sidebar, .nav, .menu, .ads, .advertisement').remove();
             const mainContent = $('main, article, .content, .post, #content').first();
@@ -45,10 +116,8 @@ export const webFetch = tool({
             if (markdown.length > MAX_CONTENT_CHARS) {
                 markdown = markdown.slice(0, MAX_CONTENT_CHARS) + '\n\n... [content truncated]';
             }
-            if (prompt) {
-                return `# Content from ${url}\n\n${markdown}\n\n---\nExtract instruction: ${prompt}`;
-            }
-            return markdown;
+            cacheSet(url, markdown);
+            return formatOutput(url, markdown, prompt);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);

package/dist/tools/web-fetch.js.map

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

package/dist/tools/web-search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web-search.d.ts","sourceRoot":"","sources":["../../src/tools/web-search.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,SAAS;;;UAwBpB,CAAA"}
+{"version":3,"file":"web-search.d.ts","sourceRoot":"","sources":["../../src/tools/web-search.ts"],"names":[],"mappings":"AA6FA,eAAO,MAAM,SAAS;;;UAyBpB,CAAA"}

package/dist/tools/web-search.js

@@ -1,26 +1,99 @@
-// @x-code-cli/core — webSearch tool (Tavily API)
+// @x-code-cli/core — webSearch tool (Tavily primary, Brave fallback)
 import { tool } from 'ai';
 import { z } from 'zod';
+import { reportProgress } from './progress.js';
+import { getShellConfig } from './shell-utils.js';
+const YEAR = new Date().getFullYear();
+const BRAVE_TIMEOUT_MS = 15_000;
+async function searchWithTavily(query, maxResults) {
+    const { tavily } = await import('@tavily/core');
+    const client = tavily({ apiKey: process.env.TAVILY_API_KEY });
+    const response = await client.search(query, { maxResults });
+    return response.results.map((r) => ({ title: r.title, url: r.url, content: r.content }));
+}
+async function searchWithBrave(query, maxResults) {
+    const url = new URL('https://api.search.brave.com/res/v1/web/search');
+    url.searchParams.set('q', query);
+    url.searchParams.set('count', String(Math.min(maxResults, 20)));
+    const res = await fetch(url, {
+        headers: {
+            'X-Subscription-Token': process.env.BRAVE_API_KEY,
+            Accept: 'application/json',
+        },
+        signal: AbortSignal.timeout(BRAVE_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+        throw new Error(`Brave API returned HTTP ${res.status} ${res.statusText}`);
+    }
+    const data = (await res.json());
+    return (data.web?.results ?? []).map((r) => ({ title: r.title, url: r.url, content: r.description }));
+}
+function buildMissingKeyError() {
+    const { type } = getShellConfig();
+    let setupBlock;
+    if (type === 'powershell') {
+        setupBlock = [
+            '  # current session:',
+            '  $env:TAVILY_API_KEY = "tvly-xxx"',
+            '  $env:BRAVE_API_KEY  = "BSA-xxx"',
+            '  # persistent (new shells):',
+            '  [Environment]::SetEnvironmentVariable("TAVILY_API_KEY","tvly-xxx","User")',
+            '  [Environment]::SetEnvironmentVariable("BRAVE_API_KEY", "BSA-xxx", "User")',
+        ].join('\n');
+    }
+    else {
+        const rc = type === 'zsh' ? '~/.zshrc' : '~/.bashrc';
+        setupBlock = [
+            '  # current session:',
+            '  export TAVILY_API_KEY="tvly-xxx"',
+            '  export BRAVE_API_KEY="BSA-xxx"',
+            '  # persistent (new shells):',
+            `  echo 'export TAVILY_API_KEY="tvly-xxx"' >> ${rc}`,
+            `  echo 'export BRAVE_API_KEY="BSA-xxx"' >> ${rc}`,
+        ].join('\n');
+    }
+    return [
+        'Error: WebSearch requires an API key. Two free options (set either one):',
+        '',
+        '  1. Tavily — 1000 searches/month, recommended',
+        '     Sign up: https://tavily.com → copy API key from dashboard',
+        '',
+        '  2. Brave  — 2000 searches/month (requires credit card, no charge)',
+        '     Sign up: https://api.search.brave.com → create API key',
+        '',
+        `Setup (${type}):`,
+        setupBlock,
+        '',
+        'After setting, restart this shell for the variable to take effect.',
+    ].join('\n');
+}
+function formatResults(results) {
+    if (results.length === 0)
+        return 'No results found.';
+    return results.map((r) => `### ${r.title}\n${r.url}\n${r.content}`).join('\n\n');
+}
 export const webSearch = tool({
-    description: 'Search the web for information. Useful for looking up documentation, error messages, or current information.',
+    description: `Search the web for information. Useful for looking up documentation, error messages, or current information. ` +
+        `The current year is ${YEAR} — use it whenever the user asks for recent/latest/current information ` +
+        `(e.g. prefer "React 19 release notes ${YEAR}" over "React latest release notes").`,
     inputSchema: z.object({
         query: z.string().describe('The search query'),
         maxResults: z.number().optional().describe('Max results (default: 5)'),
     }),
-    execute: async ({ query, maxResults }) => {
-        if (!process.env.TAVILY_API_KEY) {
-            return 'Error: TAVILY_API_KEY is not configured. Get a free API key (1000 searches/month) at https://tavily.com';
-        }
+    execute: async ({ query, maxResults }, { toolCallId }) => {
+        const n = maxResults ?? 5;
+        const hasTavily = !!process.env.TAVILY_API_KEY;
+        const hasBrave = !!process.env.BRAVE_API_KEY;
+        if (!hasTavily && !hasBrave)
+            return buildMissingKeyError();
+        reportProgress(toolCallId, `Searching: ${query}`);
         try {
-            const { tavily } = await import('@tavily/core');
-            const client = tavily({ apiKey: process.env.TAVILY_API_KEY });
-            const response = await client.search(query, { maxResults: maxResults ?? 5 });
-            const results = response.results.map((r) => `### ${r.title}\n${r.url}\n${r.content}`);
-            return results.join('\n\n') || 'No results found.';
+            const results = hasTavily ? await searchWithTavily(query, n) : await searchWithBrave(query, n);
+            return formatResults(results);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            return `Error searching: ${msg}`;
+            return `Error searching (${hasTavily ? 'Tavily' : 'Brave'}): ${msg}`;
         }
     },
 });

package/dist/tools/web-search.js.map

@@ -1 +1 @@
-{"version":3,"file":"web-search.js","sourceRoot":"","sources":["../../src/tools/web-search.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AAEzB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC;IAC5B,WAAW,EACT,8GAA8G;IAChH,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;QAC9C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;KACvE,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE;QACvC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC;YAChC,OAAO,yGAAyG,CAAA;QAClH,CAAC;QACD,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAA;YAC/C,MAAM,MAAM,GAAG,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,CAAA;YAC7D,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,UAAU,EAAE,UAAU,IAAI,CAAC,EAAE,CAAC,CAAA;YAC5E,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAClC,CAAC,CAAkD,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,EAAE,CACjG,CAAA;YACD,OAAO,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,mBAAmB,CAAA;QACpD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAC5D,OAAO,oBAAoB,GAAG,EAAE,CAAA;QAClC,CAAC;IACH,CAAC;CACF,CAAC,CAAA"}
+{"version":3,"file":"web-search.js","sourceRoot":"","sources":["../../src/tools/web-search.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -4,8 +4,6 @@ export interface TokenUsage {
     inputTokens: number;
     outputTokens: number;
     totalTokens: number;
-    estimatedCost: number;
-    costCurrency: 'USD' | 'CNY';
 }
 export interface DisplayMessage {
     id: string;
@@ -13,19 +11,45 @@ export interface DisplayMessage {
     content: string;
     toolCalls?: DisplayToolCall[];
     timestamp: number;
+    /** True for assistant text chunks emitted mid-stream (one per newline).
+     *  Rendered WITHOUT the trailing blank line that regular messages append,
+     *  so consecutive chunks join into a single paragraph visually. Keeps
+     *  streaming text out of the bottom cell buffer (avoids row-shift jitter)
+     *  by sending each complete line directly to scrollback. */
+    streamingChunk?: boolean;
+    /** Compact slash-command rendering, matching Claude Code's 2-line block:
+     *    > /model
+     *      ⎿  Set model to Sonnet 4.6
+     *  'command-echo' (user role) drops the trailing blank that regular user
+     *  messages append; 'command-result' (assistant role) renders with the
+     *  ⎿ prefix and a single trailing newline instead of markdown + \n\n.
+     *  Used only for short, single-line command responses. Long multi-line
+     *  output (/help, /usage) keeps the regular assistant-message path. */
+    kind?: 'command-echo' | 'command-result';
 }
 export interface DisplayToolCall {
     id: string;
     toolName: string;
     input: Record<string, unknown>;
     output?: string;
-    status: 'pending' | 'running' | 'completed' | 'denied';
+    /** `error` marks a tool that finished but with a non-zero exit / thrown
+     *  exception — the stdout-writer renders its result body in red so
+     *  failures stand out in scrollback. `denied` is reserved for the
+     *  permission-denial path. */
+    status: 'pending' | 'running' | 'completed' | 'denied' | 'error';
+    /** How long the tool call took to execute (milliseconds) */
+    durationMs?: number;
 }
 export interface AgentCallbacks {
     onTextDelta: (text: string) => void;
-    onToolCall: (toolName: string, input: Record<string, unknown>) => void;
-    onToolResult: (toolCallId: string, result: string) => void;
+    onToolCall: (toolCallId: string, toolName: string, input: Record<string, unknown>) => void;
+    /** Streamed progress messages emitted by a tool while it runs (e.g.
+     *  "Searching: query" → "Found 5 results"). Only the LATEST message is
+     *  shown in the live UI; the final summary comes through onToolResult. */
+    onToolProgress: (toolCallId: string, message: string) => void;
+    onToolResult: (toolCallId: string, result: string, isError?: boolean) => void;
     onAskPermission: (toolCall: {
+        toolCallId: string;
         toolName: string;
         input: Record<string, unknown>;
     }) => Promise<boolean>;
@@ -46,13 +70,22 @@ export interface AgentOptions {
     systemPromptExtra?: string;
     abortSignal?: AbortSignal;
 }
-export interface AppConfig {
-    model?: string;
-}
+/**
+ * Category taxonomy for auto memory entries. Categories describe the TYPE of
+ * knowledge (who it's about, how it was learned) rather than the topic —
+ * this mirrors the taxonomy Claude Code uses and produces sharper memories
+ * because each category has distinct trigger conditions for the agent.
+ *
+ * - user:      Facts about the human user — role, expertise, goals, constraints
+ * - feedback:  Corrections or validated approaches ("don't mock the db", "yes, that was right")
+ * - project:   Ongoing work, initiatives, decisions, non-obvious project state
+ * - reference: Pointers to external systems (Linear project, Grafana dashboard, etc.)
+ */
+export type KnowledgeCategory = 'user' | 'feedback' | 'project' | 'reference';
 export interface KnowledgeFact {
     key: string;
     fact: string;
-    category: 'tech-stack' | 'commands' | 'conventions' | 'preferences' | 'context';
+    category: KnowledgeCategory;
     date: string;
 }
 export interface SessionSummary {
@@ -67,26 +100,16 @@ export interface SessionSummary {
     filesModified: string[];
     decisions: string[];
 }
-export interface RuleFrontmatter {
-    alwaysApply?: boolean;
-    paths?: string[];
-    description?: string;
-}
-export interface RuleFile {
-    filename: string;
-    frontmatter: RuleFrontmatter;
-    content: string;
-}
 export declare const MODEL_ALIASES: Record<string, string>;
 export declare const PROVIDER_DETECTION_ORDER: readonly [{
     readonly envKey: "ANTHROPIC_API_KEY";
-    readonly defaultModel: "anthropic:claude-sonnet-4-5";
+    readonly defaultModel: "anthropic:claude-sonnet-4-6";
 }, {
     readonly envKey: "OPENAI_API_KEY";
     readonly defaultModel: "openai:gpt-4.1";
 }, {
     readonly envKey: "DEEPSEEK_API_KEY";
-    readonly defaultModel: "deepseek:deepseek-chat";
+    readonly defaultModel: "deepseek:deepseek-v4-flash";
 }, {
     readonly envKey: "ALIBABA_API_KEY";
     readonly defaultModel: "alibaba:qwen-max";
@@ -103,6 +126,22 @@ export declare const PROVIDER_DETECTION_ORDER: readonly [{
     readonly envKey: "MOONSHOT_API_KEY";
     readonly defaultModel: "moonshotai:kimi-k2.5";
 }];
+export interface ProviderModel {
+    /** Full `<provider>:<model>` id passed to AI SDK */
+    id: string;
+    /** Short display label shown in the picker */
+    label: string;
+    /** One-line description shown under the label */
+    description: string;
+}
+/**
+ * Hand-curated models per provider. Only models we've tested or that are
+ * advertised as production-stable make the list — agents tend to pick
+ * whatever is visible, so we don't dump every experimental variant here.
+ * Users who need something exotic can still type the full id into
+ * `/model <provider>:<model>` or pass it via `--model`.
+ */
+export declare const PROVIDER_MODELS: Record<string, readonly ProviderModel[]>;
 export declare const PROVIDER_KEY_URLS: Record<string, string>;
 export type { ModelMessage, LanguageModel };
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

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