vaan-ai 0.1.0

package/dist/src/index.js

@@ -0,0 +1,180 @@
+// The agent runtime. Everything that knows about everything else lives here,
+// so the pieces underneath don't have to know about each other.
+//
+// The shape worth noticing is which way the arrows point. The runtime builds
+// the policy, the gate and the trace, and hands tools a context that can *ask*
+// for permission. It never hands them the thing that answers. The approver is a
+// function the CLI closed over a terminal, and it stays in this file's closure
+// — that is the mechanical reason the model cannot approve its own actions,
+// rather than an instruction somewhere asking it not to.
+//
+// This is internal. Vaan ships as an agent, not a library — package.json
+// exports nothing but itself, so importing "vaan" fails cleanly rather than
+// half-working against interfaces that are still moving.
+import { continueAgent } from "./agent.js";
+import { defaultConfig } from "./config.js";
+import { noMemory } from "./memory/index.js";
+import { needsMemory } from "./memory/context.js";
+import { openMemory } from "./memory/store.js";
+import { newRequest } from "./observability/request.js";
+import { openTrace } from "./observability/trace.js";
+import { approveAll, createGate, denyAll } from "./permissions/approval.js";
+import { createPolicy } from "./permissions/policy.js";
+import { home } from "./paths.js";
+import { buildSystemPrompt, loadPersona } from "./prompt.js";
+import { resolve } from "./providers/index.js";
+import { loadSkills } from "./skills.js";
+import { builtinTools } from "./tools/index.js";
+import { scrubEnv } from "./sandbox/process.js";
+/** Rough cap on in-process history, trimmed whole rounds at a time. */
+const MAX_HISTORY = 40;
+export function createSession(opts) {
+    const env = opts.env ?? process.env;
+    const workspace = opts.workspace;
+    const config = opts.config ?? defaultConfig(workspace, opts.model);
+    const { provider, model } = resolve(opts.model, env);
+    const memoryOn = opts.memory ?? config.memory;
+    const memory = memoryOn ? openMemory({ dir: workspace }) : noMemory;
+    const persona = loadPersona(workspace);
+    const { skills, warnings: skillWarnings } = loadSkills(workspace);
+    const policy = createPolicy({ workspace, approvals: config.approvals });
+    // The gate lives for the session so that "yes, run npm test" holds for the
+    // session. The trace it writes to changes every request, hence the accessor.
+    let current;
+    const gate = createGate({
+        policy,
+        approve: opts.yes ? approveAll : (opts.approve ?? denyAll),
+        trace: () => current,
+        memoise: !config.sandbox.confirmEveryCommand,
+    });
+    const tools = builtinTools({
+        groups: config.tools,
+        ...(opts.search ? { search: opts.search } : {}),
+    });
+    // Credentials are stripped once, here, rather than at each spawn: the child
+    // environment is a property of the session, not of the command.
+    const childEnv = scrubEnv(env);
+    // The retrieval gate runs on every turn, so it's worth pointing at something
+    // cheap. Unrelated to the permission gate, which shares nothing but the word.
+    const recallModel = env.VAAN_GATE_MODEL ? resolve(env.VAAN_GATE_MODEL, env) : { provider, model };
+    let history = [];
+    const usage = { input: 0, output: 0 };
+    return {
+        model: opts.model,
+        provider,
+        memory,
+        tools,
+        config,
+        policy,
+        usage,
+        warnings: [...persona.warnings, ...skillWarnings],
+        async ask(input, handlers = {}) {
+            const request = newRequest(input, opts.model, workspace);
+            handlers.onRequest?.(request);
+            // Events are always collected — the eval graders read them — but only
+            // written to disk when tracing is on.
+            const trace = openTrace({
+                home: home(workspace),
+                request,
+                persist: opts.trace !== false,
+            });
+            current = trace;
+            const ctx = {
+                workspace,
+                gate,
+                policy,
+                trace,
+                network: config.network,
+                confirm: opts.yes ? async () => true : (opts.confirm ?? (async () => false)),
+                remember: async (fact) => memory.remember(workspace, { kind: "fact", text: fact, source: "tool" }),
+                env: childEnv,
+                ...(handlers.signal ? { signal: handlers.signal } : {}),
+            };
+            try {
+                const wanted = await needsMemory(input, {
+                    provider: recallModel.provider,
+                    model: recallModel.model,
+                    ...(handlers.signal ? { signal: handlers.signal } : {}),
+                });
+                handlers.onRecall?.(wanted);
+                trace.record({
+                    kind: "memory",
+                    op: wanted ? "recall" : "skipped",
+                    detail: wanted ? input : "the question stands on its own",
+                });
+                // Facts come back either way — they're injected, not searched, and the
+                // gate only decides whether to spend a query on past turns.
+                const recalled = await memory.recall(workspace, wanted ? input : "");
+                const system = buildSystemPrompt({
+                    workspace,
+                    agentName: config.agentName,
+                    persona,
+                    facts: recalled.facts,
+                    turns: wanted ? recalled.turns : [],
+                    skills,
+                    toolNames: tools.map((tool) => tool.name),
+                });
+                history = trim([
+                    ...history,
+                    { role: "user", parts: [{ type: "text", text: input }] },
+                ]);
+                const result = await continueAgent(history, {
+                    provider,
+                    model,
+                    system,
+                    tools,
+                    ctx,
+                    trace,
+                    ...(opts.stream ? { stream: true } : {}),
+                    ...(handlers.onEvent ? { onEvent: handlers.onEvent } : {}),
+                    ...(handlers.signal ? { signal: handlers.signal } : {}),
+                });
+                history = result.messages;
+                if (result.usage) {
+                    usage.input += result.usage.input;
+                    usage.output += result.usage.output;
+                }
+                await memory.remember(workspace, {
+                    kind: "turn",
+                    userText: input,
+                    replyText: result.text,
+                    tools: result.usedTools,
+                });
+                const stored = trace.finish(true, result.text);
+                return { ...result, requestId: request.id, trace: stored };
+            }
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                trace.record({ kind: "error", where: "runtime", message: detail });
+                trace.finish(false, detail);
+                throw err;
+            }
+            finally {
+                current = undefined;
+            }
+        },
+        reset() {
+            history = [];
+        },
+        close() {
+            memory.close?.();
+        },
+    };
+}
+/**
+ * Keep the transcript from growing without limit, dropping whole rounds from
+ * the front. Trimming at an arbitrary index would orphan a tool_result from its
+ * tool_call, which providers reject — so cuts only happen at a plain user turn.
+ */
+function trim(messages) {
+    if (messages.length <= MAX_HISTORY)
+        return messages;
+    for (let index = messages.length - MAX_HISTORY; index < messages.length; index++) {
+        const message = messages[index];
+        if (message?.role === "user" && message.parts.every((part) => part.type === "text")) {
+            return messages.slice(index);
+        }
+    }
+    return messages;
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

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

package/dist/src/memory/context.js

@@ -0,0 +1,63 @@
+// What memory actually contributes to a turn: the gate that decides whether to
+// look, and the shape recalled memory takes once it's in the prompt.
+//
+// The gate is the most visible thing Vaan does. Before touching memory, one
+// cheap call answers one question: does answering this need anything we've been
+// told? "What's 2+2" doesn't. "When am I seeing Alex" does. Skipping the search
+// on the first kind keeps the prompt small and the turn fast.
+//
+// It fails open. If the gate errors, times out, or answers something we can't
+// read, we retrieve — a slightly larger prompt is a much smaller problem than an
+// agent that forgot you.
+const GATE_SYSTEM = `You decide whether answering a message needs the user's stored memory.
+
+Reply with exactly one word: YES or NO.
+
+YES when the message touches the user themselves — their history, preferences,
+plans, people, projects, or anything they would have had to tell you.
+NO when the message stands on its own: arithmetic, general knowledge, a
+definition, a translation, or writing something from scratch.`;
+export async function needsMemory(message, opts) {
+    try {
+        const reply = await opts.provider.generate({
+            model: opts.model,
+            system: GATE_SYSTEM,
+            messages: [{ role: "user", parts: [{ type: "text", text: message }] }],
+            tools: [],
+            maxTokens: 8,
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        });
+        const answer = reply.message.parts
+            .map((part) => (part.type === "text" ? part.text : ""))
+            .join("")
+            .trim()
+            .toUpperCase();
+        return !answer.startsWith("NO");
+    }
+    catch {
+        return true;
+    }
+}
+/** Facts are injected, not searched, so they carry their own framing. */
+export function factsSection(facts) {
+    if (facts.length === 0)
+        return undefined;
+    return (`# What you know about this user\n\n` +
+        `Things they've told you in past sessions. Use them without being asked, and without\n` +
+        `announcing that you remembered.\n\n` +
+        facts.map((fact) => `- ${fact.text}`).join("\n"));
+}
+/** Recalled turns are retrieved, so they say so — retrieval can and does miss. */
+export function turnsSection(turns) {
+    if (turns.length === 0)
+        return undefined;
+    return (`# Relevant past conversation\n\n` +
+        `Retrieved because it looked related to what was just asked. It may not be.\n\n` +
+        turns.map(formatTurn).join("\n\n"));
+}
+const TURN_CLIP = 500;
+const formatTurn = (turn) => `[${turn.ts.slice(0, 10)}]\n` +
+    `user: ${clip(turn.userText, TURN_CLIP)}\n` +
+    `you: ${clip(turn.replyText, TURN_CLIP)}`;
+const clip = (text, max) => text.length <= max ? text : `${text.slice(0, max)}…`;
+//# sourceMappingURL=context.js.map

package/dist/src/memory/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/memory/context.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,qEAAqE;AACrE,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;AAChF,gFAAgF;AAChF,8DAA8D;AAC9D,EAAE;AACF,8EAA8E;AAC9E,iFAAiF;AACjF,yBAAyB;AAKzB,MAAM,WAAW,GAAG;;;;;;;8DAO0C,CAAC;AAQ/D,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAe,EAAE,IAAiB;IAClE,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;YACzC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,WAAW;YACnB,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;YACtE,KAAK,EAAE,EAAE;YACT,SAAS,EAAE,CAAC;YACZ,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK;aAC/B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;aACtD,IAAI,CAAC,EAAE,CAAC;aACR,IAAI,EAAE;aACN,WAAW,EAAE,CAAC;QACjB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,OAAO,CACL,qCAAqC;QACrC,uFAAuF;QACvF,qCAAqC;QACrC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CACjD,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,OAAO,CACL,kCAAkC;QAClC,gFAAgF;QAChF,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CACnC,CAAC;AACJ,CAAC;AAED,MAAM,SAAS,GAAG,GAAG,CAAC;AAEtB,MAAM,UAAU,GAAG,CAAC,IAAU,EAAU,EAAE,CACxC,IAAI,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK;IAC7B,SAAS,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI;IAC3C,QAAQ,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;AAE5C,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,GAAW,EAAU,EAAE,CACjD,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC"}

package/dist/src/memory/index.js

@@ -0,0 +1,28 @@
+// Two tiers, and the difference is the whole design.
+//
+// Facts are short statements about the user. They go into the system prompt on
+// every turn, so they work even when the question doesn't mention them.
+// "Allergic to prawns" has to surface when you ask what to order, not only
+// when you say the word prawn.
+//
+// Turns are past conversations, searched full-text and ranked against whatever
+// you just asked. Only the relevant ones come back.
+//
+// Why both: retrieval can miss, injection can't. Injection is paid on every
+// turn, so the facts tier stays small on purpose.
+export const EMPTY_RECALL = { facts: [], turns: [] };
+/**
+ * A memory that remembers nothing, for `--no-memory` and for tests. Keeping the
+ * null case behind the same interface means nothing downstream needs to ask
+ * whether memory is on.
+ */
+export const noMemory = {
+    async recall() {
+        return EMPTY_RECALL;
+    },
+    async remember() { },
+    async forget() {
+        return 0;
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/src/memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/memory/index.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,EAAE;AACF,+EAA+E;AAC/E,wEAAwE;AACxE,2EAA2E;AAC3E,+BAA+B;AAC/B,EAAE;AACF,+EAA+E;AAC/E,oDAAoD;AACpD,EAAE;AACF,4EAA4E;AAC5E,kDAAkD;AAwClD,MAAM,CAAC,MAAM,YAAY,GAAW,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAE7D;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAW;IAC9B,KAAK,CAAC,MAAM;QACV,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,KAAK,CAAC,QAAQ,KAAI,CAAC;IACnB,KAAK,CAAC,MAAM;QACV,OAAO,CAAC,CAAC;IACX,CAAC;CACF,CAAC"}

package/dist/src/memory/search.js

@@ -0,0 +1,32 @@
+// Turning a sentence into something FTS5 will accept.
+//
+// This is separated from the store because it is the part with no I/O in it and
+// the part most likely to be wrong: user text goes straight into query syntax,
+// where a stray quote or the bare word "AND" is a syntax error rather than a
+// search term.
+/** Words too common to be worth a BM25 term. Short list on purpose. */
+export const STOPWORDS = new Set(("the a an and or but if then than that this these those is are was were be been being do does did " +
+    "for to of in on at by with from about into over after before you your my me i it its as what when " +
+    "where who how why can could should would will just have has had not no yes please").split(" "));
+/** Terms past this add noise rather than signal, and cost query time. */
+const MAX_TERMS = 12;
+const MIN_TERM_LENGTH = 3;
+/**
+ * An FTS5 MATCH expression, or undefined when there's nothing worth searching.
+ *
+ * Reducing to alphanumeric words and quoting each one sidesteps the whole
+ * grammar: no operator can survive the reduction, so no input can be a syntax
+ * error, and `OR` between terms lets BM25 rank rather than filter.
+ */
+export function toMatchQuery(text) {
+    const useful = terms(text);
+    return useful.length > 0 ? useful.map((word) => `"${word}"`).join(" OR ") : undefined;
+}
+/** The words a query actually searches on. Exposed so tests can assert on them. */
+export function terms(text) {
+    const words = text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+    return words
+        .filter((word) => word.length >= MIN_TERM_LENGTH && !STOPWORDS.has(word))
+        .slice(0, MAX_TERMS);
+}
+//# sourceMappingURL=search.js.map

package/dist/src/memory/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../src/memory/search.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,6EAA6E;AAC7E,eAAe;AAEf,uEAAuE;AACvE,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,GAAG,CAC9B,CAAC,mGAAmG;IAClG,oGAAoG;IACpG,mFAAmF,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAClG,CAAC;AAEF,yEAAyE;AACzE,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACxF,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,KAAK,CAAC,IAAY;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC;IAChE,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,IAAI,eAAe,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;SACxE,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;AACzB,CAAC"}

package/dist/src/memory/store.js

@@ -0,0 +1,171 @@
+// SQLite with FTS5, at .vaan/memory/state.db.
+//
+// Why a native dependency rather than a flat file: ranked retrieval needs real
+// BM25 scoring, and Node's built-in node:sqlite ships compiled *without* FTS5
+// (nodejs/node#56951), so `CREATE VIRTUAL TABLE … USING fts5` throws there.
+// better-sqlite3 bundles its own SQLite with FTS5 enabled. The alternative was
+// hand-rolling TF-IDF over JSON files, which we'd then own and get subtly wrong.
+//
+// Nothing in here is allowed to throw. A corrupt database, a locked file, a
+// disk that filled up — none of that should stop the agent answering. Every
+// public method falls back to "no memory" and warns once.
+import Database from "better-sqlite3";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { databaseFile, memoryDir, memoryMirror } from "../paths.js";
+import { EMPTY_RECALL, } from "./index.js";
+import { toMatchQuery } from "./search.js";
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS turns (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  scope      TEXT NOT NULL,
+  ts         TEXT NOT NULL,
+  user_text  TEXT NOT NULL,
+  reply_text TEXT NOT NULL,
+  tools_json TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS turns_by_scope ON turns(scope, id DESC);
+
+CREATE TABLE IF NOT EXISTS facts (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  scope      TEXT NOT NULL,
+  text       TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  source     TEXT NOT NULL,
+  UNIQUE(scope, text)
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS turns_fts USING fts5(user_text, reply_text);
+`;
+/**
+ * Confirm this build of SQLite actually has FTS5. Returns the failure message,
+ * or undefined when all is well. The postinstall script runs the same check;
+ * the onboarding runs it again because a working install can still be moved to
+ * a machine whose native module doesn't load.
+ */
+export function probeFts5() {
+    try {
+        const db = new Database(":memory:");
+        db.exec("CREATE VIRTUAL TABLE probe USING fts5(x)");
+        db.close();
+        return undefined;
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
+    }
+}
+export function openMemory(opts) {
+    const turnLimit = opts.turnLimit ?? 5;
+    const factLimit = opts.factLimit ?? 64;
+    mkdirSync(memoryDir(opts.dir), { recursive: true });
+    const db = new Database(databaseFile(opts.dir));
+    db.pragma("journal_mode = WAL");
+    db.exec(SCHEMA);
+    const statements = {
+        facts: db.prepare("SELECT id, text, created_at, source FROM facts WHERE scope = ? ORDER BY id LIMIT ?"),
+        insertFact: db.prepare("INSERT OR IGNORE INTO facts (scope, text, created_at, source) VALUES (?, ?, ?, ?)"),
+        deleteFact: db.prepare("DELETE FROM facts WHERE scope = ? AND id = ?"),
+        insertTurn: db.prepare("INSERT INTO turns (scope, ts, user_text, reply_text, tools_json) VALUES (?, ?, ?, ?, ?)"),
+        indexTurn: db.prepare("INSERT INTO turns_fts (rowid, user_text, reply_text) VALUES (?, ?, ?)"),
+        recent: db.prepare("SELECT id, ts, user_text, reply_text, tools_json FROM turns WHERE scope = ? ORDER BY id DESC LIMIT ?"),
+        search: db.prepare(`SELECT t.id, t.ts, t.user_text, t.reply_text, t.tools_json
+         FROM turns_fts f JOIN turns t ON t.id = f.rowid
+        WHERE turns_fts MATCH ? AND t.scope = ?
+        ORDER BY bm25(turns_fts) LIMIT ?`),
+    };
+    const readFacts = (scope) => statements.facts.all(scope, factLimit).map(toFact);
+    function mirror(scope) {
+        // The database is authoritative. This file is for humans, and is
+        // regenerated from the facts table every time they change.
+        const facts = readFacts(scope);
+        const lines = [
+            "# MEMORY.md",
+            "",
+            "<!-- Generated by Vaan from .vaan/memory/state.db. Edits here are overwritten.",
+            "     To remove a fact, use /forget in the REPL. -->",
+            "",
+            ...(facts.length === 0
+                ? ["_Nothing remembered yet._"]
+                : facts.map((fact) => `- ${fact.text}  \`#${fact.id}\``)),
+            "",
+        ];
+        writeFileSync(memoryMirror(opts.dir), lines.join("\n"), "utf8");
+    }
+    return {
+        async recall(scope, query) {
+            return guard(EMPTY_RECALL, () => {
+                const facts = readFacts(scope);
+                const match = toMatchQuery(query);
+                const rows = match
+                    ? statements.search.all(match, scope, turnLimit)
+                    : statements.recent.all(scope, turnLimit);
+                return { facts, turns: rows.map(toTurn) };
+            });
+        },
+        async remember(scope, item) {
+            return guard(undefined, () => {
+                if (item.kind === "fact") {
+                    const text = item.text.trim();
+                    if (!text)
+                        return;
+                    statements.insertFact.run(scope, text, new Date().toISOString(), item.source ?? "tool");
+                    mirror(scope);
+                    return;
+                }
+                const result = statements.insertTurn.run(scope, new Date().toISOString(), item.userText, item.replyText, JSON.stringify(item.tools));
+                statements.indexTurn.run(result.lastInsertRowid, item.userText, item.replyText);
+            });
+        },
+        async forget(scope, factId) {
+            return guard(0, () => {
+                const removed = statements.deleteFact.run(scope, factId).changes;
+                if (removed > 0)
+                    mirror(scope);
+                return removed;
+            });
+        },
+        close() {
+            guard(undefined, () => db.close());
+        },
+    };
+}
+const toFact = (row) => ({
+    id: row.id,
+    text: row.text,
+    createdAt: row.created_at,
+    source: row.source,
+});
+const toTurn = (row) => ({
+    id: row.id,
+    ts: row.ts,
+    userText: row.user_text,
+    replyText: row.reply_text,
+    tools: parseTools(row.tools_json),
+});
+function parseTools(json) {
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed)
+            ? parsed.filter((item) => typeof item === "string")
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+let warned = false;
+/** Run `fn`, and on any failure warn once and hand back `fallback`. */
+function guard(fallback, fn) {
+    try {
+        return fn();
+    }
+    catch (err) {
+        if (!warned) {
+            warned = true;
+            const detail = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`vaan: memory is unavailable (${detail}). Continuing without it.\n`);
+        }
+        return fallback;
+    }
+}
+export { toMatchQuery };
+//# sourceMappingURL=store.js.map

