mindweave 0.0.1 → 2.1.2

package/dist/mcp/resources.js

@@ -0,0 +1,119 @@
+/** Longest resource description we pass on, mirroring the tool-description cap. */
+export const MAX_RESOURCE_DESCRIPTION = 512;
+/** How many resources one listing may return, before it is a context problem itself. */
+export const MAX_RESOURCES_LISTED = 200;
+/** Does this server say it has resources at all? */
+export function hasResources(capabilities) {
+    return Boolean(capabilities?.resources);
+}
+function text(value, max = MAX_RESOURCE_DESCRIPTION) {
+    const s = typeof value === "string" ? value.trim() : "";
+    return s.length > max ? s.slice(0, max - 1) + "…" : s;
+}
+/** Parse a `resources/list` payload, dropping entries that cannot be used (pure). */
+export function parseResourceList(server, result) {
+    const raw = result?.resources;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const item of raw) {
+        const r = item;
+        const uri = typeof r?.uri === "string" ? r.uri.trim() : "";
+        // A resource with no URI cannot be read, so it is not a resource.
+        if (!uri || seen.has(uri))
+            continue;
+        seen.add(uri);
+        out.push({ server, uri, name: text(r?.name, 128) || uri, description: text(r?.description), mimeType: text(r?.mimeType, 64) });
+    }
+    return sortResources(out);
+}
+/** Parse a `resources/templates/list` payload (pure). */
+export function parseTemplateList(server, result) {
+    const raw = result?.resourceTemplates;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const item of raw) {
+        const r = item;
+        const uriTemplate = typeof r?.uriTemplate === "string" ? r.uriTemplate.trim() : "";
+        if (!uriTemplate || seen.has(uriTemplate))
+            continue;
+        seen.add(uriTemplate);
+        out.push({
+            server,
+            uriTemplate,
+            name: text(r?.name, 128) || uriTemplate,
+            description: text(r?.description),
+            mimeType: text(r?.mimeType, 64),
+        });
+    }
+    return [...out].sort((a, b) => a.server.localeCompare(b.server) || a.uriTemplate.localeCompare(b.uriTemplate));
+}
+/** Stable order, for the same reason the tool catalog has one: readable, diffable output. */
+export function sortResources(resources) {
+    return [...resources].sort((a, b) => a.server.localeCompare(b.server) || a.uri.localeCompare(b.uri));
+}
+/**
+ * Parse a `resources/read` payload into blocks (pure).
+ *
+ * Note the shape difference, which is easy to get wrong: `tools/call` returns `content`
+ * with typed blocks, while `resources/read` returns `contents` with entries that carry
+ * either `text` or `blob` and no `type` at all. Reusing the tool parser here would
+ * silently yield nothing.
+ */
+export function parseResourceRead(result) {
+    const raw = result?.contents;
+    if (!Array.isArray(raw))
+        return [];
+    const blocks = [];
+    for (const item of raw) {
+        const c = item;
+        if (!c || typeof c !== "object")
+            continue;
+        const mime = typeof c.mimeType === "string" ? c.mimeType : "";
+        if (typeof c.text === "string" && c.text)
+            blocks.push({ kind: "text", text: c.text });
+        else if (typeof c.blob === "string" && c.blob)
+            blocks.push({ kind: "binary", mime: mime || "application/octet-stream", base64: c.blob });
+    }
+    return blocks;
+}
+/**
+ * Render a listing for the model (pure).
+ *
+ * The URI is what it needs to pass back, so the URI leads. Templates are marked as such
+ * and shown with their placeholders intact, because a model that mistakes a template for
+ * a real URI will read `logs://{date}` and get an error it cannot interpret.
+ */
+export function renderResourceList(resources, templates) {
+    const lines = [];
+    if (resources.length > 0) {
+        lines.push("Resources (read one with read_mcp_resource):");
+        for (const r of resources.slice(0, MAX_RESOURCES_LISTED)) {
+            const bits = [r.name !== r.uri ? r.name : "", r.description, r.mimeType].filter(Boolean).join(" — ");
+            lines.push(`- [${r.server}] ${r.uri}${bits ? ` — ${bits}` : ""}`);
+        }
+        if (resources.length > MAX_RESOURCES_LISTED) {
+            lines.push(`  … and ${resources.length - MAX_RESOURCES_LISTED} more (narrow with the \`server\` argument).`);
+        }
+    }
+    if (templates.length > 0) {
+        if (lines.length > 0)
+            lines.push("");
+        lines.push("Templates (fill in the {placeholders} to build a URI, then read it):");
+        // Capped for the same reason as the resources above, which this branch was missing:
+        // the length is chosen by a third party, and an uncapped external payload is the
+        // failure mode MCP has already produced here once.
+        for (const t of templates.slice(0, MAX_RESOURCES_LISTED)) {
+            const bits = [t.name !== t.uriTemplate ? t.name : "", t.description].filter(Boolean).join(" — ");
+            lines.push(`- [${t.server}] ${t.uriTemplate}${bits ? ` — ${bits}` : ""}`);
+        }
+        if (templates.length > MAX_RESOURCES_LISTED) {
+            lines.push(`  … and ${templates.length - MAX_RESOURCES_LISTED} more (narrow with the \`server\` argument).`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=resources.js.map

package/dist/mcp/resources.js.map

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

package/dist/mcp/resultStore.js

@@ -0,0 +1,180 @@
+/**
+ * resultStore.ts — what to do with an MCP result that is too big, or is not text.
+ *
+ * A `tools/call` result goes straight into the model's context, and its size is chosen
+ * by a third party. Before this file existed there was no ceiling at all: a server that
+ * answered a query with two megabytes of JSON put two megabytes of JSON in the prompt,
+ * and a server that returned an image put a base64 blob there instead — bytes the model
+ * cannot see and pays for anyway. One such call could exhaust a turn.
+ *
+ * So oversized and binary payloads go to a file and the model gets a POINTER: a head
+ * excerpt (for text), the path, the size, and what to do next. That is strictly more
+ * useful than a truncation, because nothing is actually lost — the model can read the
+ * part it needs with the tools it already has, or run a command over the file, instead
+ * of being handed a fragment and no way to reach the rest.
+ *
+ * Files land in the project's state dir alongside `mcp-trust.json`, not in the project
+ * itself: this is scratch output from an external server, and dropping it into someone's
+ * working tree would show up in their `git status`.
+ *
+ * The decisions are pure and tested; only `spill` and `sweepOldResults` touch disk.
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { projectDir } from "../memory/store.js";
+/**
+ * Longest result text we will put in the prompt, in characters.
+ *
+ * ~7K tokens at the 3.5-chars/token proxy used everywhere else in this codebase. Chosen
+ * to be generous for a legitimately large answer (a long file listing, a verbose API
+ * response) while still being a small fraction of any model's window, since the result
+ * arrives mid-turn on top of everything else already in context.
+ */
+export const MAX_RESULT_CHARS = 24_000;
+/** How much of an oversized result to show inline before the pointer. */
+export const RESULT_HEAD_CHARS = 2_000;
+/** Delete spilled results older than this. They are scratch, not history. */
+export const RESULT_TTL_MS = 7 * 24 * 60 * 60 * 1_000;
+/** Where a project's spilled MCP results live. */
+export function resultsDir(cwd) {
+    return join(projectDir(cwd), "mcp-results");
+}
+/**
+ * File extension for a mime type (pure).
+ *
+ * The point is that the file opens with native tooling when someone double-clicks it —
+ * a `.png` rather than a `.bin`. Unknown types fall back to the subtype when it looks
+ * like an extension, because `application/x-parquet` is more useful as `.parquet` than
+ * as `.bin`.
+ */
+export function extensionForMime(mime) {
+    const type = (mime || "").split(";")[0].trim().toLowerCase();
+    const known = {
+        "text/plain": "txt",
+        "text/markdown": "md",
+        "text/html": "html",
+        "text/csv": "csv",
+        "text/xml": "xml",
+        "application/json": "json",
+        "application/xml": "xml",
+        "application/pdf": "pdf",
+        "application/zip": "zip",
+        "application/octet-stream": "bin",
+        "image/png": "png",
+        "image/jpeg": "jpg",
+        "image/gif": "gif",
+        "image/webp": "webp",
+        "image/svg+xml": "svg",
+        "audio/wav": "wav",
+        "audio/mpeg": "mp3",
+        "audio/ogg": "ogg",
+        "video/mp4": "mp4",
+    };
+    if (known[type])
+        return known[type];
+    const subtype = type.split("/")[1] ?? "";
+    const cleaned = subtype.replace(/^x[-.]/, "").replace(/\+.*$/, "").replace(/[^a-z0-9]/g, "");
+    return cleaned && cleaned.length <= 8 ? cleaned : "bin";
+}
+/** A filesystem-safe fragment of a server or tool name (pure). */
+export function safeSlug(value) {
+    return (value || "x").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 32) || "x";
+}
+/**
+ * Build the filename for one spilled result (pure).
+ *
+ * Named after what produced it, so a directory of these is readable rather than a pile
+ * of hashes. The stamp keeps two calls to the same tool from overwriting each other.
+ */
+export function spillFileName(server, tool, mime, stamp, nonce) {
+    return `${safeSlug(server)}-${safeSlug(tool)}-${stamp}-${nonce}.${extensionForMime(mime)}`;
+}
+/** Human byte count for the pointer line (pure). */
+export function humanSize(bytes) {
+    if (bytes < 1_024)
+        return `${bytes} B`;
+    if (bytes < 1_024 * 1_024)
+        return `${(bytes / 1_024).toFixed(1)} KB`;
+    return `${(bytes / (1_024 * 1_024)).toFixed(1)} MB`;
+}
+/**
+ * Is this text too big to hand to the model whole (pure)?
+ *
+ * Its own function so the threshold is testable and so callers cannot each invent their
+ * own idea of "too big".
+ */
+export function isOversized(text, max = MAX_RESULT_CHARS) {
+    return text.length > max;
+}
+/**
+ * What the model sees in place of an oversized result (pure).
+ *
+ * Deliberately a beginning plus instructions, not a middle-out truncation: the head of a
+ * result is nearly always the part that says what it is, and the model needs to know
+ * both that there is more and exactly how to get it. Saying "truncated" without a path
+ * is how a model ends up guessing at content it could have read.
+ */
+export function oversizedPointer(text, path, head = RESULT_HEAD_CHARS) {
+    return (`${text.slice(0, head)}\n\n` +
+        `[Result truncated here — it was ${humanSize(Buffer.byteLength(text, "utf8"))} ` +
+        `(${text.length} characters) and the whole of it is saved at:\n${path}\n` +
+        `Nothing was lost: read that file (or grep it) for the parts you need.]`);
+}
+/** What the model sees in place of a binary block (pure). */
+export function binaryPointer(mime, bytes, path) {
+    return (`[${mime || "binary"} content, ${humanSize(bytes)}, saved to:\n${path}\n` +
+        `It is binary, so do not try to read it as text — pass the path to a tool that ` +
+        `handles that format, or give it to the user.]`);
+}
+/**
+ * Write one payload to the results dir and return its path.
+ *
+ * Best-effort: a failed write returns null and the caller falls back to describing the
+ * content rather than storing it. A server's oversized answer must not be able to fail
+ * a turn through our own disk handling.
+ */
+export async function spill(cwd, server, tool, mime, body) {
+    try {
+        const dir = resultsDir(cwd);
+        await fs.mkdir(dir, { recursive: true });
+        const nonce = Math.random().toString(36).slice(2, 8);
+        const path = join(dir, spillFileName(server, tool, mime, Date.now(), nonce));
+        await fs.writeFile(path, body);
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete spilled results past their TTL.
+ *
+ * Called once per session rather than on a timer: this directory only grows when a
+ * server returns something large, so sweeping on the way in is enough, and it keeps the
+ * whole mechanism free of background work.
+ */
+export async function sweepOldResults(cwd, ttlMs = RESULT_TTL_MS, now = Date.now()) {
+    try {
+        const dir = resultsDir(cwd);
+        const names = await fs.readdir(dir);
+        let removed = 0;
+        for (const name of names) {
+            const path = join(dir, name);
+            try {
+                const stat = await fs.stat(path);
+                if (now - stat.mtimeMs > ttlMs) {
+                    await fs.rm(path, { force: true });
+                    removed++;
+                }
+            }
+            catch {
+                // Raced with something else, or not ours to delete. Skip it.
+            }
+        }
+        return removed;
+    }
+    catch {
+        return 0; // no directory yet, which is the normal case
+    }
+}
+//# sourceMappingURL=resultStore.js.map

package/dist/mcp/resultStore.js.map

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

package/dist/mcp/subscriptions.js

@@ -0,0 +1,74 @@
+/**
+ * subscriptions.ts — staying current with a server that changes underneath us.
+ *
+ * A server's tool list is not fixed. It can gain tools when a user authenticates, lose
+ * them when a backend goes away, or change entirely on a redeploy. Before 2026-07-28 a
+ * client learned about that through `resources/subscribe` and an always-on GET channel;
+ * both are gone. In their place is `subscriptions/listen`: ONE long-lived stream that
+ * the client opts into by naming the change types it cares about.
+ *
+ * Opting in is the whole design point. A client that subscribes to everything pays for
+ * traffic it will ignore, and — more to the point here — every `toolsListChanged` we
+ * accept means re-fetching a catalog and rewriting the tool list mid-session, which
+ * costs a prompt-cache prefix. So we ask for exactly what we can act on today.
+ *
+ * The decisions are pure so the policy is testable without a server; `connection.ts`
+ * owns the plumbing.
+ */
+/** Change types the 2026-07-28 spec defines for `subscriptions/listen`. */
+export const SUBSCRIPTION_TYPES = ["toolsListChanged", "promptsListChanged", "resourcesListChanged", "resourceSubscriptions"];
+/** The notification a server sends when its tool list moved. */
+export const TOOLS_CHANGED = "notifications/tools/list_changed";
+/**
+ * Which change types to request from a server (pure).
+ *
+ * Only what we can act on, and only where the server says the list can move. All three
+ * are actionable now: a changed tool list rebuilds the catalog (and re-runs the trust
+ * check), a changed prompt list rebuilds the slash commands, and a changed resource list
+ * invalidates a cached listing. `resourceSubscriptions` is still not requested — that is
+ * per-resource content watching, which nothing in the agent consumes.
+ *
+ * A server that advertises none of them gets no subscription at all rather than an empty
+ * one, because an empty `subscriptions/listen` still costs a held-open stream.
+ */
+export function subscriptionsFor(capabilities) {
+    const wanted = [];
+    // `listChanged: false` is a server saying its list is fixed. Believe it.
+    const declares = (key) => {
+        const cap = capabilities?.[key];
+        return Boolean(cap) && cap.listChanged !== false;
+    };
+    if (declares("tools"))
+        wanted.push("toolsListChanged");
+    if (declares("prompts"))
+        wanted.push("promptsListChanged");
+    if (declares("resources"))
+        wanted.push("resourcesListChanged");
+    return wanted;
+}
+/**
+ * Does this notification mean "your tool catalog is stale" (pure)?
+ *
+ * Matched loosely on purpose. The method name is spelled slightly differently across
+ * revisions and implementations (`notifications/tools/list_changed` vs
+ * `toolsListChanged`), and the cost of missing one is a permanently stale catalog,
+ * while the cost of an extra match is one wasted `tools/list`.
+ */
+export function isToolsChanged(method) {
+    return isListChanged(method, "tool");
+}
+/** Does this notification mean "your prompt list is stale" (pure)? */
+export function isPromptsChanged(method) {
+    return isListChanged(method, "prompt");
+}
+/** Does this notification mean "your resource list is stale" (pure)? */
+export function isResourcesChanged(method) {
+    // `resources/updated` is a different thing — one resource's CONTENT changed — and we
+    // hold no per-resource cache to invalidate, so it is deliberately not matched here.
+    return isListChanged(method, "resource");
+}
+function isListChanged(method, subject) {
+    const m = method.toLowerCase();
+    return m.includes(subject) && (m.includes("list_changed") || m.includes("listchanged"));
+}
+//# sourceMappingURL=subscriptions.js.map

package/dist/mcp/subscriptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.js","sourceRoot":"","sources":["../../src/mcp/subscriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,kBAAkB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,uBAAuB,CAAU,CAAC;AAGvI,gEAAgE;AAChE,MAAM,CAAC,MAAM,aAAa,GAAG,kCAAkC,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,YAAqC;IACpE,MAAM,MAAM,GAAuB,EAAE,CAAC;IACtC,yEAAyE;IACzE,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAW,EAAE;QACxC,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC,GAAG,CAA0C,CAAC;QACzE,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,GAAI,CAAC,WAAW,KAAK,KAAK,CAAC;IACpD,CAAC,CAAC;IACF,IAAI,QAAQ,CAAC,OAAO,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;IACvD,IAAI,QAAQ,CAAC,SAAS,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IAC3D,IAAI,QAAQ,CAAC,WAAW,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IAC/D,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACvC,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AACzC,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,qFAAqF;IACrF,oFAAoF;IACpF,OAAO,aAAa,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAC3C,CAAC;AAED,SAAS,aAAa,CAAC,MAAc,EAAE,OAAe;IACpD,MAAM,CAAC,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IAC/B,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AAC1F,CAAC"}

package/dist/mcp/transport/headerValue.js

@@ -0,0 +1,40 @@
+/**
+ * headerValue.ts — putting an arbitrary body value into an HTTP header value.
+ *
+ * Streamable HTTP mirrors selected body fields into headers so intermediaries can route
+ * without parsing the body. Those fields are written by third parties and are not
+ * constrained to anything a header can carry: a tool name is only SHOULD-constrained to
+ * safe characters, a resource URI is not constrained at all, and a tool argument can be
+ * any string a user typed. The spec's answer is a sentinel encoding rather than a
+ * rejection, so this is the one place that decides when to reach for it.
+ *
+ * Its own module because two unrelated callers need it — the transport, for `Mcp-Name`,
+ * and the catalog layer, for `Mcp-Param-*` — and the second should not have to import a
+ * fetch client to encode a string.
+ */
+/**
+ * A value that needs no rescuing: visible ASCII, space or tab only (RFC 9110 field
+ * values), no leading or trailing whitespace, and nothing that could be mistaken for an
+ * already-encoded value.
+ */
+function isHeaderSafe(value) {
+    if (/[^\t\x20-\x7e]/.test(value))
+        return false;
+    if (/^[\t\x20]|[\t\x20]$/.test(value))
+        return false;
+    return !/^=\?base64\?[\s\S]*\?=$/.test(value);
+}
+/**
+ * Mirror one body value into a header value (pure).
+ *
+ * Anything outside the safe set travels in the spec's sentinel `=?base64?...?=`, which
+ * servers decode before comparing the header against the body. A plain value that merely
+ * LOOKS like the sentinel is encoded too: otherwise a server would decode a value the
+ * client never encoded, compare the wrong bytes, and reject a legitimate request.
+ */
+export function encodeHeaderValue(value) {
+    if (isHeaderSafe(value))
+        return value;
+    return `=?base64?${Buffer.from(value, "utf8").toString("base64")}?=`;
+}
+//# sourceMappingURL=headerValue.js.map

package/dist/mcp/transport/headerValue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headerValue.js","sourceRoot":"","sources":["../../../src/mcp/transport/headerValue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;GAIG;AACH,SAAS,YAAY,CAAC,KAAa;IACjC,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/C,IAAI,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACpD,OAAO,CAAC,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,YAAY,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,YAAY,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;AACvE,CAAC"}