mindweave 0.0.1 → 2.1.2

package/dist/mcp/trust.js

@@ -0,0 +1,98 @@
+/**
+ * trust.ts — noticing when a server changes what its tools claim to do.
+ *
+ * A tool description is not documentation. It is text written by a third party that
+ * goes straight into the model's prompt and is read as instruction. That makes the
+ * description an injection surface, and the 2026 literature on MCP converges on one
+ * structural cause for the whole family of attacks: **clients inherit trust from the
+ * servers they connect to and never verify it again.**
+ *
+ * Three named variants:
+ *   - Tool poisoning     — hidden instructions in a description or schema.
+ *   - Rug pull           — a clean server ships an update that poisons a description,
+ *                          and clients reload it silently.
+ *   - Cross-server shadow — one server's description manipulates the agent into
+ *                          misusing a DIFFERENT server's tools.
+ *
+ * This module addresses the second one, and only the second one. We fingerprint every
+ * tool's description and schema on first sight, persist it, and refuse a tool whose
+ * fingerprint has moved until the user looks at the change. That is deterministic and
+ * fires regardless of what the model does.
+ *
+ * WHAT THIS DOES NOT DO, stated plainly here and in SECURITY.md because implying
+ * otherwise would be worse than not having it: a server that is malicious on day one
+ * passes every check in this file. First sight is trusted by construction — there is no
+ * signature to verify, no reputation to consult. This catches CHANGE, not badness. No
+ * MCP client currently solves the day-one case, and pretending we do would be the kind
+ * of claim that quietly becomes a lie.
+ *
+ * The decisions are pure; `store.ts` does the disk work.
+ */
+import { createHash } from "node:crypto";
+import { mcpToolName } from "./catalog.js";
+/** A tool's fingerprint: what it claims to do and what it claims to accept. */
+export function fingerprint(def) {
+    // Description AND schema. A poisoned parameter description is the same attack as a
+    // poisoned tool description, and hashing only the latter would miss it entirely.
+    const material = JSON.stringify({ d: def.description, s: def.inputSchema });
+    return createHash("sha256").update(material).digest("hex").slice(0, 32);
+}
+/** Build the fingerprint record for a whole catalog. */
+export function fingerprintCatalog(defs) {
+    const out = {};
+    for (const def of defs)
+        out[mcpToolName(def.server, def.name)] = fingerprint(def);
+    return out;
+}
+/**
+ * Compare a live catalog against what we recorded last time (pure).
+ *
+ * Note what is NOT flagged: a tool that disappeared. A server dropping a tool cannot
+ * inject anything, and treating removal as suspicious would make every ordinary server
+ * upgrade look like an attack — which trains the user to click through the prompt, which
+ * is how a real warning gets ignored.
+ */
+export function compareTrust(defs, known) {
+    const verdict = { unchanged: [], fresh: [], changed: [] };
+    for (const def of defs) {
+        const name = mcpToolName(def.server, def.name);
+        const now = fingerprint(def);
+        const before = known[name];
+        if (before === undefined)
+            verdict.fresh.push(name);
+        else if (before === now)
+            verdict.unchanged.push(name);
+        else
+            verdict.changed.push(name);
+    }
+    verdict.fresh.sort();
+    verdict.changed.sort();
+    verdict.unchanged.sort();
+    return verdict;
+}
+/**
+ * The question put to the user when a tool's description has moved (pure).
+ *
+ * Deliberately concrete about what changed and what the risk is. "Trust this server?"
+ * is unanswerable; "this tool's description changed since you last used it, and a
+ * description is instructions the agent follows" is a question someone can actually
+ * decide.
+ */
+export function changedToolsQuestion(changed) {
+    const list = changed.length <= 3 ? changed.join(", ") : `${changed.slice(0, 3).join(", ")} and ${changed.length - 3} more`;
+    return (`An MCP server changed what ${changed.length === 1 ? "a tool claims" : "some tools claim"} to do since you last ` +
+        `used ${changed.length === 1 ? "it" : "them"}: ${list}. Tool descriptions are instructions the agent follows, so ` +
+        `a silent change is how a trusted server turns hostile. Allow ${changed.length === 1 ? "it" : "them"}?`);
+}
+/** Merge accepted tools into the stored record, leaving refused ones flagged. */
+export function acceptTools(known, defs, accept) {
+    const next = { ...known };
+    const wanted = new Set(accept);
+    for (const def of defs) {
+        const name = mcpToolName(def.server, def.name);
+        if (wanted.has(name))
+            next[name] = fingerprint(def);
+    }
+    return next;
+}
+//# sourceMappingURL=trust.js.map