package/dist/src/memory/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/memory/store.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,4EAA4E;AAC5E,+EAA+E;AAC/E,iFAAiF;AACjF,EAAE;AACF,4EAA4E;AAC5E,4EAA4E;AAC5E,0DAA0D;AAE1D,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EACL,YAAY,GAMb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;CAqBd,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,UAAU,CAAC,CAAC;QACpC,EAAE,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;QACpD,EAAE,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAC;IACnB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AASD,MAAM,UAAU,UAAU,CAAC,IAAmB;IAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;IAEvC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAChC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAEhB,MAAM,UAAU,GAAG;QACjB,KAAK,EAAE,EAAE,CAAC,OAAO,CACf,oFAAoF,CACrF;QACD,UAAU,EAAE,EAAE,CAAC,OAAO,CACpB,mFAAmF,CACpF;QACD,UAAU,EAAE,EAAE,CAAC,OAAO,CAAC,8CAA8C,CAAC;QACtE,UAAU,EAAE,EAAE,CAAC,OAAO,CACpB,yFAAyF,CAC1F;QACD,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,uEAAuE,CAAC;QAC9F,MAAM,EAAE,EAAE,CAAC,OAAO,CAChB,sGAAsG,CACvG;QACD,MAAM,EAAE,EAAE,CAAC,OAAO,CAChB;;;yCAGmC,CACpC;KACF,CAAC;IAEF,MAAM,SAAS,GAAG,CAAC,KAAa,EAAU,EAAE,CACzC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAe,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAEpE,SAAS,MAAM,CAAC,KAAa;QAC3B,iEAAiE;QACjE,2DAA2D;QAC3D,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QAC/B,MAAM,KAAK,GAAG;YACZ,aAAa;YACb,EAAE;YACF,gFAAgF;YAChF,qDAAqD;YACrD,EAAE;YACF,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;gBACpB,CAAC,CAAC,CAAC,2BAA2B,CAAC;gBAC/B,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;YAC3D,EAAE;SACH,CAAC;QACF,aAAa,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;IAClE,CAAC;IAED,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK;YACvB,OAAO,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE;gBAC9B,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;gBAC/B,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;gBAClC,MAAM,IAAI,GAAG,KAAK;oBAChB,CAAC,CAAE,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAe;oBAC/D,CAAC,CAAE,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAe,CAAC;gBAC3D,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5C,CAAC,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI;YACxB,OAAO,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE;gBAC3B,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;oBACzB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;oBAC9B,IAAI,CAAC,IAAI;wBAAE,OAAO;oBAClB,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,CAAC;oBACxF,MAAM,CAAC,KAAK,CAAC,CAAC;oBACd,OAAO;gBACT,CAAC;gBACD,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,GAAG,CACtC,KAAK,EACL,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EACxB,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,SAAS,EACd,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAC3B,CAAC;gBACF,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;YAClF,CAAC,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM;YACxB,OAAO,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE;gBACnB,MAAM,OAAO,GAAG,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC;gBACjE,IAAI,OAAO,GAAG,CAAC;oBAAE,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC/B,OAAO,OAAO,CAAC;YACjB,CAAC,CAAC,CAAC;QACL,CAAC;QAED,KAAK;YACH,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC;QACrC,CAAC;KACF,CAAC;AACJ,CAAC;AAiBD,MAAM,MAAM,GAAG,CAAC,GAAY,EAAQ,EAAE,CAAC,CAAC;IACtC,EAAE,EAAE,GAAG,CAAC,EAAE;IACV,IAAI,EAAE,GAAG,CAAC,IAAI;IACd,SAAS,EAAE,GAAG,CAAC,UAAU;IACzB,MAAM,EAAE,GAAG,CAAC,MAAM;CACnB,CAAC,CAAC;AAEH,MAAM,MAAM,GAAG,CAAC,GAAY,EAAQ,EAAE,CAAC,CAAC;IACtC,EAAE,EAAE,GAAG,CAAC,EAAE;IACV,EAAE,EAAE,GAAG,CAAC,EAAE;IACV,QAAQ,EAAE,GAAG,CAAC,SAAS;IACvB,SAAS,EAAE,GAAG,CAAC,UAAU;IACzB,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC;CAClC,CAAC,CAAC;AAEH,SAAS,UAAU,CAAC,IAAY;IAC9B,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAC1B,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC;YACnE,CAAC,CAAC,EAAE,CAAC;IACT,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,IAAI,MAAM,GAAG,KAAK,CAAC;AAEnB,uEAAuE;AACvE,SAAS,KAAK,CAAI,QAAW,EAAE,EAAW;IACxC,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,IAAI,CAAC;YACd,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,MAAM,6BAA6B,CAAC,CAAC;QAC5F,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/src/observability/events.js

