mindweave 0.0.1 → 2.1.2

package/dist/memory/images.js

@@ -0,0 +1,173 @@
+/**
+ * images.ts — the provider-neutral facts about an image attachment.
+ *
+ * One module owns everything core needs to know about an image without knowing
+ * which model will receive it: what kinds exist, what the caps are, how big it is
+ * on screen, and roughly what it will cost in context. Drivers own the wire shape;
+ * this owns the facts they all share.
+ *
+ * WHY A REFERENCE, NOT BYTES. An `ImageRef` is a path plus a media type — never the
+ * payload. The transcript stores refs, and the bytes are loaded only when a request
+ * is assembled. That keeps a session's JSONL small and readable, keeps resume cheap,
+ * and follows compaction's eviction rule directly: an image on disk is maximally
+ * reconstructible, and the path is the restoration key. The cost is that a file can
+ * change or vanish between the turn it was attached and a later turn; a missing file
+ * degrades to a note rather than an error, because a broken attachment must never
+ * take the conversation down with it.
+ */
+import { promises as fs } from "node:fs";
+import { extname } from "node:path";
+/**
+ * Media types every vision-capable provider accepts today. The intersection, not the
+ * union: a format only one provider takes would attach fine and then fail at the wire
+ * on the others, which is a worse experience than declining it up front.
+ */
+const MEDIA_TYPES = new Map([
+    [".png", "image/png"],
+    [".jpg", "image/jpeg"],
+    [".jpeg", "image/jpeg"],
+    [".gif", "image/gif"],
+    [".webp", "image/webp"],
+]);
+/**
+ * Image extensions Mindweave RECOGNIZES, which is deliberately wider than the set it
+ * can send. A `.bmp` or `.svg` is still identified as an image so the user gets
+ * "that format can't be sent" instead of a generic "binary file, skipped".
+ */
+export const IMAGE_EXTS = new Set([
+    ...MEDIA_TYPES.keys(),
+    ".bmp",
+    ".svg",
+    ".ico",
+    ".tiff",
+    ".avif",
+    ".heic",
+]);
+/**
+ * Per-image ceiling. Providers state their limit on the BASE64 payload (10 MB is the
+ * common figure), and base64 inflates by 4/3, so the raw-file cap that keeps us under
+ * it is 7.5 MB. Enforced on the file, before encoding, so an oversized image is
+ * refused without ever being read into memory twice.
+ */
+export const MAX_IMAGE_BYTES = Math.floor(7.5 * 1024 * 1024);
+/** Longest edge any provider accepts. Beyond this the request is rejected outright. */
+export const MAX_IMAGE_EDGE = 8000;
+/** The media type for a path, or null when it is not a format we can send. */
+export function mediaTypeFor(path) {
+    return MEDIA_TYPES.get(extname(path).toLowerCase()) ?? null;
+}
+/** Whether a path looks like an image at all (sendable or not). */
+export function isImage(path) {
+    return IMAGE_EXTS.has(extname(path).toLowerCase());
+}
+/**
+ * Approximate context cost of an image, in tokens.
+ *
+ * Vision models bill by fixed-size patches rather than pixels, so cost scales with
+ * AREA: the published figures work out to roughly a 28x28-pixel patch per visual
+ * token, and providers downscale anything larger before charging, which caps the
+ * worst case. This reproduces that shape — area over patch area, clamped to the cap.
+ *
+ * It is an approximation, in the same spirit as `CHARS_PER_TOKEN` for text, and it
+ * exists for one reason: the compaction bars ask "how full is the context", and an
+ * image counted as zero would make every bar fire late. Counting it approximately is
+ * strictly better than counting it as nothing. When dimensions are unknown we assume
+ * the cap rather than a small number, so the error is on the safe side.
+ */
+const PATCH_PX = 28;
+const MAX_IMAGE_TOKENS = 4784;
+export function estimateImageTokens(ref) {
+    if (!ref.width || !ref.height)
+        return MAX_IMAGE_TOKENS;
+    const patches = Math.ceil(ref.width / PATCH_PX) * Math.ceil(ref.height / PATCH_PX);
+    return Math.min(patches, MAX_IMAGE_TOKENS);
+}
+/** Total approximate cost of a set of attachments. */
+export function estimateImagesTokens(refs) {
+    if (!refs || refs.length === 0)
+        return 0;
+    let total = 0;
+    for (const r of refs)
+        total += estimateImageTokens(r);
+    return total;
+}
+/**
+ * Read the pixel dimensions out of an image's header.
+ *
+ * Only the container formats whose headers are unambiguous and cheap to parse are
+ * handled — PNG, JPEG and GIF, which covers every screenshot path that matters. WebP
+ * has three different chunk layouts and is not worth the surface here: it returns
+ * null, and the estimator then assumes the cap. Returning null is always safe.
+ *
+ * Reads a small prefix, never the whole file.
+ */
+export function readDimensions(buf) {
+    // PNG: signature, then an IHDR chunk with width/height at fixed offsets.
+    if (buf.length >= 24 && buf.readUInt32BE(0) === 0x89504e47) {
+        return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+    }
+    // GIF: "GIF87a"/"GIF89a", then the logical screen size, little-endian.
+    if (buf.length >= 10 && buf.toString("ascii", 0, 3) === "GIF") {
+        return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+    }
+    // JPEG: walk the marker chain to the start-of-frame, which carries the size.
+    if (buf.length >= 4 && buf.readUInt16BE(0) === 0xffd8) {
+        let pos = 2;
+        while (pos + 9 < buf.length) {
+            if (buf[pos] !== 0xff)
+                return null; // not on a marker boundary; give up safely
+            const marker = buf[pos + 1];
+            // SOF0..SOF15 carry the frame size. C4/C8/CC share the range but are tables.
+            if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                return { width: buf.readUInt16BE(pos + 7), height: buf.readUInt16BE(pos + 5) };
+            }
+            const segment = buf.readUInt16BE(pos + 2);
+            if (segment < 2)
+                return null; // malformed length would loop forever
+            pos += 2 + segment;
+        }
+    }
+    return null;
+}
+/**
+ * Turn a path into an `ImageRef`, or explain why not. Does the format check, the size
+ * check and the dimension read in one pass so callers get a single verdict.
+ */
+export async function describeImage(path, sizeBytes) {
+    const mediaType = mediaTypeFor(path);
+    if (!mediaType) {
+        return { reason: `${extname(path).toLowerCase() || "that format"} images can't be sent to a model` };
+    }
+    if (sizeBytes > MAX_IMAGE_BYTES) {
+        return { reason: `too large to send (${formatMb(sizeBytes)}, limit ${formatMb(MAX_IMAGE_BYTES)})` };
+    }
+    const dims = await readHeader(path);
+    if (dims && (dims.width > MAX_IMAGE_EDGE || dims.height > MAX_IMAGE_EDGE)) {
+        return { reason: `too big to send (${dims.width}x${dims.height}, limit ${MAX_IMAGE_EDGE}px per side)` };
+    }
+    return { path, mediaType, ...(dims ?? {}) };
+}
+/** True when a verdict from `describeImage` is a refusal rather than a ref. */
+export function isRejection(v) {
+    return "reason" in v;
+}
+/** Read just enough of the file to find its dimensions. */
+async function readHeader(path) {
+    let handle;
+    try {
+        handle = await fs.open(path, "r");
+        const buf = Buffer.alloc(65536);
+        const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
+        return readDimensions(buf.subarray(0, bytesRead));
+    }
+    catch {
+        return null; // unreadable header is not fatal — the estimator assumes the cap
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function formatMb(n) {
+    return `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+//# sourceMappingURL=images.js.map

package/dist/memory/images.js.map

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

package/dist/memory/presence.js

@@ -0,0 +1,59 @@
+import { fullPathsOf } from "./types.js";
+import { CLEARED_STUB } from "./compaction.js";
+/**
+ * The set of absolute paths whose WHOLE content is still present in the transcript:
+ * a `read_file` call with no `offset`/`limit`, whose result has not been cleared to a
+ * stub by microcompaction.
+ *
+ * Pure. `resolve` turns the call's recorded (possibly relative or labelled) path into
+ * the same absolute key the read ledger uses; it returns undefined for anything it
+ * cannot resolve, which is simply left out.
+ */
+export function fullReadPaths(entries, resolve) {
+    const callById = new Map();
+    for (const e of entries) {
+        if (e.role === "assistant" && e.toolCalls) {
+            for (const tc of e.toolCalls)
+                callById.set(tc.id, { name: tc.name, arguments: tc.arguments });
+        }
+    }
+    const present = new Set();
+    for (const e of entries) {
+        if (e.role !== "tool")
+            continue;
+        // A cleared body is a stub: the entry survives for navigation, the content does not.
+        if (e.content.includes(CLEARED_STUB))
+            continue;
+        // The tool recorded which file this result IS, at the moment it was true. Exact:
+        // no re-resolution, so a `cd` since then cannot make it point somewhere else.
+        const recorded = fullPathsOf(e);
+        if (recorded.length > 0) {
+            for (const path of recorded)
+                present.add(path);
+            continue;
+        }
+        // Fallback for sessions written before results carried that fact. Re-resolving the
+        // arguments is a guess about where a relative path pointed at the time, so it is
+        // used only when there is nothing better, never in preference to the recording.
+        const call = callById.get(e.toolCallId ?? "");
+        if (!call || call.name !== "read_file")
+            continue;
+        let args;
+        try {
+            args = JSON.parse(call.arguments);
+        }
+        catch {
+            continue; // malformed args — nothing to claim
+        }
+        // A ranged read put only a window in the transcript, not the whole file.
+        if (args.offset !== undefined || args.limit !== undefined)
+            continue;
+        if (typeof args.path !== "string")
+            continue;
+        const abs = resolve(args.path);
+        if (abs)
+            present.add(abs);
+    }
+    return present;
+}
+//# sourceMappingURL=presence.js.map

package/dist/memory/presence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.js","sourceRoot":"","sources":["../../src/memory/presence.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB,EAAE,OAA6C;IAC3F,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA+C,CAAC;IACxE,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;YAC1C,KAAK,MAAM,EAAE,IAAI,CAAC,CAAC,SAAS;gBAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC;QAChG,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;YAAE,SAAS;QAChC,qFAAqF;QACrF,IAAI,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,SAAS;QAE/C,iFAAiF;QACjF,8EAA8E;QAC9E,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QAChC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,KAAK,MAAM,IAAI,IAAI,QAAQ;gBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC/C,SAAS;QACX,CAAC;QAED,mFAAmF;QACnF,iFAAiF;QACjF,gFAAgF;QAChF,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW;YAAE,SAAS;QACjD,IAAI,IAA2D,CAAC;QAChE,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAgB,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,oCAAoC;QAChD,CAAC;QACD,yEAAyE;QACzE,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,SAAS;QACpE,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,SAAS;QAC5C,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,GAAG;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/memory/projectNotes.js

@@ -0,0 +1,247 @@
+/**
+ * projectNotes.ts — MINDWEAVE.md, and the files it pulls in.
+ *
+ * MINDWEAVE.md is the project's living notebook: what it is, how to run and test it,
+ * the conventions in play, where things stand. It is loaded for the agent at the start
+ * of every session, which is what makes a new conversation continue rather than start
+ * over. `/init` writes the first one; the agent maintains it after that.
+ *
+ * It began as exactly one file at the project root, read whole. That works until a real
+ * project has more to say than fits in one readable page, at which point the single file
+ * becomes either too long to keep accurate or too short to be worth loading. Three
+ * layers fix that without loading everything always:
+ *
+ *  - **Imports.** `@./docs/architecture.md` inside a notes file pulls that file in.
+ *    Split the notes the way the project is split, and the parts still arrive as one
+ *    document.
+ *  - **A personal layer.** `~/.mindweave/MINDWEAVE.md` applies to every project on the
+ *    machine, for the things that are true of how YOU work rather than of one codebase.
+ *  - **Per-directory notes.** A MINDWEAVE.md inside a folder describes that folder, and
+ *    is delivered only while the agent is actually working in it.
+ *
+ * The first two are assembled here into the text loaded at session start. The third is
+ * resolved per turn against the files in play, and is deliberately NOT part of that
+ * text: see `directoryNotesFor`.
+ *
+ * The import rules are the ones this syntax conventionally carries, so nobody who has
+ * written a notes file before is surprised: `@path` in ordinary prose, depth capped,
+ * cycles broken, and — the part that is easy to miss — **never inside code**. A notes
+ * file that documents an npm scope or a decorator would otherwise try to import
+ * `@types` as a path.
+ */
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+/** The one filename, everywhere. */
+export const NOTES_FILE = "MINDWEAVE.md";
+/**
+ * How far an import chain may go before it stops.
+ *
+ * Five. A notes file importing a file that imports another is normal; five levels of it
+ * is a structure nobody is reading, and the cap is what stops a mistake from pulling in
+ * a whole documentation tree.
+ */
+export const MAX_IMPORT_DEPTH = 5;
+/**
+ * Ceiling on the assembled notes.
+ *
+ * The pressure here runs one way: a file loaded every session, maintained by an agent
+ * rewarded for thoroughness, told to keep it concise by a sentence nothing enforces.
+ * Imports make that worse, because the size is now spread across files nobody sees
+ * together. This is the enforcement, and it is generous — roughly 4K tokens for "facts
+ * about this codebase".
+ */
+export const MAX_NOTES_CHARS = 16_000;
+/**
+ * Pull the `@path` imports out of a notes file.
+ *
+ * Only from prose. Fenced blocks and inline code are skipped, because a notes file is
+ * exactly the kind of document that quotes `@scope/package`, `@Component`, or an email
+ * address, and treating those as file paths would produce a confusing failure in the
+ * one file whose whole job is to be trusted.
+ *
+ * `@~/x` is the user's home, `@/x` is absolute, `@./x` and `@x` are relative to the
+ * importing file. A `#fragment` is dropped, and `\ ` is an escaped space, both so a
+ * path written for a human still resolves.
+ */
+export function importPathsIn(text, fromFile) {
+    const prose = stripCode(text);
+    const found = [];
+    const seen = new Set();
+    // Must follow start-of-line or whitespace: `foo@bar.md` is an address, not an import.
+    const re = /(?:^|\s)@((?:[^\s\\]|\\ )+)/g;
+    let m;
+    while ((m = re.exec(prose)) !== null) {
+        const raw = m[1];
+        if (!raw)
+            continue;
+        const hash = raw.indexOf("#");
+        const cleaned = (hash === -1 ? raw : raw.slice(0, hash)).replace(/\\ /g, " ");
+        if (!cleaned || cleaned === "/" || cleaned.startsWith("@"))
+            continue;
+        const abs = resolveImport(cleaned, fromFile);
+        if (!abs || seen.has(abs))
+            continue;
+        seen.add(abs);
+        found.push(abs);
+    }
+    return found;
+}
+function resolveImport(path, fromFile) {
+    if (path.startsWith("~/"))
+        return resolve(homedir(), path.slice(2));
+    if (isAbsolute(path))
+        return resolve(path);
+    return resolve(dirname(fromFile), path);
+}
+/**
+ * Remove fenced blocks and inline code so their contents cannot be read as imports.
+ *
+ * Replaced with blank lines rather than deleted, so nothing on a later line shifts into
+ * a position it was not written in — an `@path` at the start of a line must still look
+ * like one after this runs.
+ */
+function stripCode(text) {
+    const blanked = text.replace(/```[\s\S]*?(?:```|$)/g, (block) => block.replace(/[^\n]/g, " "));
+    return blanked.replace(/`[^`\n]*`/g, (span) => span.replace(/[^\n]/g, " "));
+}
+async function readIfPresent(path) {
+    try {
+        const text = await fs.readFile(path, "utf8");
+        return text.trim() ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read one notes file and everything it imports, depth-first.
+ *
+ * `seen` carries across the whole assembly rather than per branch, so a file imported
+ * from two places is included once and a cycle simply stops. Both are the same
+ * mechanism, which is why an import loop is not a special case here.
+ */
+async function collect(path, kind, seen, out, missing, depth, importedBy) {
+    const key = normalize(path).toLowerCase();
+    if (seen.has(key) || depth >= MAX_IMPORT_DEPTH)
+        return;
+    seen.add(key);
+    const body = await readIfPresent(path);
+    if (body === null) {
+        // Only an IMPORT is worth reporting. A project with no notes file at all, or a
+        // user who keeps none, is the ordinary case and not a problem.
+        if (kind === "import")
+            missing.push(path);
+        return;
+    }
+    out.push({ source: { path, kind, ...(importedBy ? { importedBy } : {}) }, body: body.trim() });
+    for (const target of importPathsIn(body, path)) {
+        await collect(target, "import", seen, out, missing, depth + 1, path);
+    }
+}
+/** Where the machine-wide notes live, beside the config the app already keeps there. */
+export function userNotesPath(stateDir = join(homedir(), ".mindweave")) {
+    return join(stateDir, NOTES_FILE);
+}
+/**
+ * Assemble the notes a session starts with: the user's, then the project's, plus
+ * everything either imports.
+ *
+ * The user's layer comes FIRST and the project's second, because when the two disagree
+ * the project should win, and a model reading in order treats what it read last as more
+ * specific. Each file is headed with where it came from — without that, a rule from the
+ * home directory looks like it came from the repository, and someone debugging why the
+ * agent insists on something has nowhere to look.
+ */
+export async function assembleNotes(cwd, opts = {}) {
+    const seen = new Set();
+    const parts = [];
+    const missing = [];
+    if (opts.includeUser !== false) {
+        await collect(userNotesPath(opts.stateDir), "user", seen, parts, missing, 0);
+    }
+    await collect(join(cwd, NOTES_FILE), "project", seen, parts, missing, 0);
+    if (parts.length === 0)
+        return { text: "", sources: [], truncated: false, missing };
+    const blocks = parts.map(({ source, body }) => {
+        if (source.kind === "project")
+            return body;
+        const label = source.kind === "user"
+            ? `${NOTES_FILE} (yours, applies to every project)`
+            : `imported from ${displayPath(source.path, cwd)}`;
+        return `--- ${label} ---\n${body}`;
+    });
+    // A named import that is not there is worth saying. Silence would leave the agent
+    // told to "see the architecture notes" with no architecture notes and no idea why.
+    if (missing.length > 0) {
+        const list = missing.map((p) => displayPath(p, cwd)).join(", ");
+        blocks.push(`[These notes import ${list}, which could not be read. That part is missing.]`);
+    }
+    return capped(blocks.join("\n\n"), parts.map((p) => p.source), missing);
+}
+/** A path as a person would refer to it: inside the project, relative; outside, whole. */
+function displayPath(path, cwd) {
+    const rel = relative(cwd, path);
+    return rel && !rel.startsWith("..") ? rel.split(sep).join("/") : path;
+}
+function capped(text, sources, missing) {
+    if (text.length <= MAX_NOTES_CHARS)
+        return { text, sources, truncated: false, missing };
+    const cut = text.slice(0, MAX_NOTES_CHARS);
+    const atLine = cut.slice(0, cut.lastIndexOf("\n") + 1) || cut;
+    return {
+        text: `${atLine.trimEnd()}\n\n[The project notes are longer than fits here and were truncated at ` +
+            `this point. Read the file directly if you need the rest, and consider trimming it.]`,
+        sources,
+        truncated: true,
+        missing,
+    };
+}
+/**
+ * The per-directory notes that apply to a set of files being worked on.
+ *
+ * For each file, every directory from the project root down to the file's own folder is
+ * checked for a MINDWEAVE.md. A note in `src/api/` therefore reaches the agent exactly
+ * when it opens something in `src/api/`, and not before — which is the point. Loading
+ * every folder's notes at session start would cost the whole budget to say things about
+ * code nobody is touching.
+ *
+ * The root's own file is excluded: it is already loaded at session start, and including
+ * it here would send it twice.
+ *
+ * Returned rather than concatenated into the session prompt on purpose. These change as
+ * the agent moves around a repository, and anything that changes mid-session belongs in
+ * the volatile part of the request; folding it into the cached prefix would rewrite that
+ * prefix every time the agent opened a file in a new folder, which is the single most
+ * expensive thing a turn can do.
+ */
+export async function directoryNotesFor(root, files) {
+    const dirs = new Set();
+    for (const file of files) {
+        const abs = isAbsolute(file) ? file : resolve(root, file);
+        const rel = relative(root, abs);
+        // Outside the project entirely, or the project root itself.
+        if (!rel || rel.startsWith(".."))
+            continue;
+        let dir = dirname(abs);
+        while (dir.length >= root.length) {
+            if (normalize(dir) !== normalize(root))
+                dirs.add(dir);
+            const up = dirname(dir);
+            if (up === dir)
+                break;
+            dir = up;
+        }
+    }
+    const out = [];
+    // Shallowest first: a folder's notes should read before the notes of a folder inside
+    // it, so the more specific text is the last thing the model sees.
+    for (const dir of [...dirs].sort((a, b) => a.length - b.length)) {
+        const path = join(dir, NOTES_FILE);
+        const body = await readIfPresent(path);
+        if (body !== null)
+            out.push({ path, text: body.trim() });
+    }
+    return out;
+}
+//# sourceMappingURL=projectNotes.js.map

package/dist/memory/projectNotes.js.map

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

package/dist/memory/restore.js

@@ -0,0 +1,72 @@
+const env = (name, fallback) => {
+    const v = Number(process.env[name]);
+    return Number.isFinite(v) && v > 0 ? v : fallback;
+};
+/** Most files worth putting back. Past a handful this stops being "where I was" and
+ *  becomes a second copy of the working set, which is what was removed for costing
+ *  12K on every model call. */
+export const RESTORE_MAX_FILES = env("MINDWEAVE_RESTORE_MAX_FILES", 5);
+/** Per-file ceiling. A single large file must not spend the whole budget. */
+export const RESTORE_MAX_TOKENS_PER_FILE = env("MINDWEAVE_RESTORE_FILE_TOKENS", 3_000);
+/**
+ * Total ceiling, before the model-anchored cap below is applied.
+ *
+ * 12K rather than the 50K a state-of-the-art client uses, and the difference is
+ * arithmetic rather than taste. Restored content is written once and then carried in
+ * the cached prefix for the rest of the session, so its cost is the write plus the
+ * carry. At 50K that totals more than a dozen saved re-read round trips on every model
+ * priced here — and since at most five files are restored, five round trips is the most
+ * it can ever save. A 50K budget cannot break even at any hit rate. 12K breaks even at
+ * roughly three of five.
+ */
+export const RESTORE_BUDGET_TOKENS = env("MINDWEAVE_RESTORE_BUDGET", 12_000);
+/** Never let restoration take more than this share of the room compaction just made. */
+const RESTORE_MAX_SHARE_OF_BAR = 0.15;
+/** What restoration may spend for a given autocompact bar (pure). */
+export function restoreBudgetFor(autoBar) {
+    return Math.min(RESTORE_BUDGET_TOKENS, Math.round(autoBar * RESTORE_MAX_SHARE_OF_BAR));
+}
+/**
+ * Choose which files to put back after a compaction (pure).
+ *
+ * `stillVisible` is what the kept tail already shows the model. Re-sending a file it
+ * can see costs its full length and buys nothing; the same diff-against-what-survived
+ * that a state-of-the-art client applies, and worth up to a whole budget on its own.
+ */
+export function selectForRestore(reads, stillVisible = new Set(), excluded = () => false, maxFiles = RESTORE_MAX_FILES) {
+    const candidates = [];
+    for (const [path, record] of reads) {
+        // A grep hit is not a read: it showed matching lines, never the file, so there is
+        // no "content the model had" to put back.
+        if (record.viaSearch)
+            continue;
+        // A ranged read never covered the whole file, so restoring it whole would hand the
+        // model more than it ever had and quietly reset what it believes it has seen.
+        if (!record.full)
+            continue;
+        if (stillVisible.has(path))
+            continue;
+        if (excluded(path))
+            continue;
+        candidates.push({ path, worked: (record.focus?.length ?? 0) > 0 });
+    }
+    const touchedAt = (path) => reads.get(path)?.touchedAt ?? 0;
+    // Worked-in files first, then by recency within each group. Recency alone is the
+    // selector this deliberately avoids; it is used only to break ties.
+    candidates.sort((a, b) => (a.worked === b.worked ? touchedAt(b.path) - touchedAt(a.path) : a.worked ? -1 : 1));
+    return candidates.slice(0, maxFiles);
+}
+/** Wrap restored contents for the transcript (pure).
+ *
+ *  Says plainly that this is a restoration rather than something the model read, so it
+ *  cannot mistake the block for its own earlier work, and states the one fact that
+ *  makes the ledger reconciliation legible from the model's side: everything else it
+ *  had open is gone and has to be read again. */
+export function renderRestored(files) {
+    const blocks = files.map((f) => `<file path="${f.path}">\n${f.content}\n</file>`).join("\n\n");
+    return ("The files you were working in, restored after the compaction above so you can " +
+        "carry on without re-reading them. Any OTHER file you had open is no longer in " +
+        "context: read it again before you edit it.\n\n" +
+        `<restored_files>\n${blocks}\n</restored_files>`);
+}
+//# sourceMappingURL=restore.js.map

package/dist/memory/restore.js.map

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