oioxo-mcp 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# OIOXO — context engine for AI coding agents
+
+OIOXO feeds Claude Code, GitHub Copilot, Cursor and any MCP-capable agent the **minimal relevant slice** of your codebase — the exact code in play plus the API surface of its real dependencies — instead of letting the agent read whole files. Typical result: the same answer for **10-20× fewer tokens**, so your API keys and subscriptions go much further.
+
+Everything runs **100% on your device**. Your code is never uploaded — only the *count* of tokens you saved is reported to your OIOXO account for metering.
+
+## Quick start
+
+```bash
+npm install -g oioxo-mcp
+
+oioxo-mcp login   # connect your OIOXO account (opens the browser)
+oioxo-mcp init    # wire OIOXO into the agents in this project
+```
+
+Restart your agent. From the next prompt on, it calls OIOXO before reading files.
+
+`init` detects Claude Code (`.mcp.json`), VS Code / Copilot (`.vscode/mcp.json`) and Cursor (`.cursor/mcp.json`), and **merges** into existing configs — your other MCP servers are untouched.
+
+## What the agent gets
+
+| Tool | What it does |
+|---|---|
+| `get_context` | The main event: BM25 retrieval + import-graph expansion → anchors in full, dependencies as signatures only. |
+| `get_skeleton` | One file's API surface without implementation bodies. |
+| `get_impact` | Blast radius: what a file imports, and everything that imports it. |
+| `remember` / `recall` | Durable project memory in `.oioxo/` — shared with the OIOXO IDEs. |
+
+## Plans
+
+The context engine is part of your OIOXO account:
+
+- **OIOXO Free** — a monthly saved-tokens allowance to feel the difference.
+- **OIOXO Pro** — unlimited, across every agent and every project → [oioxo.com](https://oioxo.com/?upgrade=pro)
+
+Plan checks are server-side; `oioxo-mcp status` shows your remaining allowance, plan and index stats.
+
+## How it works
+
+1. **Index** — your project is chunked and BM25-indexed in memory (~1500 files max, deps/build output excluded). No model, no GPU, instant and offline.
+2. **Anchor** — a task query retrieves the highest-confidence chunks.
+3. **Expand** — the import graph pulls in the files the anchors *actually depend on* (and their callers), rejecting files that merely share words.
+4. **Compress** — anchors ship as full code, neighbors ship as signatures. That asymmetry is the saving.
+
+## Commands
+
+```
+oioxo-mcp login            connect your OIOXO account
+oioxo-mcp init [--all]     write agent MCP configs ( --all = every supported agent )
+oioxo-mcp serve            run the MCP server (agent configs call this)
+oioxo-mcp status           plan, savings and index stats
+oioxo-mcp logout           remove the stored credential
+```
+
+---
+
+© OIOXO · [oioxo.com](https://oioxo.com)

package/dist/cli/agents.d.ts

@@ -0,0 +1,9 @@
+export interface InitOptions {
+    /** Force-write the per-PROJECT files even when not detected. */
+    all?: boolean;
+    /** Custom server command (default: npx -y oioxo-mcp). */
+    command?: string;
+    /** Home dir override (tests). */
+    home?: string;
+}
+export declare function initAgents(root: string, opts?: InitOptions): Promise<void>;

package/dist/cli/agents.js

@@ -0,0 +1,155 @@
+/**
+ * `oioxo-mcp init` — agent auto-configuration. Detects which AI coding agents
+ * touch this project / machine and writes each one's MCP config so the OIOXO
+ * context engine is available the next time the agent starts. One install,
+ * OIOXO everywhere.
+ *
+ * Per-PROJECT files (the user chooses whether to commit them):
+ *   Claude Code      → .mcp.json               { mcpServers }
+ *   VS Code/Copilot  → .vscode/mcp.json        { servers }     (VS Code's own key)
+ *   Cursor           → .cursor/mcp.json        { mcpServers }
+ * Per-MACHINE files (written only when the tool is actually installed):
+ *   Windsurf         → ~/.codeium/windsurf/mcp_config.json  { mcpServers }
+ *   Gemini CLI       → ~/.gemini/settings.json              { mcpServers }
+ *   Codex CLI        → ~/.codex/config.toml                 [mcp_servers.oioxo]
+ * Existing files are MERGED, never clobbered — we only add/replace the "oioxo" entry.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { spawnSync } from 'node:child_process';
+const onPath = (cmd) => {
+    try {
+        const probe = process.platform === 'win32' ? 'where' : 'which';
+        return spawnSync(probe, [cmd], { stdio: 'ignore', timeout: 4000 }).status === 0;
+    }
+    catch {
+        return false;
+    }
+};
+const dirExists = async (p) => {
+    try {
+        return (await fs.stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const TARGETS = [
+    {
+        id: 'claude-code',
+        display: 'Claude Code',
+        kind: 'json',
+        key: 'mcpServers',
+        file: (root) => path.join(root, '.mcp.json'),
+        detect: async () => onPath('claude'),
+    },
+    {
+        id: 'vscode-copilot',
+        display: 'VS Code / GitHub Copilot',
+        kind: 'json',
+        key: 'servers',
+        file: (root) => path.join(root, '.vscode', 'mcp.json'),
+        detect: async (root) => (await dirExists(path.join(root, '.vscode'))) || onPath('code'),
+    },
+    {
+        id: 'cursor',
+        display: 'Cursor',
+        kind: 'json',
+        key: 'mcpServers',
+        file: (root) => path.join(root, '.cursor', 'mcp.json'),
+        detect: async (root) => (await dirExists(path.join(root, '.cursor'))) || onPath('cursor'),
+    },
+    {
+        id: 'windsurf',
+        display: 'Windsurf',
+        kind: 'json',
+        key: 'mcpServers',
+        global: true,
+        file: (_root, home) => path.join(home, '.codeium', 'windsurf', 'mcp_config.json'),
+        detect: async (_root, home) => dirExists(path.join(home, '.codeium', 'windsurf')),
+    },
+    {
+        id: 'gemini-cli',
+        display: 'Gemini CLI',
+        kind: 'json',
+        key: 'mcpServers',
+        global: true,
+        file: (_root, home) => path.join(home, '.gemini', 'settings.json'),
+        detect: async (_root, home) => dirExists(path.join(home, '.gemini')),
+    },
+    {
+        id: 'codex',
+        display: 'Codex CLI',
+        kind: 'toml',
+        global: true,
+        file: (_root, home) => path.join(home, '.codex', 'config.toml'),
+        detect: async (_root, home) => dirExists(path.join(home, '.codex')),
+    },
+];
+/** The server entry every host gets. `npx -y` keeps it version-current. */
+function serverEntry(command) {
+    if (command) {
+        const [cmd, ...args] = command.split(' ');
+        return { command: cmd, args: [...args, 'serve'] };
+    }
+    return { command: 'npx', args: ['-y', 'oioxo-mcp', 'serve'] };
+}
+async function mergeWriteJson(file, key, entry) {
+    let existing = {};
+    try {
+        existing = JSON.parse(await fs.readFile(file, 'utf8'));
+    }
+    catch { /* fresh file */ }
+    const section = existing[key] ?? {};
+    section['oioxo'] = entry;
+    existing[key] = section;
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, JSON.stringify(existing, null, 2) + '\n', 'utf8');
+}
+/** Codex config is TOML — append our section if absent (never rewrite the file). */
+async function appendToml(file, entry) {
+    let existing = '';
+    try {
+        existing = await fs.readFile(file, 'utf8');
+    }
+    catch { /* fresh file */ }
+    if (/^\s*\[mcp_servers\.oioxo\]/m.test(existing))
+        return false; // already wired — leave the user's edits alone
+    const block = `\n[mcp_servers.oioxo]\n` +
+        `command = "${entry.command}"\n` +
+        `args = [${entry.args.map((a) => `"${a}"`).join(', ')}]\n`;
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, existing + block, 'utf8');
+    return true;
+}
+export async function initAgents(root, opts = {}) {
+    const home = opts.home ?? os.homedir();
+    const entry = serverEntry(opts.command);
+    let wrote = 0;
+    console.log('\nOIOXO — wiring the context engine into your agents');
+    for (const t of TARGETS) {
+        // --all forces project files; machine-level configs only when the tool exists.
+        const want = t.global ? await t.detect(root, home) : opts.all || (await t.detect(root, home));
+        if (!want) {
+            console.log(`  · ${t.display}: not detected${t.global ? '' : ' (use --all to force)'}`);
+            continue;
+        }
+        const file = t.file(root, home);
+        if (t.kind === 'toml') {
+            const added = await appendToml(file, entry);
+            console.log(added ? `  ✓ ${t.display}: ${file}` : `  ✓ ${t.display}: already configured (${file})`);
+        }
+        else {
+            await mergeWriteJson(file, t.key, entry);
+            console.log(`  ✓ ${t.display}: ${t.global ? file : path.relative(root, file)}`);
+        }
+        wrote++;
+    }
+    if (!wrote) {
+        console.log('  No agents detected. Run with --all to write the project configs anyway.');
+        return;
+    }
+    console.log('\nRestart your agent (or reload the window) and it will call OIOXO before reading files.');
+    console.log('Not connected yet? Run `oioxo-mcp login`.');
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * OIOXO MCP CLI — the context engine for AI coding agents.
+ *
+ *   oioxo-mcp login           connect your OIOXO account (browser handoff)
+ *   oioxo-mcp init [--all]    wire OIOXO into the agents in this project
+ *   oioxo-mcp serve           run the MCP server (what agent configs invoke)
+ *   oioxo-mcp status          index + account + savings at a glance
+ *   oioxo-mcp logout          forget the stored credential
+ */
+import { login } from './login.js';
+import { initAgents } from './agents.js';
+import { startServer } from '../mcp/server.js';
+import { loadProject } from '../core/files.js';
+import { Bm25Index } from '../core/bm25.js';
+import { readCredentials, clearCredentials, saveMeter, CONTROL_PLANE } from '../gate/account.js';
+const HELP = `OIOXO — context engine for AI coding agents (https://oioxo.com)
+
+Usage: oioxo-mcp <command>
+
+Commands:
+  login            Connect your OIOXO account (opens the browser)
+  init [--all]     Write MCP configs for the agents in this project
+                   (--all: write every supported agent; --command "<cmd>": custom server command)
+  serve            Run the MCP server over stdio (agents call this; you rarely will)
+  status           Show account tier, monthly savings and index stats
+  logout           Remove the stored credential from this machine
+`;
+async function status(root) {
+    console.log('\nOIOXO status');
+    console.log(`  Control plane : ${CONTROL_PLANE}`);
+    const creds = await readCredentials();
+    if (!creds || creds.expiresAt <= Date.now()) {
+        console.log('  Account       : not connected — run `oioxo-mcp login`');
+    }
+    else {
+        const days = Math.max(0, Math.round((creds.expiresAt - Date.now()) / 86_400_000));
+        console.log(`  Account       : connected (credential valid ~${days}d)`);
+        const s = await saveMeter('check');
+        if (s?.tier === 'pro')
+            console.log('  Plan          : OIOXO Pro — unlimited context engine');
+        else if (s?.tier === 'free')
+            console.log(`  Plan          : OIOXO Free — ${s.remainingTokens?.toLocaleString() ?? 0} saved-tokens left this month (resets ${new Date(s.resetsAt).toUTCString()})`);
+        else if (s)
+            console.log(`  Plan          : ${s.tier}`);
+        else
+            console.log('  Plan          : could not reach oioxo.com');
+    }
+    const files = await loadProject(root);
+    const idx = new Bm25Index();
+    const st = idx.build(files);
+    console.log(`  Index         : ${st.files} files, ${st.chunks} chunks (in-memory, on-device)`);
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    const root = process.cwd();
+    switch (cmd) {
+        case 'login':
+            await login();
+            return;
+        case 'logout':
+            await clearCredentials();
+            console.log('OIOXO credential removed from this machine.');
+            return;
+        case 'init': {
+            const all = rest.includes('--all');
+            const ci = rest.indexOf('--command');
+            const command = ci >= 0 ? rest[ci + 1] : undefined;
+            await initAgents(root, { all, command });
+            return;
+        }
+        case 'serve':
+            // stdio belongs to the MCP transport from here on — no console output.
+            await startServer(root);
+            return;
+        case 'status':
+            await status(root);
+            return;
+        default:
+            console.log(HELP);
+    }
+}
+main().catch((err) => {
+    console.error(`oioxo-mcp: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});

package/dist/cli/login.d.ts

@@ -0,0 +1 @@
+export declare function login(): Promise<void>;

package/dist/cli/login.js

@@ -0,0 +1,125 @@
+/**
+ * `oioxo-mcp login` — loopback browser handoff (the `gh auth login` pattern).
+ *
+ * 1. Start a one-shot HTTP listener on 127.0.0.1:<random port>.
+ * 2. Open https://oioxo.com/cli-auth?port=<port>&state=<nonce> in the browser.
+ * 3. The signed-in user clicks Authorize there; the page mints a 30-day device
+ *    bearer via /api/auth/device-token and POSTs it to the listener with the
+ *    state nonce echoed. Wrong/missing nonce → rejected.
+ * 4. Store the bearer in ~/.oioxo/credentials.json (0600).
+ *
+ * The token only ever travels oioxo.com → this machine's loopback. CORS is
+ * scoped to the OIOXO origin so no other site can talk to the listener.
+ */
+import * as http from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { CONTROL_PLANE, writeCredentials, deviceId, saveMeter } from '../gate/account.js';
+const LOGIN_TIMEOUT_MS = 5 * 60_000;
+// Served by the loopback listener after a successful handoff — the tab the
+// user lands on. Same restrained OIOXO look: white, one gold accent.
+const SUCCESS_HTML = `<!doctype html><html><head><meta charset="utf-8"><title>OIOXO CLI connected</title></head>
+<body style="margin:0;display:flex;align-items:center;justify-content:center;min-height:100vh;background:#fafafa;font-family:ui-sans-serif,system-ui,Segoe UI,sans-serif">
+<div style="background:#fff;border-radius:16px;box-shadow:0 10px 30px rgba(0,0,0,.08);padding:28px;max-width:380px">
+<div style="display:flex;align-items:center;gap:8px;margin-bottom:18px">
+<span style="display:inline-block;width:10px;height:10px;border-radius:50%;background:#E2B24A"></span>
+<span style="font-family:ui-monospace,monospace;font-size:13px;font-weight:500;color:#232327">OIOXO</span></div>
+<h1 style="font-size:17px;margin:0 0 8px;color:#232327">OIOXO CLI connected</h1>
+<p style="font-size:13.5px;line-height:1.6;color:#71717a;margin:0">You can close this tab and return to your terminal.</p>
+</div></body></html>`;
+function openBrowser(url) {
+    const platform = process.platform;
+    // `start` must go through cmd on Windows; '' is the window-title slot.
+    if (platform === 'win32')
+        spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
+    else if (platform === 'darwin')
+        spawn('open', [url], { detached: true, stdio: 'ignore' }).unref();
+    else
+        spawn('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
+}
+export async function login() {
+    const state = randomBytes(24).toString('base64url');
+    const device = await deviceId();
+    const tokenPromise = new Promise((resolve, reject) => {
+        const server = http.createServer((req, res) => {
+            const allowOrigin = new URL(CONTROL_PLANE).origin;
+            res.setHeader('Access-Control-Allow-Origin', allowOrigin);
+            res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+            res.setHeader('Access-Control-Allow-Headers', 'content-type');
+            // Chrome Private Network Access: a public https page fetching loopback
+            // must see this on the preflight, or the request is blocked.
+            res.setHeader('Access-Control-Allow-Private-Network', 'true');
+            if (req.method === 'OPTIONS') {
+                res.writeHead(204).end();
+                return;
+            }
+            if (req.method !== 'POST' || req.url !== '/oioxo/token') {
+                res.writeHead(404).end();
+                return;
+            }
+            let body = '';
+            req.on('data', (c) => { body += c; if (body.length > 64_000)
+                req.destroy(); });
+            req.on('end', () => {
+                try {
+                    // The page delivers via a top-level form POST (urlencoded) — fetch() to
+                    // loopback is blocked by Chrome's Local Network Access. JSON kept for
+                    // forward-compat with clients that may hold the LNA permission.
+                    const ct = req.headers['content-type'] ?? '';
+                    let j;
+                    if (ct.includes('application/json')) {
+                        j = JSON.parse(body);
+                    }
+                    else {
+                        const p = new URLSearchParams(body);
+                        j = {
+                            state: p.get('state') ?? undefined,
+                            token: p.get('token') ?? undefined,
+                            expiresInSeconds: p.get('expiresInSeconds') ? Number(p.get('expiresInSeconds')) : undefined,
+                        };
+                    }
+                    if (j.state !== state || !j.token) {
+                        res.writeHead(400, { 'content-type': 'text/html' }).end('<p>OIOXO: invalid or expired login request. Run <code>oioxo-mcp login</code> again.</p>');
+                        return;
+                    }
+                    res.writeHead(200, { 'content-type': 'text/html' }).end(SUCCESS_HTML);
+                    server.close();
+                    resolve({ token: j.token, expiresInSeconds: j.expiresInSeconds });
+                }
+                catch {
+                    res.writeHead(400).end();
+                }
+            });
+        });
+        server.on('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            const port = typeof addr === 'object' && addr ? addr.port : 0;
+            const url = `${CONTROL_PLANE}/cli-auth?port=${port}&state=${state}`;
+            console.log('\nOIOXO — connect your account');
+            console.log(`Opening ${url}`);
+            console.log('If the browser does not open, paste the URL yourself.\n');
+            // OIOXO_NO_BROWSER=1: print the URL only (CI / e2e / remote shells).
+            if (process.env.OIOXO_NO_BROWSER !== '1')
+                openBrowser(url);
+        });
+        setTimeout(() => { server.close(); reject(new Error('timeout')); }, LOGIN_TIMEOUT_MS).unref();
+    });
+    const { token, expiresInSeconds } = await tokenPromise;
+    await writeCredentials({
+        token,
+        expiresAt: Date.now() + (expiresInSeconds ?? 30 * 24 * 3600) * 1000,
+        device,
+    });
+    const stateNow = await saveMeter('check');
+    if (stateNow?.tier === 'pro') {
+        console.log('Connected — OIOXO Pro: unlimited context engine. ✓');
+    }
+    else if (stateNow?.tier === 'free') {
+        const rem = stateNow.remainingTokens?.toLocaleString() ?? '—';
+        console.log(`Connected — OIOXO Free: ${rem} saved-tokens remaining this month. Pro is unlimited → https://oioxo.com/?upgrade=pro ✓`);
+    }
+    else {
+        console.log('Connected. ✓');
+    }
+}

package/dist/core/bm25.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OIOXO BM25 lexical index — ported from the desktop IDE's on-device @codebase
+ * engine (oioxoCodebaseIndexService). BM25, not embeddings, is the deliberate
+ * choice: no model, no GPU, instant + offline, and for code (identifiers,
+ * symbols, error strings) lexical match is strong.
+ *
+ * Chunking: ~60-line windows with 12-line overlap so a symbol near a boundary
+ * still appears whole in at least one chunk.
+ */
+import type { ProjectFile } from './files.js';
+export interface RetrievedChunk {
+    path: string;
+    startLine: number;
+    endLine: number;
+    text: string;
+    score: number;
+}
+export interface IndexStatus {
+    files: number;
+    chunks: number;
+}
+export declare function tokenize(s: string): string[];
+export declare class Bm25Index {
+    private chunks;
+    private df;
+    private avgLen;
+    private _status;
+    status(): IndexStatus;
+    build(files: ProjectFile[]): IndexStatus;
+    retrieve(query: string, k?: number): RetrievedChunk[];
+}

package/dist/core/bm25.js

@@ -0,0 +1,103 @@
+const CHUNK_LINES = 60;
+const CHUNK_OVERLAP = 12;
+const MAX_CHUNK_CHARS = 4000;
+export function tokenize(s) {
+    // Split identifiers too: camelCase / snake_case / kebab → sub-tokens, so a
+    // query "user auth" matches "getUserAuthToken".
+    const raw = s.toLowerCase().match(/[a-z0-9_]+/g) ?? [];
+    const out = [];
+    for (const t of raw) {
+        out.push(t);
+        for (const part of t.split('_'))
+            if (part && part !== t)
+                out.push(part);
+    }
+    for (const m of s.match(/[A-Za-z][a-z0-9]+|[A-Z]+(?![a-z])/g) ?? []) {
+        const low = m.toLowerCase();
+        if (low.length > 1)
+            out.push(low);
+    }
+    return out.filter((t) => t.length > 1 && t.length < 40);
+}
+export class Bm25Index {
+    chunks = [];
+    df = new Map();
+    avgLen = 0;
+    _status = { files: 0, chunks: 0 };
+    status() {
+        return this._status;
+    }
+    build(files) {
+        const chunks = [];
+        for (const f of files) {
+            const lines = f.content.split('\n');
+            for (let start = 0; start < lines.length; start += CHUNK_LINES - CHUNK_OVERLAP) {
+                const slice = lines.slice(start, start + CHUNK_LINES);
+                const chunkText = slice.join('\n').slice(0, MAX_CHUNK_CHARS);
+                if (chunkText.trim()) {
+                    const tokens = tokenize(chunkText);
+                    if (tokens.length) {
+                        const tf = new Map();
+                        for (const t of tokens)
+                            tf.set(t, (tf.get(t) ?? 0) + 1);
+                        chunks.push({
+                            path: f.path,
+                            startLine: start + 1,
+                            endLine: Math.min(start + CHUNK_LINES, lines.length),
+                            text: chunkText,
+                            tf,
+                            len: tokens.length,
+                        });
+                    }
+                }
+                if (start + CHUNK_LINES >= lines.length)
+                    break;
+            }
+        }
+        const df = new Map();
+        let totalLen = 0;
+        for (const c of chunks) {
+            totalLen += c.len;
+            for (const term of c.tf.keys())
+                df.set(term, (df.get(term) ?? 0) + 1);
+        }
+        this.chunks = chunks;
+        this.df = df;
+        this.avgLen = chunks.length ? totalLen / chunks.length : 0;
+        this._status = { files: files.length, chunks: chunks.length };
+        return this._status;
+    }
+    retrieve(query, k = 6) {
+        if (!this.chunks.length)
+            return [];
+        const qTerms = tokenize(query);
+        if (!qTerms.length)
+            return [];
+        const N = this.chunks.length;
+        const k1 = 1.5;
+        const b = 0.75;
+        const scored = this.chunks
+            .map((c) => {
+            let score = 0;
+            for (const term of qTerms) {
+                const f = c.tf.get(term);
+                if (!f)
+                    continue;
+                const n = this.df.get(term) ?? 0;
+                const idf = Math.log(1 + (N - n + 0.5) / (n + 0.5));
+                const denom = f + k1 * (1 - b + b * (c.len / (this.avgLen || 1)));
+                score += idf * ((f * (k1 + 1)) / denom);
+            }
+            return { c, score };
+        })
+            .filter((s) => s.score > 0);
+        scored.sort((a, b2) => b2.score - a.score);
+        return scored.slice(0, k).map(({ c, score }) => ({
+            path: c.path,
+            startLine: c.startLine,
+            endLine: c.endLine,
+            text: c.text,
+            score,
+        }));
+    }
+}

package/dist/core/capsule.d.ts

@@ -0,0 +1,34 @@
+/**
+ * OIOXO context capsule — the engine's main product. For a task/query it
+ * returns the MINIMAL relevant slice of the codebase:
+ *
+ *   1. BM25 retrieval picks high-confidence ANCHOR chunks (lexical, on-device);
+ *   2. the import graph EXPANDS anchors to the files they actually depend on
+ *      (the Context Compiler pattern — rejects same-words-only decoys);
+ *   3. anchors ship as full excerpts, neighbors ship as SKELETONS (signatures,
+ *      no bodies) — that asymmetry is where the token saving lives.
+ *
+ * `savedTokens` is the honest estimate of what the agent did NOT have to read:
+ * (full size of every file represented in the capsule − capsule size) / 4.
+ */
+import type { ProjectFile } from './files.js';
+import { Bm25Index, type RetrievedChunk } from './bm25.js';
+export interface Capsule {
+    /** Ready-to-inject context block. */
+    text: string;
+    /** Files represented (anchors first). */
+    files: string[];
+    /** Estimated tokens the agent avoided reading (capsule vs full files). */
+    savedTokens: number;
+    /** Raw anchor chunks (for callers that want structure). */
+    chunks: RetrievedChunk[];
+}
+export interface CapsuleOptions {
+    /** Max anchor chunks from BM25. */
+    topChunks?: number;
+    /** Max files in the expanded slice. */
+    maxFiles?: number;
+    /** Cap on the capsule text size (chars). */
+    maxChars?: number;
+}
+export declare function buildCapsule(query: string, files: ProjectFile[], index: Bm25Index, opts?: CapsuleOptions): Capsule;

package/dist/core/capsule.js

@@ -0,0 +1,50 @@
+import { buildGraph, expandContext } from './code-graph.js';
+import { fileSkeleton } from './skeleton.js';
+const APPROX_CHARS_PER_TOKEN = 4;
+export function buildCapsule(query, files, index, opts = {}) {
+    const topChunks = opts.topChunks ?? 6;
+    const maxFiles = opts.maxFiles ?? 10;
+    const maxChars = opts.maxChars ?? 24_000;
+    const byPath = new Map(files.map((f) => [f.path, f]));
+    const chunks = index.retrieve(query, topChunks);
+    // Anchors: distinct files behind the top chunks (order of first appearance).
+    const anchors = [];
+    for (const c of chunks)
+        if (!anchors.includes(c.path))
+            anchors.push(c.path);
+    // Graph expansion: the files the anchors actually import (+1 hop of callers).
+    let slice = anchors.slice(0, maxFiles);
+    try {
+        const graph = buildGraph(files);
+        slice = expandContext(graph, anchors.slice(0, 3), { hops: 2, includeDependents: true, max: maxFiles });
+        for (const a of anchors)
+            if (!slice.includes(a) && slice.length < maxFiles)
+                slice.push(a);
+    }
+    catch {
+        // graph is an optimization — never break retrieval
+    }
+    const parts = [];
+    const anchorSet = new Set(anchors);
+    // 1) Anchor chunks: the exact code in play, full text, with line refs.
+    for (const c of chunks) {
+        parts.push(`// ${c.path}:${c.startLine}-${c.endLine}\n${c.text}`);
+    }
+    // 2) Neighbor files: skeletons only.
+    for (const p of slice) {
+        if (anchorSet.has(p))
+            continue;
+        const f = byPath.get(p);
+        if (f)
+            parts.push(fileSkeleton(f.path, f.content));
+    }
+    let text = parts.join('\n\n');
+    if (text.length > maxChars)
+        text = text.slice(0, maxChars) + '\n// … capsule truncated';
+    // Savings estimate: full files the capsule REPRESENTS vs what it actually shipped.
+    let fullChars = 0;
+    for (const p of slice.length ? slice : anchors)
+        fullChars += byPath.get(p)?.content.length ?? 0;
+    const savedTokens = Math.max(0, Math.round((fullChars - text.length) / APPROX_CHARS_PER_TOKEN));
+    return { text, files: slice.length ? slice : anchors, savedTokens, chunks };
+}