onadit 0.0.1 → 1.0.0

package/dist/src/retrieval/project-index.js

@@ -0,0 +1,348 @@
+/**
+ * Project identity for captured agent sessions.
+ *
+ * Conversation rows carry no project column. Auto-captured rows do carry the
+ * session id inside `idempotency_key` (`auto-capture:<source>:<session>:<fp>`),
+ * and the session transcript records the working directory. This module keeps
+ * a small sidecar (`<data_dir>/project-index.json`) mapping
+ * `<source>:<session>` → { cwd, root }, where `root` is the repository the
+ * session ran in (worktrees map to their main repository).
+ *
+ * Sources, all deterministic:
+ *   1. capture time — auto-capture records the parsed session cwd;
+ *   2. backfill — transcripts still on disk in every agent home: ~/.claude
+ *      and ~/.codex plus per-account siblings like ~/.claude-work
+ *      (<home>/projects/<dir>/<id>.jsonl,
+ *      <home>/{sessions,archived_sessions}/**\/rollout-*-<id>.jsonl).
+ * Sessions whose transcripts are gone, and web/email imports, stay unknown:
+ * they remain fully searchable, just not project-scoped. Unknown sessions are
+ * retried at each backfill, so a transcript found later still links.
+ *
+ * Only the daemon's main process writes the sidecar (atomic rename).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { getTable } from "../storage/tables.js";
+const FILE_NAME = "project-index.json";
+/**
+ * Every Claude Code / Codex home on this machine: the defaults, per-account
+ * siblings (`~/.claude-<name>`, `~/.codex-<name>`), and CLAUDE_CONFIG_DIR /
+ * CODEX_HOME. Lookups are by session id of already-captured rows, so reading
+ * an extra home can link a session but never imports anything.
+ */
+export function discoverTranscriptHomes(home = os.homedir(), env = process.env) {
+    const claude = new Set();
+    const codex = new Set();
+    let names = [];
+    try {
+        names = fs.readdirSync(home, { withFileTypes: true });
+    }
+    catch {
+        // unreadable home: fall back to the env overrides only
+    }
+    for (const ent of names) {
+        if (!ent.isDirectory())
+            continue;
+        if (/^\.claude(-[^/]+)?$/.test(ent.name))
+            claude.add(path.join(home, ent.name));
+        if (/^\.codex(-[^/]+)?$/.test(ent.name))
+            codex.add(path.join(home, ent.name));
+    }
+    if (env.CLAUDE_CONFIG_DIR)
+        claude.add(path.resolve(env.CLAUDE_CONFIG_DIR));
+    if (env.CODEX_HOME)
+        codex.add(path.resolve(env.CODEX_HOME));
+    return {
+        claudeProjects: [...claude].map((d) => path.join(d, "projects")),
+        codexRoots: [...codex].flatMap((d) => [path.join(d, "sessions"), path.join(d, "archived_sessions")]),
+    };
+}
+const HEAD_BYTES = 64 * 1024;
+/** `auto-capture:<source>:<session>:<fp>` → `<source>:<session>`. */
+export function sessionKeyFromIdempotencyKey(key) {
+    if (!key || !key.startsWith("auto-capture:"))
+        return null;
+    const parts = key.split(":");
+    if (parts.length < 4 || !parts[1] || !parts[2])
+        return null;
+    return `${parts[1]}:${parts[2]}`;
+}
+const rootCache = new Map();
+/**
+ * Repository a directory belongs to. Worktrees resolve to the main repository
+ * (via the shared git dir), so a project keeps one identity across worktrees.
+ * The home directory and "/" are not projects. A directory that no longer
+ * exists keeps its own path as identity.
+ */
+export function resolveProjectRoot(cwd) {
+    if (!cwd)
+        return null;
+    const clean = path.resolve(cwd);
+    if (clean === path.parse(clean).root || clean === os.homedir())
+        return null;
+    const cached = rootCache.get(clean);
+    if (cached !== undefined)
+        return cached;
+    let root = clean;
+    if (fs.existsSync(clean)) {
+        try {
+            const common = execFileSync("git", ["-C", clean, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2_000 }).trim();
+            root = path.basename(common) === ".git" ? path.dirname(common) : clean;
+        }
+        catch {
+            root = clean; // not a git repo: the directory is the project
+        }
+    }
+    rootCache.set(clean, root);
+    return root;
+}
+export class ProjectIndex {
+    dataDir;
+    homes;
+    data;
+    rowsCache = null;
+    constructor(dataDir, homes = discoverTranscriptHomes()) {
+        this.dataDir = dataDir;
+        this.homes = homes;
+        this.data = this.load();
+    }
+    get file() {
+        return path.join(this.dataDir, FILE_NAME);
+    }
+    load() {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.file, "utf8"));
+            if (parsed.version === 1 && parsed.sessions)
+                return parsed;
+        }
+        catch {
+            // missing or corrupt: rebuild from sources
+        }
+        return { version: 1, sessions: {} };
+    }
+    save() {
+        const tmp = `${this.file}.tmp-${process.pid}`;
+        fs.writeFileSync(tmp, JSON.stringify(this.data));
+        fs.renameSync(tmp, this.file);
+    }
+    get(sessionKey) {
+        return this.data.sessions[sessionKey];
+    }
+    /** Capture time: record the cwd the parser read from the transcript. */
+    record(sessionKey, cwd) {
+        const entry = { cwd: cwd ?? null, root: resolveProjectRoot(cwd) };
+        const prev = this.data.sessions[sessionKey];
+        if (prev && prev.cwd === entry.cwd && prev.root === entry.root)
+            return;
+        this.data.sessions[sessionKey] = entry;
+        this.rowsCache = null;
+        this.save();
+    }
+    /**
+     * Resolve every auto-captured session in `conversations_hot` that the index
+     * has not seen yet, or saw without a cwd, from transcripts still on disk.
+     * New sessions with no transcript are recorded as unknown (counted once);
+     * known-unknown sessions are retried and only change when a cwd turns up.
+     */
+    async backfillFromTable() {
+        const rows = (await getTable("conversations_hot")
+            .query()
+            .select(["id", "source", "idempotency_key"])
+            .toArray());
+        const pending = new Map();
+        for (const r of rows) {
+            const key = sessionKeyFromIdempotencyKey(r.idempotency_key);
+            if (!key || this.data.sessions[key]?.cwd)
+                continue;
+            const list = pending.get(key) ?? [];
+            list.push({ id: r.id, source: r.source });
+            pending.set(key, list);
+        }
+        if (pending.size === 0)
+            return { resolved: 0, unknown: 0 };
+        const files = this.transcriptFiles();
+        const rawFiles = new RawPayloadFiles(path.join(this.dataDir, "raw", "conversations"));
+        let resolved = 0;
+        let unknown = 0;
+        for (const [key, keyRows] of pending) {
+            const sessionId = key.slice(key.indexOf(":") + 1);
+            const file = files.get(sessionId);
+            // Transcript first; captures made since cwd was persisted also carry it
+            // in their raw payload, which survives the host deleting transcripts.
+            let cwd = file ? readTranscriptCwd(file) : null;
+            for (const r of keyRows) {
+                if (cwd)
+                    break;
+                cwd = rawFiles.cwdFor(r.source, r.id);
+            }
+            const wasUnknown = key in this.data.sessions;
+            if (!cwd && wasUnknown)
+                continue;
+            this.data.sessions[key] = { cwd, root: resolveProjectRoot(cwd) };
+            if (cwd)
+                resolved++;
+            else
+                unknown++;
+        }
+        if (resolved === 0 && unknown === 0)
+            return { resolved, unknown };
+        this.rowsCache = null;
+        this.save();
+        return { resolved, unknown };
+    }
+    /** sessionId → transcript path, for both hosts across every home. */
+    transcriptFiles() {
+        const out = new Map();
+        for (const claude of this.homes.claudeProjects) {
+            if (!fs.existsSync(claude))
+                continue;
+            for (const dir of fs.readdirSync(claude, { withFileTypes: true })) {
+                if (!dir.isDirectory())
+                    continue;
+                for (const f of fs.readdirSync(path.join(claude, dir.name))) {
+                    if (f.endsWith(".jsonl"))
+                        out.set(f.slice(0, -".jsonl".length), path.join(claude, dir.name, f));
+                }
+            }
+        }
+        const walk = (dir) => {
+            if (!fs.existsSync(dir))
+                return;
+            for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+                const p = path.join(dir, ent.name);
+                if (ent.isDirectory())
+                    walk(p);
+                else {
+                    const m = /^rollout-.*-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/.exec(ent.name);
+                    if (m)
+                        out.set(m[1], p);
+                }
+            }
+        };
+        for (const root of this.homes.codexRoots)
+            walk(root);
+        return out;
+    }
+    /**
+     * Row ids per project root, from the conversations table. Recomputed when
+     * the table version moves (any add, delete or update — a replaced capture
+     * keeps the row count but changes the version) or the index gains entries.
+     */
+    async rowsByProject() {
+        const table = getTable("conversations_hot");
+        const version = await table.version();
+        if (this.rowsCache && this.rowsCache.version === version)
+            return this.rowsCache;
+        const rows = (await table.query().select(["id", "idempotency_key"]).toArray());
+        const byRoot = new Map();
+        const projectById = new Map();
+        for (const r of rows) {
+            const key = sessionKeyFromIdempotencyKey(r.idempotency_key);
+            const root = key ? this.data.sessions[key]?.root : null;
+            if (!root)
+                continue;
+            projectById.set(r.id, root);
+            const list = byRoot.get(root) ?? [];
+            list.push(r.id);
+            byRoot.set(root, list);
+        }
+        this.rowsCache = { version, byRoot, projectById };
+        return this.rowsCache;
+    }
+}
+/**
+ * After a save job completes: link its session to the project it ran in.
+ * Every save path (daemon capture, `onadit capture`, POST /save) goes through
+ * the save job, so this is the one place capture-time identity is recorded.
+ * Best-effort — a failed index write never fails the save.
+ */
+export function recordSavedSessionProject(index, payload) {
+    if (!payload || typeof payload !== "object")
+        return;
+    const { idempotency_key, cwd } = payload;
+    if (typeof idempotency_key !== "string" || typeof cwd !== "string" || !cwd)
+        return;
+    const sessionKey = sessionKeyFromIdempotencyKey(idempotency_key);
+    if (!sessionKey)
+        return;
+    try {
+        index.record(sessionKey, cwd);
+    }
+    catch (err) {
+        process.stderr.write(`Project index record failed (non-fatal): ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+/** Raw save payloads (`<source>/<ts>_<rowId>.json`), listed lazily per source. */
+class RawPayloadFiles {
+    root;
+    bySource = new Map();
+    constructor(root) {
+        this.root = root;
+    }
+    cwdFor(source, rowId) {
+        let names = this.bySource.get(source);
+        if (!names) {
+            names = new Map();
+            const dir = path.join(this.root, source);
+            if (fs.existsSync(dir)) {
+                for (const f of fs.readdirSync(dir)) {
+                    const m = /_([^_]+)\.json$/.exec(f);
+                    if (m)
+                        names.set(m[1], path.join(dir, f));
+                }
+            }
+            this.bySource.set(source, names);
+        }
+        const file = names.get(rowId);
+        if (!file)
+            return null;
+        try {
+            const payload = JSON.parse(fs.readFileSync(file, "utf8"));
+            return typeof payload.cwd === "string" && payload.cwd ? payload.cwd : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** First `cwd` recorded in a transcript's opening lines (both hosts write it early). */
+export function readTranscriptCwd(file) {
+    let fd;
+    try {
+        fd = fs.openSync(file, "r");
+        const buf = Buffer.alloc(HEAD_BYTES);
+        const n = fs.readSync(fd, buf, 0, HEAD_BYTES, 0);
+        for (const line of buf.subarray(0, n).toString("utf8").split("\n")) {
+            if (!line.includes('"cwd"'))
+                continue;
+            try {
+                const e = JSON.parse(line);
+                const cwd = e.cwd ?? e.payload?.cwd;
+                if (typeof cwd === "string" && cwd)
+                    return cwd;
+            }
+            catch {
+                // truncated last line
+            }
+        }
+    }
+    catch {
+        // unreadable transcript: unknown
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+    return null;
+}
+let active = null;
+/** The daemon installs its index once; retrieval reads it (null in tests/CLI). */
+export function setProjectIndex(index) {
+    active = index;
+}
+export function getProjectIndex() {
+    return active;
+}
+//# sourceMappingURL=project-index.js.map

package/dist/src/retrieval/project-index.js.map

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

package/dist/src/retrieval/recall-hint.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What an agent is told at session start about Onadit, in the project brief and
+ * in the line the hook prints where no brief exists. No imports beyond the
+ * names: the hook is a short-lived CLI process and must not load the store to
+ * print a sentence.
+ *
+ * The tool is named in full. Some hosts hide a server's tools until the agent
+ * looks for one, so "check your memory" alone reaches onadit_search or nothing.
+ */
+import { type McpNaming } from "../mcp/names.js";
+export declare const RECALL_HINT: string;
+/** Printed at session start where there is no project brief (a new folder, no trackers, no sessions). */
+export declare const NO_BRIEF_HINT = "Onadit is connected: it keeps this user's earlier decisions and rules from their past AI sessions. Before you start a task, call onadit_context_pack (MCP server onadit) once with this cwd. As its task, put what you are about to decide as a short question (\"Which database for the export job?\"), not the instruction you were given. It returns the user's earlier decisions and rules in a few KB. Lines marked \"You said\" are the user's own words: follow them unless the user now says otherwise, and name the session they come from. To read one in context, open it with onadit_open_evidence at detail \"middle\" with the quote as query; that returns the passage, and a whole session is many times larger. Use onadit_search only when the pack has nothing useful. Skip Onadit for a trivial question.";
+/**
+ * `text` with the hint in it spelled the way a connection under `naming`
+ * names the server and its tools. Only the hint changes: the rest of a brief
+ * quotes the person's notes and stays as written.
+ */
+export declare function withHintNames(text: string, naming: McpNaming): string;
+/** Added where one host on this Mac has the tools under the current names and another under the earlier ones. */
+export declare const EARLIER_NAMES_NOTE: string;
+//# sourceMappingURL=recall-hint.d.ts.map

package/dist/src/retrieval/recall-hint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-hint.d.ts","sourceRoot":"","sources":["../../../src/retrieval/recall-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAA+C,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE9F,eAAO,MAAM,WAAW,QASwE,CAAC;AAEjG,yGAAyG;AACzG,eAAO,MAAM,aAAa,kyBAAsH,CAAC;AAEjJ;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,MAAM,CAGrE;AAED,iHAAiH;AACjH,eAAO,MAAM,kBAAkB,QAAiJ,CAAC"}

package/dist/src/retrieval/recall-hint.js

@@ -0,0 +1,33 @@
+/**
+ * What an agent is told at session start about Onadit, in the project brief and
+ * in the line the hook prints where no brief exists. No imports beyond the
+ * names: the hook is a short-lived CLI process and must not load the store to
+ * print a sentence.
+ *
+ * The tool is named in full. Some hosts hide a server's tools until the agent
+ * looks for one, so "check your memory" alone reaches onadit_search or nothing.
+ */
+import { PREVIOUS_NAMING, SERVER_NAME, withToolNames } from "../mcp/names.js";
+export const RECALL_HINT = "Before you start a task, call onadit_context_pack (MCP server onadit) once with this cwd. " +
+    'As its task, put what you are about to decide as a short question ("Which database for the export job?"), ' +
+    "not the instruction you were given. " +
+    "It returns the user's earlier decisions and rules in a few KB. " +
+    'Lines marked "You said" are the user\'s own words: follow them unless the user now says otherwise, ' +
+    "and name the session they come from. " +
+    'To read one in context, open it with onadit_open_evidence at detail "middle" with the quote as query; ' +
+    "that returns the passage, and a whole session is many times larger. " +
+    "Use onadit_search only when the pack has nothing useful. Skip Onadit for a trivial question.";
+/** Printed at session start where there is no project brief (a new folder, no trackers, no sessions). */
+export const NO_BRIEF_HINT = `Onadit is connected: it keeps this user's earlier decisions and rules from their past AI sessions. ${RECALL_HINT}`;
+/**
+ * `text` with the hint in it spelled the way a connection under `naming`
+ * names the server and its tools. Only the hint changes: the rest of a brief
+ * quotes the person's notes and stays as written.
+ */
+export function withHintNames(text, naming) {
+    const hint = withToolNames(RECALL_HINT, naming).replaceAll(`(MCP server ${SERVER_NAME})`, `(MCP server ${naming.serverName})`);
+    return text.replace(RECALL_HINT, () => hint);
+}
+/** Added where one host on this Mac has the tools under the current names and another under the earlier ones. */
+export const EARLIER_NAMES_NOTE = `If your tools are named ${PREVIOUS_NAMING.toolPrefix}… (MCP server ${PREVIOUS_NAMING.serverName}), they are the same tools: use those names.`;
+//# sourceMappingURL=recall-hint.js.map

package/dist/src/retrieval/recall-hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-hint.js","sourceRoot":"","sources":["../../../src/retrieval/recall-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAkB,MAAM,iBAAiB,CAAC;AAE9F,MAAM,CAAC,MAAM,WAAW,GACtB,4FAA4F;IAC5F,4GAA4G;IAC5G,sCAAsC;IACtC,iEAAiE;IACjE,qGAAqG;IACrG,uCAAuC;IACvC,wGAAwG;IACxG,sEAAsE;IACtE,8FAA8F,CAAC;AAEjG,yGAAyG;AACzG,MAAM,CAAC,MAAM,aAAa,GAAG,sGAAsG,WAAW,EAAE,CAAC;AAEjJ;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,MAAiB;IAC3D,MAAM,IAAI,GAAG,aAAa,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,UAAU,CAAC,eAAe,WAAW,GAAG,EAAE,eAAe,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC;IAC/H,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;AAC/C,CAAC;AAED,iHAAiH;AACjH,MAAM,CAAC,MAAM,kBAAkB,GAAG,2BAA2B,eAAe,CAAC,UAAU,iBAAiB,eAAe,CAAC,UAAU,8CAA8C,CAAC"}

package/dist/src/retrieval/receipt.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Point-of-use receipt (Slice 1 of the value-visibility thread).
+ *
+ * A receipt is the ONE human-facing line a retrieval response leads with:
+ * a humble, plain-language summary of what Onadit recalled, so the client
+ * agent (Claude Code / Codex / Cursor) can relay it at the moment of use.
+ * The menu-bar scoreboard is too late for attribution — this is.
+ *
+ * Design rules (see TODO.md "Value visibility" slice):
+ * - Human audience, not machine: NO scores, tiers, `source` codes,
+ *   retrieval methods, or byte/token counts. Those stay in the hit list,
+ *   which is the agent's working data.
+ * - Name the specific sources, capped at {@link NAMED_MAX}; the tail is a
+ *   plain count (`+N more`), NEVER a token volume — we must not imply Onadit
+ *   literally read every token of every source.
+ * - Humble verb: "recalled", never "improved your answer".
+ * - Agent-mediated: Onadit can pre-format and instruct, but cannot see
+ *   whether the client rendered it. So this is best-effort text, not
+ *   telemetry — omitted entirely when there is nothing honest to say.
+ */
+import type { CompactHit } from "./compact.js";
+import type { ContextPack } from "./context-pack.js";
+/** Maximum number of named sources before collapsing the rest into `+N more`. */
+export declare const NAMED_MAX = 3;
+/**
+ * Receipts default ON; opt out with RIFT_RECEIPT=false|0|off|no. Default-on
+ * is deliberate: the whole point is visibility, and an off-by-default flag
+ * would mean it never shows during dogfood (the only signal we get on which
+ * clients actually relay it).
+ */
+export declare function receiptEnabled(): boolean;
+/**
+ * Build the receipt for onadit_search / onadit_conversations_search.
+ *
+ * Plain search mixes kinds, so naming the things is enough — no kind label.
+ * Prefers each hit's `summary` (reads like English) over `title` (often
+ * tag-salad like "rift, cli-tool, typescript").
+ */
+export declare function buildSearchReceipt(hits: CompactHit[] | undefined): string | null;
+/**
+ * Build the receipt for onadit_context_pack.
+ *
+ * Here the buckets ARE trustworthy kinds, so we lead with the kind
+ * ("a prior decision", "the current state") — that is exactly the signal
+ * the slice calls for. We draw from durable/current buckets first and
+ * deliberately EXCLUDE `discounted` (stale by definition — claiming we
+ * "recalled" it would be dishonest) and `recommended_live_files` (Onadit
+ * points at those, it did not recall their contents).
+ */
+export declare function buildContextPackReceipt(pack: ContextPack | undefined): string | null;
+/**
+ * Prepend a receipt as the leading line of a response body (leading, because
+ * agents relay what they read first and drop trailing content). No-op when
+ * the receipt is null.
+ */
+export declare function withReceipt(receipt: string | null, body: string): string;
+//# sourceMappingURL=receipt.d.ts.map

package/dist/src/retrieval/receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.d.ts","sourceRoot":"","sources":["../../../src/retrieval/receipt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,iFAAiF;AACjF,eAAO,MAAM,SAAS,IAAI,CAAC;AAa3B;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAIxC;AAgCD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAShF;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAyBpF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAExE"}

package/dist/src/retrieval/receipt.js

@@ -0,0 +1,122 @@
+/** Maximum number of named sources before collapsing the rest into `+N more`. */
+export const NAMED_MAX = 3;
+/** Word budget per named phrase before eliding with `…`. */
+const PHRASE_MAX_WORDS = 9;
+/**
+ * Hard character budget per phrase, applied AFTER the word cap. The word cap
+ * alone can't bound a single long unbroken token (a URL, a path, or a
+ * comma-less tag blob counts as one "word"), and this is the exact line agents
+ * are most likely to quote — so it must stay short no matter the input shape.
+ */
+const PHRASE_MAX_CHARS = 64;
+/**
+ * Receipts default ON; opt out with RIFT_RECEIPT=false|0|off|no. Default-on
+ * is deliberate: the whole point is visibility, and an off-by-default flag
+ * would mean it never shows during dogfood (the only signal we get on which
+ * clients actually relay it).
+ */
+export function receiptEnabled() {
+    const v = process.env["RIFT_RECEIPT"];
+    if (v == null)
+        return true;
+    return !/^(false|0|off|no)$/i.test(v.trim());
+}
+/**
+ * Reduce a raw title/summary/decision to a short, single-line, italics-safe
+ * phrase. Collapses whitespace, word-caps with an ellipsis, then ESCAPES
+ * markdown emphasis (`\_`, `\*`) so an embedded underscore can't prematurely
+ * close the wrapping italics — escaping rather than stripping keeps real
+ * filenames like `PROJECT_STATE.md` intact. Returns null for empty input so
+ * callers can skip it.
+ */
+function phrase(raw, maxWords = PHRASE_MAX_WORDS) {
+    if (!raw)
+        return null;
+    const full = raw.replace(/\s+/g, " ").trim();
+    if (!full)
+        return null;
+    let s = full.split(" ").slice(0, maxWords).join(" ");
+    if (s.length > PHRASE_MAX_CHARS)
+        s = s.slice(0, PHRASE_MAX_CHARS).trimEnd();
+    // `s` is a prefix of `full`, so a shorter length means we elided something
+    // (by word OR by char) and owe the reader an ellipsis.
+    if (s.length < full.length)
+        s += "…";
+    // Backticks aren't reliably escapable inside italics, so drop them; escape
+    // emphasis markers that would otherwise toggle the wrapping `_..._`.
+    return s.replace(/`/g, "").replace(/([_*])/g, "\\$1");
+}
+/** Wrap named phrases + tail count into the final italic receipt line. */
+function render(named, total) {
+    if (named.length === 0)
+        return null;
+    const more = Math.max(0, total - named.length);
+    const tail = more > 0 ? ` — +${more} more` : "";
+    return `_Onadit recalled ${named.join(", ")}${tail}._`;
+}
+/**
+ * Build the receipt for onadit_search / onadit_conversations_search.
+ *
+ * Plain search mixes kinds, so naming the things is enough — no kind label.
+ * Prefers each hit's `summary` (reads like English) over `title` (often
+ * tag-salad like "rift, cli-tool, typescript").
+ */
+export function buildSearchReceipt(hits) {
+    if (!receiptEnabled() || !hits?.length)
+        return null;
+    const named = [];
+    for (const h of hits) {
+        if (named.length >= NAMED_MAX)
+            break;
+        const p = phrase(h.summary || h.title);
+        if (p)
+            named.push(p);
+    }
+    return render(named, hits.length);
+}
+/**
+ * Build the receipt for onadit_context_pack.
+ *
+ * Here the buckets ARE trustworthy kinds, so we lead with the kind
+ * ("a prior decision", "the current state") — that is exactly the signal
+ * the slice calls for. We draw from durable/current buckets first and
+ * deliberately EXCLUDE `discounted` (stale by definition — claiming we
+ * "recalled" it would be dishonest) and `recommended_live_files` (Onadit
+ * points at those, it did not recall their contents).
+ */
+export function buildContextPackReceipt(pack) {
+    if (!receiptEnabled() || !pack)
+        return null;
+    // Ordered by durability/currency: a decision is worth surfacing before a
+    // passing discussion. Each entry is [kind label, raw phrase source]. The
+    // phrase is clipped, so a sentence the user said is named by its session:
+    // clipped, it could lose the clause that limits it.
+    const candidates = [
+        ...(pack.decisions ?? []).map((d) => d.said_by === "user" ? ["a decision you stated in", d.session] : ["a prior decision", d.text]),
+        ...(pack.current_truth ?? []).map((e) => ["the current state", e.title]),
+        ...(pack.constraints ?? []).map((c) => c.said_by === "user" ? ["a rule you set in", c.session] : ["a constraint", c.text]),
+        ...(pack.rules ?? []).map((r) => ["a rule", r.title]),
+        ...(pack.past_reasoning ?? []).map((e) => ["a past discussion", e.title]),
+        ...(pack.examples ?? []).map((e) => ["a past discussion", e.summary || e.title]),
+        ...(pack.older_memory ?? []).map((e) => ["older memory", e.title]),
+        ...(pack.other_projects ?? []).map((o) => [`work in ${o.project}`, o.title]),
+    ];
+    const named = [];
+    for (const [label, raw] of candidates) {
+        if (named.length >= NAMED_MAX)
+            break;
+        const p = phrase(raw);
+        if (p)
+            named.push(`${label} (${p})`);
+    }
+    return render(named, candidates.length);
+}
+/**
+ * Prepend a receipt as the leading line of a response body (leading, because
+ * agents relay what they read first and drop trailing content). No-op when
+ * the receipt is null.
+ */
+export function withReceipt(receipt, body) {
+    return receipt ? `${receipt}\n\n${body}` : body;
+}
+//# sourceMappingURL=receipt.js.map

package/dist/src/retrieval/receipt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.js","sourceRoot":"","sources":["../../../src/retrieval/receipt.ts"],"names":[],"mappings":"AAuBA,iFAAiF;AACjF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC;AAE3B,4DAA4D;AAC5D,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACtC,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC3B,OAAO,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,MAAM,CAAC,GAAuB,EAAE,QAAQ,GAAG,gBAAgB;IAClE,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7C,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrD,IAAI,CAAC,CAAC,MAAM,GAAG,gBAAgB;QAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,OAAO,EAAE,CAAC;IAC5E,2EAA2E;IAC3E,uDAAuD;IACvD,IAAI,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM;QAAE,CAAC,IAAI,GAAG,CAAC;IACrC,2EAA2E;IAC3E,qEAAqE;IACrE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AACxD,CAAC;AAED,0EAA0E;AAC1E,SAAS,MAAM,CAAC,KAAe,EAAE,KAAa;IAC5C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAChD,OAAO,oBAAoB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA8B;IAC/D,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IACpD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,KAAK,CAAC,MAAM,IAAI,SAAS;YAAE,MAAM;QACrC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAA6B;IACnE,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAE5C,yEAAyE;IACzE,yEAAyE;IACzE,0EAA0E;IAC1E,oDAAoD;IACpD,MAAM,UAAU,GAAwC;QACtD,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAgC,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,0BAA0B,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,kBAAkB,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACjK,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAgC,EAAE,CAAC,CAAC,mBAAmB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;QACtG,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAgC,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,mBAAmB,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACxJ,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAgC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;QACnF,GAAG,CAAC,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAgC,EAAE,CAAC,CAAC,mBAAmB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;QACvG,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAgC,EAAE,CAAC,CAAC,mBAAmB,EAAE,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC;QAC9G,GAAG,CAAC,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAgC,EAAE,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;QAChG,GAAG,CAAC,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAgC,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;KAC3G,CAAC;IAEF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,UAAU,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,MAAM,IAAI,SAAS;YAAE,MAAM;QACrC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAAsB,EAAE,IAAY;IAC9D,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC"}