package/dist/mcp/trust.js.map

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

package/dist/mcp/trustStore.js

@@ -0,0 +1,55 @@
+/**
+ * trustStore.ts — where tool fingerprints live between sessions.
+ *
+ * Kept in the project's governor state dir, alongside `forbidden.md` and
+ * `forbidden-commands.md`, because this is the same kind of thing: a persisted decision
+ * about what this project is allowed to do, owned by the user rather than the model.
+ *
+ * Per PROJECT, not global. The same server can legitimately be a different build in two
+ * checkouts, and a global record would make an ordinary version difference look like a
+ * rug pull in every other project.
+ *
+ * Failure is always "no record": a missing or corrupt file means every tool reads as
+ * fresh. That is the safe direction for availability (MCP keeps working) and the honest
+ * one for security (we do not claim to have verified something we could not read).
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { projectDir } from "../memory/store.js";
+const FILE = "mcp-trust.json";
+export function trustPath(cwd) {
+    return join(projectDir(cwd), FILE);
+}
+/** Load the fingerprint record for a project. `{}` when absent or unreadable. */
+export async function loadTrust(cwd) {
+    try {
+        const raw = await fs.readFile(trustPath(cwd), "utf8");
+        const data = JSON.parse(raw);
+        if (!data || typeof data !== "object" || Array.isArray(data))
+            return {};
+        // Drop anything that is not a string→string pair rather than trusting the shape.
+        const out = {};
+        for (const [name, hash] of Object.entries(data)) {
+            if (typeof hash === "string" && hash)
+                out[name] = hash;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** Persist the fingerprint record. Best-effort: a failed write must not break MCP. */
+export async function saveTrust(cwd, record) {
+    try {
+        await fs.mkdir(projectDir(cwd), { recursive: true });
+        // Sorted keys so the file diffs cleanly in git and a review shows what moved.
+        const sorted = Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+        await fs.writeFile(trustPath(cwd), JSON.stringify(sorted, null, 2) + "\n", "utf8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=trustStore.js.map

package/dist/mcp/trustStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trustStore.js","sourceRoot":"","sources":["../../src/mcp/trustStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGhD,MAAM,IAAI,GAAG,gBAAgB,CAAC;AAE9B,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW;IACzC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;QACtD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;QACxC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,CAAC;QACxE,iFAAiF;QACjF,MAAM,GAAG,GAAgB,EAAE,CAAC;QAC5B,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAA+B,CAAC,EAAE,CAAC;YAC3E,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI;gBAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACzD,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW,EAAE,MAAmB;IAC9D,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,8EAA8E;QAC9E,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACjG,MAAM,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;QACnF,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/memory/autoMemory.js

@@ -0,0 +1,340 @@
+/**
+ * autoMemory.ts — Mindweave's cross-session memory store.
+ *
+ * This is the persistence layer for what Mindweave learns and is asked to remember:
+ * facts about the user, feedback on how to work, project context, and pointers
+ * to external systems. It is the personal-memory layer, SEPARATE from two things
+ * it must not duplicate:
+ *   - MINDWEAVE.md          — the project's own knowledge file (read each session).
+ *   - the governor      — standing rules / skills / forbidden paths.
+ *
+ * Layout (under the same per-project state dir as sessions and the governor):
+ *   ~/.mindweave/projects/<slug>/memory/
+ *     MEMORY.md      — the index: one line per memory, ALWAYS loaded into the
+ *                      prompt. Capped, so it stays a cheap table of contents.
+ *     <name>.md      — one topic file per memory, with a small frontmatter
+ *                      header. Read on demand by the model (grep/read), not
+ *                      auto-loaded.
+ *
+ * The model writes here through the `save_memory` tool, which saves SILENTLY: the
+ * user asked not to be made to approve each one. (This comment used to say the tool
+ * "confirms with the user first", which stopped being true when the prompt was
+ * dropped — worth stating plainly, because "we ask first" is exactly the kind of
+ * assurance someone reads once and then relies on.) This module is the mechanism
+ * only — it does not decide WHAT is worth remembering; that is the model's
+ * judgment, guided by the prompt.
+ *
+ * Like store.ts, this is the CLIENT side of the eventual client/server split:
+ * the pure engine never calls in here. All writes are best-effort.
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "../tools/atomicWrite.js";
+import { projectDir } from "./store.js";
+/** The closed set of memory types (mirrors the prompt's taxonomy). */
+export const MEMORY_TYPES = ["user", "feedback", "project", "reference"];
+export function isMemoryType(v) {
+    return typeof v === "string" && MEMORY_TYPES.includes(v);
+}
+export const MEMORY_INDEX = "MEMORY.md";
+// Caps for the always-loaded index. Lines is the natural boundary; bytes catches
+// a short index with very long lines. Past either, we load a prefix + a warning.
+const MAX_INDEX_LINES = 200;
+const MAX_INDEX_BYTES = 25_000;
+/** The memory directory for a project (under its state dir). */
+export function memoryDir(projectCwd) {
+    return join(projectDir(projectCwd), "memory");
+}
+/** Create the memory directory if absent, so the model never has to mkdir. */
+export async function ensureMemoryDir(projectCwd) {
+    try {
+        await fs.mkdir(memoryDir(projectCwd), { recursive: true });
+    }
+    catch {
+        // Best-effort: a real perms error surfaces when save_memory's write fails.
+    }
+}
+/**
+ * Read MEMORY.md for injection into the prompt, truncated to the caps. Returns
+ * "" when there is no index yet (the prompt then says memory is empty).
+ */
+export async function loadMemoryIndex(projectCwd) {
+    const dir = memoryDir(projectCwd);
+    let raw;
+    try {
+        raw = await fs.readFile(join(dir, MEMORY_INDEX), "utf8");
+    }
+    catch {
+        return "";
+    }
+    return truncateIndex((await reconcileIndex(dir, raw)).trim());
+}
+/**
+ * Give back a pointer to any memory that has one on disk but none in the index (pure
+ * except for reading the directory).
+ *
+ * This is what makes a lost index line survivable instead of fatal. The index is
+ * read-modify-write, so two Mindweave instances open on one project can each write an
+ * index that lacks the other's line. Serialising fixes that inside a process and cannot
+ * fix it between two, and the alternatives all rest on a guess: a retry budget large
+ * enough, or a lock file with a staleness timeout long enough. Both are timing, and
+ * timing is what this project has learned not to trust.
+ *
+ * Reconciling needs no timing at all. The topic FILE is the durable record and it is
+ * never the thing lost; the pointer is derived from it. So a dropped line costs
+ * visibility until the next read rather than forever, and the repair is deterministic:
+ * the same directory always produces the same index.
+ *
+ * The recovered line is rebuilt from the file's own frontmatter, which is why the hook
+ * comes back as its `description` rather than the original prose. That is a real loss of
+ * flavour and the right trade: a memory listed plainly is found, and one not listed at
+ * all may as well not exist.
+ *
+ * Costs one directory read per session when nothing is missing, which is the normal case.
+ */
+async function reconcileIndex(dir, index) {
+    let names;
+    try {
+        names = await fs.readdir(dir);
+    }
+    catch {
+        return index;
+    }
+    const orphans = names.filter((n) => n.endsWith(".md") && n !== MEMORY_INDEX && !indexLists(index, n));
+    if (orphans.length === 0)
+        return index;
+    let out = index;
+    for (const file of orphans.sort()) {
+        const meta = await frontmatterOf(join(dir, file));
+        // Skip a file we cannot read a name out of rather than listing it as "undefined":
+        // an unreadable entry in the always-loaded index is worse than a missing one.
+        if (!meta.name)
+            continue;
+        out = applyIndexUpsert(out, file, `- [${meta.name}](${file}) — ${meta.description || "recovered entry"}`);
+    }
+    return out;
+}
+/** The `name:` and `description:` from a memory file's frontmatter. */
+async function frontmatterOf(path) {
+    try {
+        const raw = await fs.readFile(path, "utf8");
+        return {
+            name: /^name:[ \t]*(.*)$/m.exec(raw)?.[1]?.trim() ?? "",
+            description: /^description:[ \t]*(.*)$/m.exec(raw)?.[1]?.trim() ?? "",
+        };
+    }
+    catch {
+        return { name: "", description: "" };
+    }
+}
+/** Line-cap first (clean boundary), then byte-cap at the last newline that fits. */
+function truncateIndex(content) {
+    if (!content)
+        return "";
+    const lines = content.split("\n");
+    const overLines = lines.length > MAX_INDEX_LINES;
+    const overBytes = content.length > MAX_INDEX_BYTES;
+    if (!overLines && !overBytes)
+        return content;
+    let out = overLines ? lines.slice(0, MAX_INDEX_LINES).join("\n") : content;
+    if (out.length > MAX_INDEX_BYTES) {
+        const cut = out.lastIndexOf("\n", MAX_INDEX_BYTES);
+        out = out.slice(0, cut > 0 ? cut : MAX_INDEX_BYTES);
+    }
+    return `${out}\n\n> WARNING: ${MEMORY_INDEX} is too long and was only partly loaded. Keep each index entry to one short line; move detail into the topic files.`;
+}
+/**
+ * Write a memory: the topic file (frontmatter + body) plus its pointer line in
+ * MEMORY.md. A memory whose name slugs to an existing file is an UPDATE — the
+ * topic file is overwritten and its index line replaced in place, so the model
+ * refining a fact never creates a duplicate.
+ */
+export async function saveMemory(projectCwd, m) {
+    await ensureMemoryDir(projectCwd);
+    const dir = memoryDir(projectCwd);
+    const slug = slugify(m.name);
+    const file = `${slug}.md`;
+    const path = join(dir, file);
+    const previous = await existingName(path);
+    const updated = previous !== null;
+    // Atomic: cross-session memory is the one thing here that OUTLIVES the session, so a
+    // torn write costs a fact the user expected to be remembered permanently.
+    await writeFileAtomic(path, renderMemoryFile(m));
+    await upsertIndexLine(dir, file, `- [${oneLine(m.name)}](${file}) — ${oneLine(m.indexLine)}`);
+    const replaced = previous && previous !== oneLine(m.name) ? previous : undefined;
+    return { name: m.name, file, updated, ...(replaced ? { replaced } : {}) };
+}
+/** The `name:` of the memory already at `path`, or null if there is no file there.
+ *  Returns "" for a file we cannot parse, which still counts as "something was here". */
+async function existingName(path) {
+    try {
+        const raw = await fs.readFile(path, "utf8");
+        return /^name:[ \t]*(.*)$/m.exec(raw)?.[1]?.trim() ?? "";
+    }
+    catch {
+        return null;
+    }
+}
+function renderMemoryFile(m) {
+    // Flat key: value frontmatter, the same shape the governor and skills use.
+    // Values are flattened to ONE line: these are model-supplied strings going into a
+    // line-oriented format, so an embedded newline would start what parses as a new
+    // frontmatter key — a `description` ending in "\ntype: user" would silently
+    // re-file the memory. Nothing malicious is needed for this, just a pasted title.
+    return [
+        "---",
+        `name: ${oneLine(m.name)}`,
+        `description: ${oneLine(m.description)}`,
+        `type: ${m.type}`,
+        "---",
+        "",
+        m.body.trim(),
+        "",
+    ].join("\n");
+}
+/** Collapse any newline/carriage return into a space, so a value stays one field. */
+function oneLine(value) {
+    return value.replace(/[\r\n]+/g, " ").trim();
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Does this line point at `file`?
+ *
+ *  Anchored to the start on purpose. The old test was `line.includes("(file.md)")`,
+ *  which matched anywhere in the line — so an index entry whose prose referenced
+ *  another memory ("supersedes (user-role.md)") was deleted when that other memory was
+ *  next saved. Index lines are model-written prose about memories, so cross-references
+ *  are expected content, and losing one silently removes a memory from the only listing
+ *  that is always loaded. */
+function pointsAt(line, file) {
+    return new RegExp(`^\\s*-\\s*\\[[^\\]]*\\]\\(${escapeRegExp(file)}\\)`).test(line);
+}
+/** Whether `index` already lists `file`. */
+export function indexLists(index, file) {
+    return index.split("\n").some((l) => pointsAt(l, file));
+}
+/** Add or replace the pointer line for `file` in an index's text (pure). */
+export function applyIndexUpsert(current, file, line) {
+    if (!current.trim())
+        return `# Memory Index\n\n${line}\n`;
+    const kept = current
+        .split("\n")
+        .filter((l) => !pointsAt(l, file))
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trimEnd();
+    return `${kept}\n${line}\n`;
+}
+/** How many times to re-attempt a write the filesystem refused. Bounded so two
+ *  instances colliding cannot spin. */
+const INDEX_WRITE_ATTEMPTS = 4;
+/**
+ * Add or replace the index line that points at `file`, keeping MEMORY.md a flat list.
+ *
+ * Read, edit, write — which is a lost update waiting to happen, and the consequence is
+ * out of proportion to the window. Two instances saving at once both read the same
+ * index, and the second write drops the first one's line. The topic FILE survives, so
+ * nothing looks broken, but MEMORY.md is the only listing that is ever loaded and
+ * nothing rebuilds it: that memory is invisible from then on, permanently.
+ *
+ * So the write is verified rather than assumed. After writing we re-read and check our
+ * own pointer is actually there; if another writer landed on top of us, we re-read
+ * their content, re-apply our line to it, and write again. Each attempt starts from
+ * whatever is on disk NOW, so the two writers converge on an index containing both
+ * lines instead of racing to overwrite each other.
+ *
+ * Atomic writes (which this already uses) solve a different problem — they stop a
+ * reader seeing a half-written file. They cannot help here, because both writes are
+ * individually complete and simply describe different pasts.
+ */
+async function upsertIndexLine(dir, file, line) {
+    return serializeIndexWrite(() => upsertIndexLineNow(dir, file, line));
+}
+/**
+ * Index edits from THIS process, one at a time.
+ *
+ * Two writers need two different answers and this is the half that can be made
+ * airtight. Inside one instance the collisions are ordinary: the engine runs
+ * concurrency-safe tools in parallel, so several `save_memory` calls can be in flight
+ * together. Read-modify-write under that loses lines, and no amount of retrying fixes
+ * it — measured at twelve concurrent saves, ten were lost, because every writer retried
+ * in step with the others and collided again.
+ *
+ * Serialising removes the race rather than narrowing it: each edit reads an index that
+ * already contains every edit before it. It also removes the Windows EPERM this
+ * uncovered, where several overlapping atomic writes fought over renaming onto the same
+ * destination.
+ *
+ * Cross-PROCESS contention (a second Mindweave open on the same project) is out of
+ * reach of a queue, and that is what the verify-and-retry below is for. The two are
+ * complementary, not alternatives.
+ */
+let indexWrites = Promise.resolve();
+function serializeIndexWrite(run) {
+    // Chained off settled OR failed, so one failing write cannot wedge the queue for the
+    // rest of the session.
+    const next = indexWrites.then(run, run);
+    indexWrites = next.catch(() => undefined);
+    return next;
+}
+async function upsertIndexLineNow(dir, file, line) {
+    const indexPath = join(dir, MEMORY_INDEX);
+    const read = async () => {
+        try {
+            return await fs.readFile(indexPath, "utf8");
+        }
+        catch {
+            return ""; // no index yet
+        }
+    };
+    // Retried only for a FAILED write, never to win a race. Windows refuses a rename
+    // while another process holds the destination, so two instances landing together
+    // produce EPERM; starting over from whatever is on disk now clears it.
+    //
+    // There is deliberately no "did my line survive" check here. One was written, and
+    // measured: across two processes it still lost 3 of 12, because both sides retry into
+    // each other. Convergence by retrying is a guess about budgets, and the reconcile on
+    // read makes a dropped line recoverable without guessing anything.
+    for (let attempt = 1; attempt <= INDEX_WRITE_ATTEMPTS; attempt++) {
+        try {
+            await writeFileAtomic(indexPath, applyIndexUpsert(await read(), file, line));
+            return;
+        }
+        catch (error) {
+            if (attempt === INDEX_WRITE_ATTEMPTS)
+                throw error;
+            await settle(attempt);
+        }
+    }
+}
+/**
+ * A short, jittered pause between attempts.
+ *
+ * Correctness comes from re-reading and re-checking, not from this: with no pause the
+ * loop is still right, it just collides again immediately. The jitter is what stops two
+ * instances retrying in lockstep forever, which is the one way a bounded retry can burn
+ * its whole budget without either side making progress.
+ */
+function settle(attempt) {
+    const ms = Math.round(15 * attempt * (0.5 + Math.random()));
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** A filesystem-safe slug from a memory name. Falls back to "memory" if empty. */
+export function slugify(name) {
+    return (name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60) || "memory");
+}
+async function exists(path) {
+    try {
+        await fs.stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=autoMemory.js.map

package/dist/memory/autoMemory.js.map

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