@@ -0,0 +1,109 @@
+// The event taxonomy, and the redactor.
+//
+// This module is a leaf on purpose: permissions, the sandbox, the providers and
+// the loop all emit into it, so it must not import any of them. Events are
+// plain data with string discriminants for exactly that reason.
+//
+// Nothing here is allowed to record a credential. `redact` runs over every
+// payload on the way in, not on the way out, so a secret is never written to
+// disk in the first place — a trace file that has to be sanitised later is a
+// trace file that already leaked.
+/** Field names whose value is a secret whatever it looks like. */
+const SECRET_KEYS = /^(?:.*_)?(?:api[-_]?key|apikey|authorization|auth|token|access[-_]?token|refresh[-_]?token|secret|password|passwd|credential|credentials|cookie|session|private[-_]?key)$/i;
+/** Shapes that are a secret whatever they're called. */
+const SECRET_VALUES = [
+    /\bsk-[A-Za-z0-9_-]{16,}/g, // OpenAI, Anthropic
+    /\bsk-ant-[A-Za-z0-9_-]{16,}/g,
+    /\bgh[pousr]_[A-Za-z0-9]{20,}/g, // GitHub
+    /\bAKIA[0-9A-Z]{16}\b/g, // AWS access key id
+    /\bAIza[0-9A-Za-z_-]{30,}\b/g, // Google
+    /\bxox[abprs]-[A-Za-z0-9-]{10,}/g, // Slack
+    /\bBearer\s+[A-Za-z0-9._~+/-]{20,}=*/gi,
+    /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g, // JWT
+];
+export const REDACTED = "[redacted]";
+/** Strip anything that looks like a credential out of a string. */
+export function redactText(text) {
+    let out = text;
+    for (const pattern of SECRET_VALUES)
+        out = out.replace(pattern, REDACTED);
+    return out;
+}
+/**
+ * Deep-copy `value` with every secret removed: keys whose *name* marks them
+ * secret lose their value entirely, and every remaining string is scanned for
+ * secret-shaped substrings. Cycles are cut rather than followed.
+ */
+export function redact(value, seen = new WeakSet()) {
+    if (typeof value === "string")
+        return redactText(value);
+    if (value === null || typeof value !== "object")
+        return value;
+    if (seen.has(value))
+        return "[circular]";
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.map((item) => redact(item, seen));
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        out[key] = SECRET_KEYS.test(key) ? REDACTED : redact(item, seen);
+    }
+    return out;
+}
+/** Redact an event's free-form payload. Called once, as the event is recorded. */
+export function redactEvent(event) {
+    switch (event.kind) {
+        case "tool_call":
+            return { ...event, input: redact(event.input) };
+        case "request":
+            return { ...event, input: redactText(event.input) };
+        case "tool_result":
+            return { ...event, summary: redactText(event.summary) };
+        case "result":
+            return { ...event, summary: redactText(event.summary) };
+        case "error":
+            return { ...event, message: redactText(event.message) };
+        case "permission":
+            return { ...event, target: redactText(event.target), reason: redactText(event.reason) };
+        case "sandbox":
+            return {
+                ...event,
+                target: redactText(event.target),
+                ...(event.detail === undefined ? {} : { detail: redactText(event.detail) }),
+            };
+        case "memory":
+            return { ...event, detail: redactText(event.detail) };
+        default:
+            return event;
+    }
+}
+/** One line per event, for `vaan trace`. */
+export function describeEvent(event) {
+    switch (event.kind) {
+        case "request":
+            return `request   ${clip(event.input, 60)}`;
+        case "model_call": {
+            const tokens = event.tokensIn === undefined ? "" : `  ${event.tokensIn} in / ${event.tokensOut ?? 0} out`;
+            return `model     ${event.provider}/${event.model}${tokens}`;
+        }
+        case "tool_call":
+            return `tool      ${event.tool}`;
+        case "tool_result":
+            return `${event.ok ? "result  " : "FAILED  "}  ${event.tool} — ${clip(event.summary, 60)}`;
+        case "permission":
+            return `permit    ${event.capability} ${clip(event.target, 40)} — ${event.decision.toUpperCase()}`;
+        case "sandbox":
+            return `sandbox   ${event.op} ${clip(event.target, 50)}${event.ok ? "" : " — failed"}`;
+        case "memory":
+            return `memory    ${event.op} ${clip(event.detail, 50)}`;
+        case "error":
+            return `error     ${event.where}: ${clip(event.message, 60)}`;
+        case "result":
+            return `${event.ok ? "done" : "FAIL"}      ${clip(event.summary, 60)}`;
+    }
+}
+const clip = (text, max) => {
+    const line = text.replace(/\s+/g, " ").trim();
+    return line.length <= max ? line : `${line.slice(0, max)}…`;
+};
+//# sourceMappingURL=events.js.map

package/dist/src/observability/events.js.map

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