mind-palace-graph 0.3.0

package/dist/api.js

@@ -0,0 +1,660 @@
+/**
+ * Programmatic API for mpg.
+ *
+ * This is the surface an LLM harness should embed against instead of
+ * shelling out to the CLI. It exposes the same operations the CLI
+ * does, but as async functions returning structured data.
+ *
+ * The CLI is a thin wrapper over this module. Conversely, this module
+ * is what powers `mpg search`, `mpg stash`, etc. for in-process use.
+ */
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { applyTotalBudget, applyWindowCurve, buildNode, loadSourceContent } from "./nodes.js";
+import { buildFuzzyRegex, verifyFuzzy } from "./fuzzy.js";
+import { RgError, runRg } from "./rg.js";
+import { captureCommand, captureStdin, captureUrl, classifyPathSpecs, } from "./sources.js";
+import { addStash as addStashToPalace, composeToSources, defaultPalacePath, dropStash as dropStashFromPalace, getStash as getStashFromPalace, listStashes as listStashesFromPalace, loadPalace, savePalace, } from "./mind-palace.js";
+// ─── Search ─────────────────────────────────────────────────────────
+const EFFORT_DEFAULTS = {
+    // "scan" — index mode. Many nodes with tiny disambiguating windows
+    // (~20 tokens on each side of the match). Purpose: see all hits at
+    // once, then pick which file/page to dig into with quick/normal/deep.
+    // This is the "index -> detail" pattern: scan first to find what's
+    // relevant; targeted small queries follow up on the chosen file(s).
+    // Tokens scale O(n) with hit count (~60 tok/match on average);
+    // maxNodes is intentionally high so scan matches rg's recall AND
+    // precision regardless of hit count. Use --max-tokens if you want
+    // to cap by budget instead.
+    scan: { before: 20, after: 20, maxNodes: 100000 },
+    quick: { before: 200, after: 200, maxNodes: 10 },
+    normal: { before: 500, after: 500, maxNodes: 30 },
+    deep: { before: 2000, after: 2000, maxNodes: 100 },
+    auto: { before: 500, after: 500, maxNodes: 30 },
+};
+/**
+ * Threshold above which auto-tune treats the corpus as "wide-record"
+ * (JSONL events, log lines with embedded JSON, etc) and drops
+ * before/after padding. Chosen so that typical source code (lines
+ * usually under 200 chars) stays in the line-based regime, while
+ * single-line serialized events trip the switch.
+ */
+export const WIDE_RECORD_MEDIAN_THRESHOLD = 500;
+/** Per-file sample budget — read only the head, never the whole file. */
+const SAMPLE_BYTES_PER_FILE = 64 * 1024;
+/** Across all sampled files, never exceed this much I/O on auto-tune. */
+const SAMPLE_BYTES_TOTAL = 256 * 1024;
+/**
+ * Estimate median line length across the first chunk of up to 3 files.
+ * Used by the wide-record auto-tune.
+ *
+ * Bounded I/O: we read at most 64KB per file and at most 256KB total,
+ * regardless of file size. A file whose head contains any NUL byte is
+ * treated as binary and skipped — otherwise a stray .png in a dir spec
+ * would feed garbage into the median.
+ */
+export function sampleMedianLineLength(files) {
+    if (files.length === 0)
+        return 0;
+    const lengths = [];
+    let totalRead = 0;
+    for (const f of files.slice(0, 3)) {
+        if (totalRead >= SAMPLE_BYTES_TOTAL)
+            break;
+        let fd = -1;
+        try {
+            const stat = statSync(f);
+            if (!stat.isFile())
+                continue;
+            const want = Math.min(SAMPLE_BYTES_PER_FILE, SAMPLE_BYTES_TOTAL - totalRead, Number(stat.size));
+            if (want <= 0)
+                continue;
+            fd = openSync(f, "r");
+            const buf = Buffer.alloc(want);
+            const n = readSync(fd, buf, 0, want, 0);
+            totalRead += n;
+            // Binary heuristic: a NUL byte in the head means rg won't search
+            // this as text anyway, so it shouldn't influence auto-tune.
+            let binary = false;
+            for (let i = 0; i < Math.min(n, 4096); i++) {
+                if (buf[i] === 0) {
+                    binary = true;
+                    break;
+                }
+            }
+            if (binary)
+                continue;
+            const text = buf.toString("utf8", 0, n);
+            const lines = text.split(/\r?\n/).slice(0, 100);
+            for (const ln of lines) {
+                if (ln.length > 0)
+                    lengths.push(ln.length);
+            }
+        }
+        catch { /* skip unreadable files */ }
+        finally {
+            if (fd >= 0) {
+                try {
+                    closeSync(fd);
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    if (lengths.length === 0)
+        return 0;
+    lengths.sort((a, b) => a - b);
+    return lengths[Math.floor(lengths.length / 2)];
+}
+/**
+ * Run a search and return structured result.
+ *
+ * @example
+ *   const r = await search({ pattern: "TODO", in: ["src/"], effort: "quick" });
+ *   console.log(r.total_nodes, r.nodes[0].match_text);
+ */
+export async function search(opts) {
+    // Resolve effort defaults. Default is "quick" — cheap by design,
+    // following a "scan first, dig deeper on demand" philosophy.
+    // Agents bump to normal/deep when one shot returned ambiguous nodes.
+    const effort = opts.effort ?? "quick";
+    const preset = EFFORT_DEFAULTS[effort];
+    const userSetBefore = opts.before !== undefined;
+    const userSetAfter = opts.after !== undefined;
+    let before = opts.before ?? preset.before;
+    let after = opts.after ?? preset.after;
+    const maxNodes = opts.maxNodes ?? preset.maxNodes;
+    const strategy = opts.strategy ?? "fill";
+    // Build source list. Path inputs go through resolvePathSpecs which
+    // handles globs, dirs, @- and @file. Other sources are captured
+    // inline.
+    const pathInputs = [...(opts.in ?? [])];
+    let palace = null;
+    const palacePath = opts.palacePath ?? defaultPalacePath();
+    if (opts.from || (opts.compose && opts.compose.length > 0)) {
+        palace = loadPalace(palacePath);
+        const names = opts.from ? [opts.from] : opts.compose;
+        for (const s of composeToSources(palace, names)) {
+            pathInputs.unshift(s.id);
+        }
+    }
+    // Split into literal files (cheap per-file fan-out, hot content
+    // cache) vs bulk specs (dirs / globs / @file expansions of dirs)
+    // that we hand to rg as-is so it can do its own parallel walk.
+    // The old code expanded everything to per-file specs up front, which
+    // turned a `--in .` scan into hundreds of rg spawns — measured 30s+
+    // on the perf bench. Letting rg walk one spec is ~100ms.
+    const { files, bulk } = pathInputs.length > 0
+        ? await classifyPathSpecs(pathInputs)
+        : { files: [], bulk: [] };
+    // Wide-record auto-tune. If the user didn't pass explicit
+    // before/after and the corpus has very long lines (e.g. JSONL
+    // events), drop padding to 0 so we don't pull in entire neighboring
+    // records around each match. This is the headline product fix for
+    // the conversational-corpus benchmark.
+    let autoTuneApplied = false;
+    if (!opts.noAutoTune && !userSetBefore && !userSetAfter && files.length > 0) {
+        const median = sampleMedianLineLength(files);
+        if (median > WIDE_RECORD_MEDIAN_THRESHOLD) {
+            before = 0;
+            after = 0;
+            autoTuneApplied = true;
+        }
+    }
+    // Explicit files first, then bulk specs. The ordering matters when
+    // `max_nodes` caps the result: a user who lists specific files
+    // alongside a dir means "I care about these specifically — show me
+    // their hits before you start mining the dir."
+    const resolved = files.map((f) => ({
+        source: { id: f, type: "file" },
+        content: null,
+    }));
+    for (const b of bulk) {
+        resolved.push({ source: { id: b, type: "bulk" }, content: null });
+    }
+    if (opts.cmd) {
+        const content = await captureCommand(opts.cmd);
+        resolved.push({
+            source: { id: `cmd:${opts.cmd}`, type: "command", label: `$ ${opts.cmd}` },
+            content,
+        });
+    }
+    if (opts.url) {
+        const content = await captureUrl(opts.url);
+        resolved.push({ source: { id: opts.url, type: "url" }, content });
+    }
+    if (opts.stdin) {
+        const content = await captureStdin();
+        resolved.push({ source: { id: "stdin", type: "stdin" }, content });
+    }
+    // Run rg + build nodes.
+    const t0 = Date.now();
+    const errors = [];
+    // Fuzzy: trigram-union regex driver + Levenshtein post-filter (./fuzzy.ts).
+    const effectivePattern = opts.fuzzy ? buildFuzzyRegex(opts.pattern) : opts.pattern;
+    const rgOpts = {
+        case_insensitive: opts.rg?.caseInsensitive,
+        word_match: opts.rg?.word,
+        fixed_strings: opts.rg?.fixedStrings,
+        multiline: opts.rg?.multiline,
+        hidden: opts.rg?.hidden,
+        no_ignore: opts.rg?.noIgnore,
+        include_globs: opts.rg?.include,
+        exclude_globs: opts.rg?.exclude,
+        type: opts.rg?.type,
+    };
+    // Per-source scan worker. Returns the nodes for that source plus an
+    // optional error.
+    //
+    // Content caching: each match comes back tagged with its actual file
+    // path (rg.ts overrides match.source for matches from file/bulk
+    // searches). We cache per-file so a 1000-match file reads once, AND
+    // a bulk search across many files doesn't accidentally reuse one
+    // file's content for another file's matches.
+    async function scanSource(rs, nodeBudget) {
+        const out = [];
+        // For inline-content sources (cmd/url/stdin) the source content is
+        // always `rs.content`; for file/bulk sources we cache per file path.
+        const inlineContent = rs.content;
+        const fileCache = new Map();
+        // rg emits one match record per submatch. Two TODOs on one line
+        // (e.g. `// TODO: x; // TODO: y`) become two `Match` objects with
+        // identical `(source.id, line)`. We always dedup by line so each
+        // line contributes one node, regardless of auto-tune state.
+        const seenLines = new Set();
+        try {
+            for await (const match of runRg(effectivePattern, rs.source, rs.content, rgOpts)) {
+                if (out.length >= nodeBudget)
+                    break;
+                if (opts.fuzzy) {
+                    if (!verifyFuzzy(match.text, match.match_start, opts.pattern, 2))
+                        continue;
+                }
+                const lineKey = `${match.source.id}:${match.line}`;
+                if (seenLines.has(lineKey))
+                    continue;
+                seenLines.add(lineKey);
+                let content;
+                if (inlineContent !== null) {
+                    content = inlineContent;
+                }
+                else {
+                    const cached = fileCache.get(match.source.id);
+                    if (cached !== undefined) {
+                        content = cached;
+                    }
+                    else {
+                        content = loadSourceContent(match.source, null);
+                        fileCache.set(match.source.id, content);
+                    }
+                }
+                const node = buildNode(match, content, {
+                    beforeTokens: before,
+                    afterTokens: after,
+                    clipChars: opts.clipChars,
+                });
+                out.push(node);
+                if (out.length >= nodeBudget)
+                    break;
+            }
+            return { nodes: out, error: null };
+        }
+        catch (err) {
+            const msg = err instanceof RgError
+                ? err.message
+                : `${err.message}`;
+            return { nodes: out, error: msg };
+        }
+    }
+    // Bounded-parallel scan across resolved sources. Each worker still
+    // honors the overall `maxNodes` cap conservatively by partitioning
+    // the budget; we re-truncate after merging to enforce the hard cap.
+    // Parallelism = min(resolved.length, RG_CONCURRENCY).
+    const RG_CONCURRENCY = Math.max(1, parseInt(process.env.MPG_RG_CONCURRENCY ?? "4", 10) || 4);
+    const allNodes = [];
+    // Track which file paths we've already attributed a node to so a
+    // bulk source can't blot out the explicit files alongside it under
+    // a tight maxNodes cap.
+    const dedupKey = new Set();
+    for (let i = 0; i < resolved.length; i += RG_CONCURRENCY) {
+        if (allNodes.length >= maxNodes)
+            break;
+        const batch = resolved.slice(i, i + RG_CONCURRENCY);
+        // Per-worker budget. For file/cmd/url/stdin sources we cap at
+        // maxNodes (one source can't legally produce more than the global
+        // cap). For bulk sources we let the worker over-collect — a bulk
+        // walk can produce matches from many files, and we want the
+        // orchestrator's round-robin interleave to do the fair-share
+        // distribution rather than rg's walk order silently picking
+        // winners. The 4x spread is enough to cover ~4 files at the cap
+        // before we have to worry about real memory pressure.
+        const results = await Promise.all(batch.map((rs) => {
+            const budget = rs.source.type === "bulk" ? maxNodes * 4 : maxNodes;
+            return scanSource(rs, budget);
+        }));
+        // Merge in input order, deduping by (file, match_line) so that a
+        // bulk source that re-walks a file already covered by an explicit
+        // file spec doesn't double-count.
+        for (let j = 0; j < batch.length; j++) {
+            const { nodes: workerNodes, error } = results[j];
+            if (error) {
+                errors.push({ source: batch[j].source.id, message: error });
+            }
+            for (const n of workerNodes) {
+                if (allNodes.length >= maxNodes)
+                    break;
+                const k = `${n.source.id}:${n.match_line}`;
+                if (dedupKey.has(k))
+                    continue;
+                dedupKey.add(k);
+                allNodes.push(n);
+            }
+            if (allNodes.length >= maxNodes)
+                break;
+        }
+    }
+    // Interleave round-robin so when a tight maxNodes cap is in play,
+    // every distinct source contributes before any one source repeats.
+    // This preserves the test-23-style semantic where listing a dir +
+    // an explicit file should surface both in sources_count even at
+    // very tight caps. We compute the round-robin AFTER the in-order
+    // merge so the natural file-order is preserved when budget allows.
+    if (allNodes.length > 0 && allNodes.length < maxNodes * 2) {
+        const bySource = new Map();
+        for (const n of allNodes) {
+            const id = n.source.id;
+            let arr = bySource.get(id);
+            if (!arr) {
+                arr = [];
+                bySource.set(id, arr);
+            }
+            arr.push(n);
+        }
+        if (bySource.size > 1) {
+            const interleaved = [];
+            const buckets = [...bySource.values()];
+            let still = true;
+            let idx = 0;
+            while (still && interleaved.length < allNodes.length) {
+                still = false;
+                for (const b of buckets) {
+                    if (idx < b.length) {
+                        interleaved.push(b[idx]);
+                        still = true;
+                    }
+                }
+                idx++;
+            }
+            allNodes.length = 0;
+            for (const n of interleaved)
+                allNodes.push(n);
+        }
+    }
+    // Optional ordering by source file mtime.
+    if (opts.sort === "recent" || opts.sort === "oldest") {
+        const mtimes = new Map();
+        for (const n of allNodes) {
+            const id = n.source.id;
+            if (mtimes.has(id))
+                continue;
+            if (n.source.type === "file") {
+                try {
+                    mtimes.set(id, statSync(id).mtimeMs);
+                }
+                catch {
+                    mtimes.set(id, 0);
+                }
+            }
+            else {
+                // Non-file sources have no mtime; push to one end.
+                mtimes.set(id, opts.sort === "recent" ? -Infinity : Infinity);
+            }
+        }
+        const dir = opts.sort === "recent" ? -1 : 1;
+        allNodes.sort((a, b) => {
+            const ma = mtimes.get(a.source.id) ?? 0;
+            const mb = mtimes.get(b.source.id) ?? 0;
+            if (ma !== mb)
+                return dir * (ma - mb);
+            // Stable within a file: preserve match-line order.
+            return (a.match_line ?? 0) - (b.match_line ?? 0);
+        });
+    }
+    // Apply window-decay curve before total-budget enforcement so the
+    // smaller windows count against the cap accurately.
+    const windowCurve = opts.windowCurve ?? "flat";
+    if (windowCurve !== "flat") {
+        applyWindowCurve(allNodes, windowCurve, before, after);
+    }
+    const { nodes: budgeted, truncated } = applyTotalBudget(allNodes, opts.maxTokens, strategy);
+    // Apply pagination if requested.
+    const { paginate } = await import("./pagination.js");
+    const { items: paged, pagination } = paginate(budgeted, {
+        page: opts.page,
+        pageSize: opts.pageSize,
+        all: opts.all,
+    });
+    paged.forEach((n, i) => { n.id = i + 1; });
+    const sources = new Set(budgeted.map((n) => n.source.id));
+    const totalTokens = budgeted.reduce((s, n) => s + n.tokens, 0);
+    const pageTokens = paged.reduce((s, n) => s + n.tokens, 0);
+    // Status: if any source errored, classify by whether anything came
+    // back. Agents branching on `status` will see "partial" / "error"
+    // instead of a misleading "no_matches".
+    let status;
+    if (errors.length > 0 && budgeted.length === 0) {
+        status = "error";
+    }
+    else if (errors.length > 0) {
+        status = "partial";
+    }
+    else if (budgeted.length === 0) {
+        status = "no_matches";
+    }
+    else if (truncated) {
+        status = "truncated";
+    }
+    else {
+        status = "ok";
+    }
+    return {
+        pattern: opts.pattern,
+        effort,
+        strategy,
+        status,
+        total_nodes: budgeted.length,
+        total_tokens: totalTokens,
+        page_tokens: pageTokens,
+        sources_count: sources.size,
+        truncated,
+        nodes: paged,
+        errors,
+        duration_ms: Date.now() - t0,
+        before_tokens: before,
+        after_tokens: after,
+        max_nodes: maxNodes,
+        max_tokens: opts.maxTokens,
+        auto_tune_applied: autoTuneApplied || undefined,
+        pagination,
+    };
+}
+// ─── Mind palace operations ─────────────────────────────────────────
+/**
+ * Stash a search result in the mind palace.
+ *
+ * The `result` can be a SearchResult, or just an array of Nodes.
+ * Returns the action taken (created/merged/replaced) and the full stash.
+ */
+export async function stash(result, opts) {
+    const palacePath = opts.palacePath ?? defaultPalacePath();
+    const palace = loadPalace(palacePath);
+    const nodes = Array.isArray(result) ? result : result.nodes;
+    const sources = Array.isArray(result)
+        ? [...new Set(result.map((n) => n.source.id))]
+        : [...new Set(result.nodes.map((n) => n.source.id))];
+    const pattern = Array.isArray(result) ? "" : result.pattern;
+    const effort = Array.isArray(result) ? "normal" : result.effort;
+    const { action, stash: newStash } = addStashToPalace(palace, opts.name, opts.note ?? "", nodes, { pattern, effort, sources_count: sources.length }, sources, opts.tags ?? [], {
+        replace: opts.replace ?? false,
+        ttl: opts.ttl,
+        locations: opts.locations,
+    });
+    savePalace(palacePath, palace);
+    return { action, stash: newStash, palace_path: palacePath };
+}
+export function listStashes(palacePath, tagFilter) {
+    const path = palacePath ?? defaultPalacePath();
+    const palace = loadPalace(path);
+    return listStashesFromPalace(palace, tagFilter);
+}
+export function getStash(name, palacePath) {
+    const path = palacePath ?? defaultPalacePath();
+    const palace = loadPalace(path);
+    return getStashFromPalace(palace, name);
+}
+export function dropStash(name, palacePath) {
+    const path = palacePath ?? defaultPalacePath();
+    const palace = loadPalace(path);
+    const ok = dropStashFromPalace(palace, name);
+    if (ok)
+        savePalace(path, palace);
+    return ok;
+}
+/** Resolve a stash (or composition of stashes) to its source paths. */
+export function stashToSources(names, palacePath) {
+    const path = palacePath ?? defaultPalacePath();
+    const palace = loadPalace(path);
+    const arr = Array.isArray(names) ? names : [names];
+    return composeToSources(palace, arr).map((s) => s.id);
+}
+// ─── Tool calling schemas (Claude, Gemini, OpenAI) ──────────────────
+// Claude and Gemini work better with SEPARATE tools per operation
+// because each tool_use result is atomic. Five tools = five decisions.
+const SEARCH_PARAMS = {
+    type: "object",
+    properties: {
+        pattern: { type: "string", description: "Regex pattern to search for (ripgrep syntax)." },
+        in: { type: "array", items: { type: "string" },
+            description: "Paths to search: files, directories (recurses), globs, @file, @-." },
+        cmd: { type: "string", description: "Search the stdout of a shell command." },
+        url: { type: "string", description: "Fetch and search a URL." },
+        before: { type: "number", description: "Tokens of context before each match. Default 500." },
+        after: { type: "number", description: "Tokens of context after each match. Default 500." },
+        max_nodes: { type: "number", description: "Cap on number of nodes. Default 30." },
+        max_tokens: { type: "number", description: "Total token budget across all nodes." },
+        effort: { type: "string", enum: ["quick", "normal", "deep", "auto"],
+            description: "Preset. quick=200t/10n, normal=500t/30n, deep=2000t/100n." },
+        strategy: { type: "string", enum: ["fill", "deep"],
+            description: "How to use max_tokens. fill prefers more nodes, deep prefers deeper per node." },
+        from: { type: "string", description: "Scope search to files from a stashed mind-palace slot." },
+        compose: { type: "array", items: { type: "string" },
+            description: "Scope search to the union of multiple stashed slots' file lists." },
+        page: { type: "number", description: "1-indexed page number. Set to 1 to enable pagination." },
+        page_size: { type: "number", description: "Nodes per page. Default 10." },
+    },
+    required: ["pattern"],
+};
+const STASH_PARAMS = {
+    type: "object",
+    properties: {
+        name: { type: "string", description: "Name for this memory slot. Use kebab-case." },
+        note: { type: "string", description: "Free-form note describing what this stash contains." },
+        tags: { type: "array", items: { type: "string" },
+            description: "Tags for filtering: e.g. ['auth', 'p0', 'security']." },
+        pattern: { type: "string", description: "The regex pattern used in the search (for provenance)." },
+        in: { type: "array", items: { type: "string" }, description: "Paths searched (for provenance)." },
+        effort: { type: "string", enum: ["quick", "normal", "deep", "auto"] },
+        replace: { type: "boolean", description: "Overwrite an existing slot. Default: merge (dedup by file:line)." },
+        palace_path: { type: "string", description: "Override mind-palace file location." },
+    },
+    required: ["name", "note"],
+};
+/** Claude-compatible tool definitions. Drop into Claude's API. */
+export const claudeTools = [
+    {
+        type: "function",
+        function: {
+            name: "mpg_search",
+            description: "Search code, markdown, command output, and URLs for a regex " +
+                "pattern. Returns token-budgeted context nodes with file:line " +
+                "attribution. Each node is sized in tokens (not lines). Supports " +
+                "effort presets (quick/normal/deep), pagination, and scoped " +
+                "re-search from mind-palace stashes via the 'from'/'compose' fields.",
+            parameters: SEARCH_PARAMS,
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "mpg_stash",
+            description: "Save the result of a search into a named mind-palace slot " +
+                "(the LLM's instantiable short-term memory). Stashed slots can " +
+                "be used as search targets via mpg_search(from:name) or " +
+                "mpg_search(compose:[a,b]). Merges by default (dedup by file:line); " +
+                "pass replace:true to overwrite.",
+            parameters: STASH_PARAMS,
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "mpg_list_stashes",
+            description: "List all named memory slots in the mind palace. Optionally " +
+                "filter by tag. Use this to see what you've stashed before deciding " +
+                "to compose or re-search. Supports pagination.",
+            parameters: {
+                type: "object",
+                properties: {
+                    tag_filter: { type: "array", items: { type: "string" },
+                        description: "Only show stashes with all of these tags." },
+                    page: { type: "number", description: "1-indexed page number." },
+                    page_size: { type: "number", description: "Stashes per page. Default 20." },
+                    palace_path: { type: "string", description: "Override mind-palace file." },
+                },
+                required: [],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "mpg_get_stash",
+            description: "Show a single mind-palace slot. Returns the CARD VIEW by default: " +
+                "the synthesized intel an agent almost always wants — note, tags, " +
+                "search provenance, source paths (passable as mpg_search 'from'), " +
+                "relations, and node/source counts. The captured node bodies are " +
+                "omitted (5–6× cheaper). Pass with_nodes:true to include the full " +
+                "stashed nodes block; pagination only applies in that mode.",
+            parameters: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Name of the stash to retrieve." },
+                    with_nodes: {
+                        type: "boolean",
+                        description: "If true, include the captured node bodies. Default false " +
+                            "returns the card view (metadata + relations + sources only).",
+                    },
+                    page: { type: "number", description: "1-indexed page number (only when with_nodes:true)." },
+                    page_size: { type: "number", description: "Nodes per page. Default 10 (only when with_nodes:true)." },
+                    palace_path: { type: "string", description: "Override mind-palace file." },
+                },
+                required: ["name"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "mpg_drop_stash",
+            description: "Remove a slot from the mind palace. Use this to free memory when " +
+                "a line of investigation is complete. Dropped stashes are gone " +
+                "permanently (the JSON file is rewritten).",
+            parameters: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Name of the stash to drop." },
+                    palace_path: { type: "string", description: "Override mind-palace file." },
+                },
+                required: ["name"],
+            },
+        },
+    },
+];
+/** Gemini-compatible tool definitions (function_declarations array). */
+export const geminiTools = claudeTools.map((t) => ({
+    name: t.function.name,
+    description: t.function.description,
+    parameters: t.function.parameters,
+}));
+/** Legacy: single-tool definition for OpenAI-compatible APIs. */
+export const toolDefinition = {
+    name: "mpg",
+    description: "Search code, markdown, command output, and URLs. " +
+        "Use mpg_list_stashes first to see available memory slots, " +
+        "then mpg_search to find content, and mpg_stash to save results.",
+    parameters: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: ["search", "stash", "list", "get", "drop"],
+                description: "Which operation to perform.",
+            },
+            pattern: { type: "string", description: "Regex pattern (search)." },
+            in: { type: "array", items: { type: "string" }, description: "Paths to search." },
+            name: { type: "string", description: "Stash name (stash/get/drop)." },
+            note: { type: "string", description: "Stash note (stash)." },
+            tags: { type: "array", items: { type: "string" }, description: "Tags (stash/filter)." },
+            before: { type: "number" },
+            after: { type: "number" },
+            max_nodes: { type: "number" },
+            max_tokens: { type: "number" },
+            effort: { type: "string", enum: ["quick", "normal", "deep", "auto"] },
+            from: { type: "string", description: "Stash name as search target." },
+            compose: { type: "array", items: { type: "string" }, description: "Stash names as union target." },
+            page: { type: "number", description: "1-indexed page number." },
+            page_size: { type: "number", description: "Items per page." },
+        },
+        required: ["action"],
+    },
+};
+//# sourceMappingURL=api.js.map