agent-from-zero 0.5.0 → 0.28.0

package/dist/markdown.js

@@ -0,0 +1,152 @@
+import { Marked } from "marked"; // the parser
+import { markedTerminal } from "marked-terminal"; // the ANSI renderer
+import Table from "cli-table3"; // box-drawing table (borders + padding)
+import wrapAnsi from "wrap-ansi"; // ANSI- and CJK-aware line wrapping
+import chalk from "chalk"; // our one color source — keep the theme consistent with ui.ts
+import { displayWidth } from "./editor.js"; // CJK-/ANSI-aware display width (shared with the line editor)
+// Why a library here, not hand-rolled? Markdown→terminal is a solved, fiddly
+// problem (CJK-aware table widths, nested lists, code fences, link rewriting).
+// The agent's *core* is hand-written on purpose; this is pure presentation, so
+// we lean on `marked` + `marked-terminal` and spend our effort on the streaming
+// glue instead. The model speaks markdown; without this the screen shows raw
+// `##`, `**`, and `|---|` — exactly the ugliness this module removes.
+// ---- responsive tables ------------------------------------------------------
+// marked-terminal's `width` does NOT size tables — a wide table overflows and the
+// terminal hard-wraps it into garbage. So we render tables ourselves: shrink the
+// columns to fit the window, wrap each cell (CJK-aware, no truncation), and let
+// cli-table3 draw the box. This is what makes a table adapt to the window size.
+// Per-column CONTENT widths that fit `maxWidth` once borders/padding are paid for.
+// Start from each column's natural width, then repeatedly shave the widest until
+// the row fits — so narrow columns keep their size and the roomy ones give first.
+function tableColumnWidths(header, rows, maxWidth) {
+    const n = header.length;
+    const natural = header.map((h, i) => Math.max(displayWidth(h), ...rows.map((r) => displayWidth(r[i] ?? ""))));
+    const budget = maxWidth - (n + 1) - 2 * n; // n+1 borders, 2 cols of padding per column
+    const widths = natural.slice();
+    const MIN = 4; // never shrink a column below this many content columns
+    while (widths.reduce((a, b) => a + b, 0) > budget) {
+        const widest = widths.indexOf(Math.max(...widths));
+        if (widths[widest] <= MIN)
+            break; // can't shrink further — let it overflow rather than vanish
+        widths[widest]--;
+    }
+    return widths;
+}
+// Draw one table, wrapped to fit `maxWidth`. Cells are pre-wrapped with wrap-ansi
+// (which counts CJK as 2 and keeps ANSI styles intact across line breaks), then
+// handed to cli-table3 with wordWrap OFF — cli-table3's own wrap mis-measures CJK.
+function renderTable(header, rows, maxWidth) {
+    const content = tableColumnWidths(header, rows, maxWidth);
+    const wrapRow = (cells) => cells.map((c, i) => wrapAnsi(c ?? "", content[i], { hard: true, trim: false }));
+    const t = new Table({
+        head: wrapRow(header),
+        colWidths: content.map((w) => w + 2), // cli-table3 widths include the 2 padding columns
+        wordWrap: false, // we already wrapped — cli-table3 would mis-wrap CJK
+        style: { head: [], border: [] }, // no extra colour; keep the dim theme from the caller
+    });
+    for (const r of rows)
+        t.push(wrapRow(r));
+    return t.toString();
+}
+// The terminal theme, matched to ui.ts (cyan headers, yellow code, dim borders).
+function renderer(width) {
+    return markedTerminal({
+        width, // wrap paragraphs/tables to this many columns
+        reflowText: true, // re-wrap long paragraphs to `width` instead of one long line
+        tab: 2, // list indentation
+        showSectionPrefix: false, // drop the literal "## " in front of headings
+        firstHeading: chalk.cyan.bold,
+        heading: chalk.cyan.bold,
+        code: chalk.yellow, // fenced code block
+        codespan: chalk.cyan, // `inline code`
+        blockquote: chalk.gray.italic,
+        strong: chalk.bold,
+        em: chalk.italic,
+        del: chalk.dim.strikethrough,
+        link: chalk.cyan.underline,
+        href: chalk.cyan.underline,
+        paragraph: (s) => s,
+    });
+}
+// Render a complete markdown string to ANSI. Pure (width injectable), so tests
+// can assert on the output without a real terminal. A fresh Marked per call
+// keeps width overridable and avoids leaking global parser state.
+export function renderMarkdown(md, width = termWidth()) {
+    const w = Math.max(20, width);
+    const m = new Marked();
+    m.use(renderer(w));
+    // Override the table renderer AFTER marked-terminal so ours wins: render each
+    // cell's inline markdown to ANSI (parseInline), then lay the table out to fit w.
+    m.use({
+        renderer: {
+            table(token) {
+                const header = token.header.map((c) => this.parser.parseInline(c.tokens));
+                const rows = token.rows.map((r) => r.map((c) => this.parser.parseInline(c.tokens)));
+                return renderTable(header, rows, w) + "\n";
+            },
+        },
+    });
+    const out = m.parse(md, { async: false });
+    return out.replace(/\s+$/g, ""); // trim the trailing blank lines marked-terminal adds
+}
+function termWidth() {
+    return (process.stdout.columns || 80) - 4; // leave room for our 2-col gutter + margin
+}
+// ---- streaming glue ---------------------------------------------------------
+// marked renders a WHOLE document; the model streams tokens. The bridge: buffer
+// text and flush one markdown *block* at a time, where a block ends at a blank
+// line that is NOT inside a ``` fence. So a paragraph, heading, list, or table
+// renders the moment it's complete — you keep the live "it's typing" feel, but
+// every block lands fully formatted (a table needs all its rows to align).
+export class MarkdownStream {
+    write;
+    opts;
+    buf = ""; // text not yet flushed
+    firstLine = true; // the very first printed line gets the ⏺ prefix
+    constructor(write, // where rendered lines go (stdout in prod)
+    opts = {}) {
+        this.write = write;
+        this.opts = opts;
+    }
+    // Feed streamed tokens; flushes any blocks that are now complete.
+    push(chunk) {
+        this.buf += chunk;
+        for (let i = this.boundary(); i >= 0; i = this.boundary()) {
+            const block = this.buf.slice(0, i);
+            this.buf = this.buf.slice(i).replace(/^\n+/, ""); // drop the blank-line separator
+            if (block.trim())
+                this.emit(block);
+        }
+    }
+    // End of answer: render whatever's left as the final block.
+    end() {
+        if (this.buf.trim())
+            this.emit(this.buf);
+        this.buf = "";
+    }
+    // Index of the first blank-line boundary that sits OUTSIDE a code fence, or -1.
+    // Counting fence markers before the candidate tells us if we're inside one.
+    boundary() {
+        for (let from = 0;;) {
+            const i = this.buf.indexOf("\n\n", from);
+            if (i < 0)
+                return -1;
+            const fences = (this.buf.slice(0, i).match(/^[ \t]*(```|~~~)/gm) || []).length;
+            if (fences % 2 === 0)
+                return i; // even number of fences → not inside one
+            from = i + 2; // this blank line is inside a fence; keep looking
+        }
+    }
+    // Render one block and print it, with a left gutter so wrapped lines align
+    // under the ⏺ marker (first physical line uses firstPrefix, the rest indent).
+    emit(md) {
+        const indent = this.opts.indent ?? "  ";
+        const rendered = renderMarkdown(md, (process.stdout.columns || 80) - indent.length - 1);
+        const out = rendered.split("\n").map((ln) => {
+            const prefix = this.firstLine ? (this.opts.firstPrefix ?? indent) : indent;
+            this.firstLine = false;
+            return prefix + ln;
+        });
+        this.write(out.join("\n") + "\n");
+    }
+}

package/dist/mcp.js

@@ -0,0 +1,237 @@
+import { spawn } from "node:child_process"; // stdio servers are subprocesses
+import chalk from "chalk"; // status lines
+import { CONFIG } from "./config.js"; // configured servers
+import { registerExternalTool } from "./tools.js"; // expose discovered tools
+import { emit } from "./telemetry.js"; // observability
+// MCP (Model Context Protocol) lets the agent borrow tools from external
+// servers — a filesystem server, a GitHub server, a database server, anything.
+// The wire protocol is JSON-RPC 2.0. We do the initialize handshake, ask for the
+// server's tools, and register each one so it flows through the SAME dispatch and
+// the SAME permission gate as a built-in. There is one execution path, period.
+//
+// Since Day 24 there are TWO ways to reach a server: spawn it and talk over
+// stdio (local), or POST to a URL (remote, "Streamable HTTP"). The protocol is
+// identical; only the pipe differs. That difference lives behind a Transport
+// interface, so McpClient — handshake, ids, tool flattening — never has to care.
+//
+// Discovered tools are named mcp__<server>__<tool> so they never collide with
+// built-ins and the user can see (and gate) exactly where each came from.
+const INIT_TIMEOUT_MS = 15_000; // a server that doesn't initialize in 15s is skipped
+const CALL_TIMEOUT_MS = 60_000; // a single tool call may take this long
+// ---- stdio transport: one JSON object per line, to a subprocess --------------
+class StdioTransport {
+    child;
+    pending = new Map(); // id → resolver (responses arrive async on one stream)
+    buffer = ""; // partial stdout, reassembled into whole lines
+    constructor(def) {
+        this.child = spawn(def.command, def.args ?? [], {
+            stdio: ["pipe", "pipe", "pipe"], // we own stdin/stdout; stderr is the server's log
+            env: { ...process.env, ...def.env }, // pass through + extras
+        });
+        // Reassemble newline-delimited JSON from the stdout stream.
+        this.child.stdout.on("data", (chunk) => {
+            this.buffer += chunk.toString();
+            let nl;
+            while ((nl = this.buffer.indexOf("\n")) >= 0) {
+                const line = this.buffer.slice(0, nl).trim(); // one complete message
+                this.buffer = this.buffer.slice(nl + 1); // keep the remainder
+                if (line)
+                    this.onMessage(line);
+            }
+        });
+        this.child.stderr.on("data", () => { }); // the server's stderr is its own logging — never our stdout
+    }
+    onMessage(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return; // ignore anything that isn't valid JSON-RPC
+        }
+        const resolver = this.pending.get(msg.id);
+        if (resolver) {
+            this.pending.delete(msg.id);
+            resolver(msg);
+        }
+    }
+    request(payload, timeoutMs) {
+        const { id } = payload;
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (r) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.pending.delete(id);
+                resolve(r);
+            };
+            const timer = setTimeout(() => finish({ id, error: { message: `MCP request '${payload.method}' timed out` } }), timeoutMs);
+            this.pending.set(id, finish);
+            this.child.stdin.write(JSON.stringify(payload) + "\n"); // one line, newline-terminated
+        });
+    }
+    notify(method, params) {
+        this.child.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n");
+    }
+    close() {
+        this.child.kill(); // best-effort cleanup
+    }
+}
+// Pull JSON-RPC messages out of a Server-Sent-Events body. SSE frames are
+// separated by blank lines; the payload lives on one or more `data:` lines.
+// Exported because parsing is the fiddly part worth testing on its own.
+export function parseSseData(body) {
+    const out = [];
+    for (const frame of body.split(/\r?\n\r?\n/)) {
+        const data = frame
+            .split(/\r?\n/)
+            .filter((l) => l.startsWith("data:"))
+            .map((l) => l.slice(5).trim()) // strip "data:" and surrounding space
+            .join("\n");
+        if (data)
+            out.push(data);
+    }
+    return out;
+}
+// ---- HTTP transport: POST to a URL, read JSON or SSE back --------------------
+class HttpTransport {
+    url;
+    headers;
+    sessionId; // assigned by the server on initialize, echoed on every later request
+    constructor(def) {
+        this.url = def.url;
+        this.headers = { ...def.headers };
+    }
+    // The response to a POST may come back as a single JSON object OR as an SSE
+    // stream carrying it. Either way we want the JSON-RPC message matching our id.
+    async post(body, timeoutMs, isRequest) {
+        const res = await fetch(this.url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json, text/event-stream", // we accept either shape
+                ...(this.sessionId ? { "mcp-session-id": this.sessionId } : {}),
+                ...this.headers,
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const sid = res.headers.get("mcp-session-id"); // initialize hands us a session to keep
+        if (sid)
+            this.sessionId = sid;
+        if (!isRequest)
+            return null; // a notification expects no body (202 Accepted)
+        const raw = await res.text();
+        const payloads = res.headers.get("content-type")?.includes("text/event-stream") ? parseSseData(raw) : [raw];
+        for (const p of payloads) {
+            try {
+                const msg = JSON.parse(p);
+                if (msg && (msg.result !== undefined || msg.error !== undefined))
+                    return msg; // the response we came for
+            }
+            catch {
+                /* skip non-JSON frames (SSE comments, keep-alives) */
+            }
+        }
+        return null;
+    }
+    async request(payload, timeoutMs) {
+        try {
+            const msg = await this.post(payload, timeoutMs, true);
+            return msg ?? { id: payload.id, error: { message: `MCP request '${payload.method}' returned no response` } };
+        }
+        catch (err) {
+            return { id: payload.id, error: { message: `MCP HTTP request '${payload.method}' failed: ${err.message}` } };
+        }
+    }
+    notify(method, params) {
+        // Fire-and-forget; errors on a notification are not worth surfacing.
+        void this.post({ jsonrpc: "2.0", method, params }, INIT_TIMEOUT_MS, false).catch(() => { });
+    }
+    close() {
+        // Best-effort: tell the server to drop the session. No await, no error care.
+        if (this.sessionId) {
+            void fetch(this.url, { method: "DELETE", headers: { "mcp-session-id": this.sessionId, ...this.headers } }).catch(() => { });
+        }
+    }
+}
+// Choose the pipe from the config: a url means HTTP, otherwise spawn over stdio.
+function makeTransport(def) {
+    return def.url ? new HttpTransport(def) : new StdioTransport(def);
+}
+// The protocol layer: handshake, request ids, tool flattening. It talks to a
+// Transport and is blind to whether that's a subprocess or an HTTP endpoint.
+class McpClient {
+    transport;
+    nextId = 1; // JSON-RPC request id counter
+    constructor(def) {
+        this.transport = makeTransport(def);
+    }
+    request(method, params, timeoutMs) {
+        return this.transport.request({ jsonrpc: "2.0", id: this.nextId++, method, params }, timeoutMs);
+    }
+    // The MCP startup dance: initialize → initialized → list tools.
+    async start() {
+        const init = await this.request("initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "mini-agent", version: "0" } }, INIT_TIMEOUT_MS);
+        if (init.error)
+            throw new Error(init.error.message); // server refused to initialize
+        this.transport.notify("notifications/initialized", {}); // tell the server we're ready
+        const list = await this.request("tools/list", {}, INIT_TIMEOUT_MS); // ask what it offers
+        if (list.error)
+            throw new Error(list.error.message);
+        return list.result?.tools ?? [];
+    }
+    // Invoke one tool and flatten its content into plain text for the model.
+    async callTool(name, args) {
+        const res = await this.request("tools/call", { name, arguments: args }, CALL_TIMEOUT_MS);
+        if (res.error)
+            return `[error] MCP tool failed: ${res.error.message}`; // surface, don't throw
+        const text = (res.result?.content ?? []).map((c) => c.text ?? `[${c.type} content]`).join("\n"); // flatten parts
+        const body = text || "(no output)";
+        return res.result?.isError ? `[error] ${body}` : body; // MCP can flag a logical error in a successful response
+    }
+    kill() {
+        this.transport.close();
+    }
+}
+// Connect to every configured MCP server, register their tools, and return a
+// cleanup function. Failures are isolated: a server that won't start is logged
+// and skipped — it never stops the agent or the other servers.
+export async function connectMcpServers() {
+    const entries = Object.entries(CONFIG.mcpServers); // [name, def] pairs
+    if (!entries.length)
+        return () => { }; // the common case: nothing configured
+    const clients = []; // for cleanup
+    for (const [serverName, def] of entries) {
+        const client = new McpClient(def);
+        try {
+            const specs = await client.start(); // handshake + discover
+            clients.push(client);
+            for (const spec of specs) {
+                const toolName = `mcp__${serverName}__${spec.name}`; // namespaced, collision-proof
+                const tool = {
+                    definition: {
+                        type: "function",
+                        function: {
+                            name: toolName,
+                            description: `[MCP:${serverName}] ${spec.description ?? spec.name}`, // mark the origin in the manual
+                            parameters: spec.inputSchema ?? { type: "object", properties: {} }, // pass the server's schema straight through
+                        },
+                    },
+                    run: async (args) => client.callTool(spec.name, args), // dispatch routes here; the permission gate ran first
+                };
+                registerExternalTool(tool); // now indistinguishable from a built-in to the rest of the system
+            }
+            emit("agent_mcp_connected", { server: serverName, tools: specs.length, transport: def.url ? "http" : "stdio" });
+            console.log(chalk.dim(`(mcp: ${serverName} — ${specs.length} tools${def.url ? " over http" : ""})`)); // visible at startup
+        }
+        catch (err) {
+            client.kill(); // don't leak the process/session
+            emit("agent_mcp_failed", { server: serverName });
+            console.error(chalk.yellow(`  [mcp] ${serverName} failed to start (skipped): ${err.message}`)); // loud, but not fatal
+        }
+    }
+    return () => clients.forEach((c) => c.kill()); // the caller calls this on exit
+}

package/dist/memory.js

@@ -0,0 +1,186 @@
+import fs from "node:fs"; // memory lives in a file on disk
+import path from "node:path"; // path joining
+// Long-term memory: facts the agent should carry ACROSS sessions, not just
+// within one conversation. Session persistence (Day 12) restores "what we were
+// talking about"; this restores "what I should always know about this project".
+//
+// One Markdown file, project-local, human-readable and human-editable. Not a
+// vector database, not embeddings: a file you can open, read, and fix.
+//
+// Two ways facts get in: the model calls `remember` explicitly, OR — when
+// auto-extract is on — after each turn a cheap model call reads the conversation
+// and saves what's worth keeping (especially turns where the USER corrected the
+// assistant: 90% the model gets right isn't worth saving, the 10% it got wrong
+// and was corrected on is gold). Every fact is TYPED so the model can tell "this
+// is who the user is" from "this is a correction" from "this is a project fact".
+export const MEMORY_PATH = path.resolve(".mini-agent", "MEMORY.md");
+// The four memory types (handbook §17). feedback is the most valuable.
+export const MEMORY_TYPES = ["user", "feedback", "project", "reference"];
+// Bounds, because unbounded memory dilutes the model's attention (Ch6: too many
+// rules → worse compliance) and grows the cached prefix forever. On overflow we
+// drop the OLDEST — recent facts are likelier still true.
+const MAX_ENTRIES = 40; // at most this many remembered facts
+const MAX_BYTES = 12_000; // ...and at most this many bytes total
+const HEADER = "# mini-agent long-term memory\n# One fact per line: - [type] fact. Injected at session start. Edit freely.\n";
+// Coerce any string to a valid type, defaulting to "project".
+function asType(t) {
+    return MEMORY_TYPES.includes(t ?? "") ? t : "project";
+}
+// Parse one bullet's text into a typed entry. "[feedback] foo" → feedback; a
+// bare "foo" (legacy / hand-written) → project.
+function parseEntry(text) {
+    const m = text.match(/^\[(\w+)\]\s*(.*)$/);
+    if (m && MEMORY_TYPES.includes(m[1]))
+        return { type: m[1], fact: m[2].trim() };
+    return { type: "project", fact: text.trim() };
+}
+// Read facts WITH their types. The fiddly parsing lives here.
+export function readMemoryTyped() {
+    try {
+        return fs
+            .readFileSync(MEMORY_PATH, "utf8")
+            .split("\n")
+            .filter((l) => l.startsWith("- "))
+            .map((l) => parseEntry(l.slice(2).trim()))
+            .filter((e) => e.fact);
+    }
+    catch {
+        return []; // no memory file yet — fine
+    }
+}
+// Read just the fact text (no type). Kept for callers that only want the facts.
+export function readMemory() {
+    return readMemoryTyped().map((e) => e.fact);
+}
+// The block injected into the system message, grouped by type so the model can
+// weigh "a correction" differently from "a project fact". Empty when there's
+// nothing, so the cached prefix stays clean for projects that never use it.
+export function memoryContext() {
+    const entries = readMemoryTyped();
+    if (!entries.length)
+        return "";
+    const labels = {
+        user: "About the user",
+        feedback: "Guidance & corrections the user gave you (follow these)",
+        project: "Project facts & decisions",
+        reference: "References",
+    };
+    let out = "\n\nLong-term project memory (background from earlier sessions; verify against the code before relying on a specific claim):";
+    for (const type of MEMORY_TYPES) {
+        const group = entries.filter((e) => e.type === type);
+        if (group.length)
+            out += `\n[${labels[type]}]\n${group.map((e) => `- ${e.fact}`).join("\n")}`;
+    }
+    return out;
+}
+// Append a typed fact, then enforce the caps. Self-healing: every write re-applies
+// the bounds, so the file can never grow past them even if hand-edited huge.
+export function addFact(fact, type = "project") {
+    const clean = fact.replace(/\s+/g, " ").trim(); // one line, normalized whitespace
+    if (!clean)
+        return "[error] nothing to remember (empty fact).";
+    const t = asType(type); // coerce a bad type to "project" so the on-disk format stays parseable
+    let entries = readMemoryTyped();
+    if (entries.some((e) => e.fact === clean))
+        return "Already remembered — no change."; // idempotent
+    entries.push({ type: t, fact: clean });
+    if (entries.length > MAX_ENTRIES)
+        entries = entries.slice(entries.length - MAX_ENTRIES); // drop oldest
+    let body = entries.map((e) => `- [${e.type}] ${e.fact}`).join("\n");
+    while (Buffer.byteLength(HEADER + body, "utf8") > MAX_BYTES && entries.length > 1) {
+        entries.shift(); // still too big — drop the oldest until it fits
+        body = entries.map((e) => `- [${e.type}] ${e.fact}`).join("\n");
+    }
+    fs.mkdirSync(path.dirname(MEMORY_PATH), { recursive: true });
+    fs.writeFileSync(MEMORY_PATH, HEADER + body + "\n", "utf8");
+    return `Remembered (${t}). (${entries.length} fact${entries.length === 1 ? "" : "s"} stored.)`;
+}
+// The tool the model calls to save something worth keeping.
+export const rememberTool = {
+    definition: {
+        type: "function",
+        function: {
+            name: "remember",
+            description: `Save a durable fact to long-term memory (persists across sessions, shown to you at the start of every future session).
+Use it for things still true next time: the build/test command, a gotcha, a convention, a decision and its reason, a user preference, or a correction the user gave you.
+Do NOT use it for transient state (current task, today's bug). Keep each fact to one sentence. Pick the right "type".`,
+            parameters: {
+                type: "object",
+                properties: {
+                    fact: { type: "string", description: "One durable fact, as a single sentence" },
+                    type: { type: "string", enum: [...MEMORY_TYPES], description: "user (who they are/prefs) · feedback (a correction/guidance) · project (a decision/convention/gotcha) · reference (a URL/doc)" },
+                },
+                required: ["fact"],
+            },
+        },
+    },
+    run: (args) => addFact(args.fact ?? "", asType(args.type)),
+};
+// ---- auto-extract -----------------------------------------------------------
+// After a turn, read the conversation and save what's worth keeping. The high-
+// frequency write path from §17 — so memory captures itself instead of relying
+// on the model to remember to call `remember`.
+const EXTRACT_SYSTEM = `You extract DURABLE memories from a slice of a coding-assistant conversation — facts worth carrying into FUTURE sessions.
+Output ONLY a JSON array. Each item: {"type": "...", "fact": "one sentence"}. No prose, no markdown fences.
+"type" is one of:
+- "user": who the user is — role, preferences, how they like to work.
+- "feedback": guidance or a CORRECTION the user gave the assistant. These are the MOST valuable — prioritize any turn where the user corrected or redirected the assistant.
+- "project": a goal, decision, convention, or non-obvious gotcha about THIS project.
+- "reference": a pointer to an external resource (a URL, a doc, a ticket).
+Do NOT save: transient task state, the bug currently being fixed, or anything obvious from reading the code. Keep each fact to one sentence.
+If nothing is worth saving, output [].`;
+// Parse the model's extraction output into typed entries. Lenient: finds the
+// JSON array even if wrapped in prose/fences, drops malformed items. Pure.
+export function parseExtractedMemories(text) {
+    const m = text.match(/\[[\s\S]*\]/); // the first […] — tolerate surrounding chatter
+    if (!m)
+        return [];
+    let arr;
+    try {
+        arr = JSON.parse(m[0]);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(arr))
+        return [];
+    return arr
+        .filter((x) => !!x && typeof x === "object")
+        .filter((x) => typeof x.fact === "string" && x.fact.trim())
+        .map((x) => ({ type: asType(x.type), fact: String(x.fact).replace(/\s+/g, " ").trim() }));
+}
+// Build the transcript handed to the extractor: the last few user/assistant
+// turns (string content only), each capped, so the extraction stays cheap.
+function buildTranscript(messages) {
+    const turns = messages
+        .filter((m) => (m.role === "user" || m.role === "assistant") && typeof m.content === "string" && m.content.trim())
+        .slice(-12) // recent context is what matters
+        .map((m) => `${m.role}: ${String(m.content).split("\n\n[Referenced files")[0].slice(0, 600)}`);
+    return turns.join("\n\n");
+}
+// Run one extraction pass: a single (cheap) model call, parse, save. Returns the
+// facts it saved. Never throws — a failed extraction must not break the session.
+export async function extractMemories(client, model, messages) {
+    const transcript = buildTranscript(messages);
+    if (!transcript.trim())
+        return [];
+    let text = "";
+    try {
+        const res = await client.chat.completions.create({
+            model,
+            messages: [
+                { role: "system", content: EXTRACT_SYSTEM },
+                { role: "user", content: transcript },
+            ],
+            stream: false,
+        });
+        text = res.choices?.[0]?.message?.content ?? "";
+    }
+    catch {
+        return []; // network/model error — skip silently, try again next turn
+    }
+    const extracted = parseExtractedMemories(text);
+    for (const e of extracted)
+        addFact(e.fact, e.type); // addFact dedups internally
+    return extracted;
+}

package/dist/mentions.js

@@ -0,0 +1,62 @@
+import fs from "node:fs"; // read referenced files
+import path from "node:path"; // resolve mention paths
+import { checkPermission } from "./permissions.js"; // reuse the read_file gate — secret files must never leak in
+// @file mentions: let the user pull a file into the conversation just by naming
+// it — "explain @src/loop.ts" attaches the file's content so the model sees it
+// without a separate read_file round-trip. The point is convenience, but the
+// SAME rule still holds: a secret file (.env, *.pem) must never enter the
+// context. So every mention is routed through the read_file permission gate
+// (Day 4) — if it would deny a read, the mention is refused, not read.
+// @ must start the token (line start or after whitespace) so emails (a@b) and
+// npm scopes inside words don't trigger. The path runs to the next space; we
+// trim trailing sentence punctuation so "see @cart.js." doesn't include the dot.
+const MENTION_RE = /(?:^|\s)@(\S+)/g;
+const MAX_MENTION_BYTES = 100_000; // a referenced file bigger than this is truncated
+// Pull the raw @tokens out of a line (trailing , ; : ! ? ) stripped).
+export function findMentions(line) {
+    const out = [];
+    for (const m of line.matchAll(MENTION_RE)) {
+        const raw = m[1].replace(/[.,;:!?)\]]+$/, ""); // drop trailing punctuation, keep inner dots (cart.js)
+        if (raw)
+            out.push(raw);
+    }
+    return out;
+}
+// Resolve one mention to a file we may attach. Never throws.
+function resolveMention(raw) {
+    const abs = path.resolve(raw);
+    // The gate decides if a read is allowed; a secret file comes back "deny".
+    if (checkPermission("read_file", JSON.stringify({ path: raw })).decision === "deny") {
+        return { raw, path: abs, status: "denied" };
+    }
+    try {
+        const stat = fs.statSync(abs);
+        if (stat.isDirectory())
+            return { raw, path: abs, status: "dir" };
+        let content = fs.readFileSync(abs, "utf8");
+        if (content.length > MAX_MENTION_BYTES)
+            content = content.slice(0, MAX_MENTION_BYTES) + `\n... (truncated, file is ${content.length} chars)`;
+        return { raw, path: abs, status: "ok", content };
+    }
+    catch {
+        return { raw, path: abs, status: "missing" }; // not a file — probably not a reference at all
+    }
+}
+// Expand a user line: find @mentions, attach the readable ones, and refuse the
+// secret ones out loud. Returns the augmented message (file blocks appended) and
+// the mention list (for the REPL to summarize). A line with no resolvable
+// mention is returned unchanged — @tokens that don't name a real file (an email,
+// a stray @) are ignored silently so we don't nag on every "@" in prose.
+export function expandMentions(line) {
+    const mentions = findMentions(line).map(resolveMention);
+    // Only attach files we actually read, and announce refusals (security-relevant).
+    // "missing"/"dir" are dropped silently — likely not file references.
+    const attach = mentions.filter((m) => m.status === "ok" || m.status === "denied");
+    if (!attach.length)
+        return { augmented: line, mentions };
+    const blocks = attach.map((m) => m.status === "ok"
+        ? `--- ${m.raw} ---\n${m.content}`
+        : `--- ${m.raw} (refused: secret file, not included) ---`);
+    const augmented = `${line}\n\n[Referenced files — the user attached these with @mentions]\n${blocks.join("\n\n")}`;
+    return { augmented, mentions };
+}