ctxr-cli 0.30.0 → 0.32.0

package/dist/core/mcp/tools/find.js

@@ -0,0 +1,136 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { joinBaseUrl, noteRoute } from '../../browse/page-url.js';
+import { catalogSectionsFor, sectionForNote } from '../../catalog/model.js';
+import { isUnderAnyPrefix } from '../../fs/prefix.js';
+import { listCaptures, listNotes } from '../../notes/list.js';
+import { readCatalogGlosses } from '../../records.js';
+import { ToolRefusal } from '../jsonrpc.js';
+/**
+ * remote-access spec, *`find` stands in for a client's own content
+ * matching*; context-retrieval's bounded exception. Literal,
+ * case-insensitive substring matching over the notes the store's
+ * enumeration admits, in path order, with no score. Captures — inbox files
+ * on the default branch and on pending `capture/` branches — come back in
+ * `unfiled`, never among the notes (context-ingest's exception, design.md
+ * D6). With no text, the catalog as a map to pick selectors from.
+ */
+export const MAX_LINES_PER_HIT = 3;
+export const MAX_LINE_CHARS = 240;
+export const DEFAULT_MAX_MATCHES = 25;
+export const DEFAULT_MAX_MAP_NOTES = 500;
+export const MAX_RESULTS = 1000;
+const MAX_TEXT_CHARS = 200;
+/**
+ * Plain on purpose: type, description and required only. Some clients (Gemini) accept a narrow subset of JSON
+ * Schema and drop a tool whose schema uses more; every limit is enforced by `parseFindArgs` instead.
+ */
+export const FIND_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        text: { type: 'string', description: 'Literal text to look for, case-insensitive. Omit it to get the map of the store instead.' },
+        under: { type: 'string', description: 'Only look under this folder of the store, e.g. "projects/".' },
+        max: { type: 'integer', description: `How many notes to return (default ${DEFAULT_MAX_MATCHES} when matching, ${DEFAULT_MAX_MAP_NOTES} for the map).` },
+    },
+};
+export function parseFindArgs(args) {
+    const out = {};
+    if (args.text !== undefined && args.text !== null) {
+        if (typeof args.text !== 'string')
+            throw new ToolRefusal('mcp.invalid_arguments', '"text" must be a string.');
+        if (args.text.length > MAX_TEXT_CHARS)
+            throw new ToolRefusal('mcp.invalid_arguments', `"text" is at most ${MAX_TEXT_CHARS} characters.`);
+        if (args.text.trim().length > 0)
+            out.text = args.text.trim();
+    }
+    if (args.under !== undefined && args.under !== null) {
+        if (typeof args.under !== 'string')
+            throw new ToolRefusal('mcp.invalid_arguments', '"under" must be a string.');
+        const under = args.under.trim().replace(/^\.?\/+/, '');
+        if (under.length > 0)
+            out.under = under;
+    }
+    if (args.max !== undefined && args.max !== null) {
+        if (typeof args.max !== 'number' || !Number.isInteger(args.max) || args.max < 1 || args.max > MAX_RESULTS) {
+            throw new ToolRefusal('mcp.invalid_arguments', `"max" must be a whole number from 1 to ${MAX_RESULTS}.`);
+        }
+        out.max = args.max;
+    }
+    return out;
+}
+function matchLines(text, needle) {
+    const lines = [];
+    let count = 0;
+    const all = text.split(/\r?\n/);
+    for (let i = 0; i < all.length; i += 1) {
+        const line = all[i];
+        if (!line.toLowerCase().includes(needle))
+            continue;
+        count += 1;
+        if (lines.length < MAX_LINES_PER_HIT) {
+            lines.push({ line: i + 1, text: line.length > MAX_LINE_CHARS ? `${line.slice(0, MAX_LINE_CHARS - 1)}…` : line });
+        }
+    }
+    return { lines, count };
+}
+const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+/** `baseUrl` is `serve.base_url` from the configuration `serve` loaded: links point at the browsing surface it answers. */
+export async function find(snapshot, args, baseUrl) {
+    const store = snapshot.store;
+    const linkFor = (notePath) => joinBaseUrl(baseUrl, noteRoute(notePath));
+    const glosses = await readCatalogGlosses(store);
+    const scope = (p) => args.under === undefined || isUnderAnyPrefix(p, [args.under]);
+    const notes = (await listNotes(store.root, store.config)).filter((n) => scope(n.path)).sort(byPath);
+    if (args.text === undefined) {
+        const max = args.max ?? DEFAULT_MAX_MAP_NOTES;
+        const sections = catalogSectionsFor(store.config);
+        const grouped = new Map(sections.map((s) => [s.id, []]));
+        let listed = 0;
+        for (const note of notes) {
+            if (listed >= max)
+                break;
+            grouped.get(sectionForNote(sections, note.path).id).push({ path: note.path, gloss: glosses.get(note.path) ?? '', url: linkFor(note.path) });
+            listed += 1;
+        }
+        return {
+            mode: 'map',
+            sections: [...grouped.entries()].filter(([, entries]) => entries.length > 0).map(([id, entries]) => ({ id, notes: entries })),
+            notes_omitted: notes.length - listed,
+        };
+    }
+    const needle = args.text.toLowerCase();
+    const max = args.max ?? DEFAULT_MAX_MATCHES;
+    // Raw file text, frontmatter included, so line numbers are the file's own — what grep would report.
+    const noteHits = [];
+    for (const note of notes) {
+        const { lines, count } = matchLines(await readFile(path.join(store.root, note.path), 'utf8'), needle);
+        if (count > 0)
+            noteHits.push({ path: note.path, gloss: glosses.get(note.path) ?? '', lines, matching_lines: count, url: linkFor(note.path) });
+    }
+    const inbox = store.config.ingest.inbox_path;
+    const unfiled = [];
+    for (const capture of (await listCaptures(store.root, store.config)).sort(byPath)) {
+        if (!isUnderAnyPrefix(capture.path, [inbox]) || !scope(capture.path))
+            continue;
+        const { lines, count } = matchLines(await readFile(path.join(store.root, capture.path), 'utf8'), needle);
+        if (count > 0)
+            unfiled.push({ path: capture.path, lines, matching_lines: count, pending_merge: false, branch: null });
+    }
+    const pending = [...snapshot.pending].sort((a, b) => byPath(a, b) || (a.branch < b.branch ? -1 : 1));
+    for (const capture of pending) {
+        if (!scope(capture.path))
+            continue;
+        const { lines, count } = matchLines(capture.text, needle);
+        if (count > 0)
+            unfiled.push({ path: capture.path, lines, matching_lines: count, pending_merge: true, branch: capture.branch });
+    }
+    return {
+        mode: 'match',
+        text: args.text,
+        notes: noteHits.slice(0, max),
+        notes_omitted: Math.max(0, noteHits.length - max),
+        unfiled: unfiled.slice(0, max),
+        unfiled_omitted: Math.max(0, unfiled.length - max),
+    };
+}
+//# sourceMappingURL=find.js.map

package/dist/core/mcp/tools/find.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find.js","sourceRoot":"","sources":["../../../../src/core/mcp/tools/find.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AACnC,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAClC,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AACtC,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AACzC,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC;AAChC,MAAM,cAAc,GAAG,GAAG,CAAC;AAiC3B;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,0FAA0F,EAAE;QACjI,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,6DAA6D,EAAE;QACrG,GAAG,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,qCAAqC,mBAAmB,mBAAmB,qBAAqB,gBAAgB,EAAE;KACxJ;CACO,CAAC;AAEX,MAAM,UAAU,aAAa,CAAC,IAA6B;IACzD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAClD,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,IAAI,WAAW,CAAC,uBAAuB,EAAE,0BAA0B,CAAC,CAAC;QAC9G,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,cAAc;YAAE,MAAM,IAAI,WAAW,CAAC,uBAAuB,EAAE,qBAAqB,cAAc,cAAc,CAAC,CAAC;QACzI,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAC/D,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QACpD,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;YAAE,MAAM,IAAI,WAAW,CAAC,uBAAuB,EAAE,2BAA2B,CAAC,CAAC;QAChH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACvD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;IAC1C,CAAC;IACD,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;QAChD,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,GAAG,WAAW,EAAE,CAAC;YAC1G,MAAM,IAAI,WAAW,CAAC,uBAAuB,EAAE,0CAA0C,WAAW,GAAG,CAAC,CAAC;QAC3G,CAAC;QACD,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;IACrB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,UAAU,CAAC,IAAY,EAAE,MAAc;IAC9C,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAE,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,SAAS;QACnD,KAAK,IAAI,CAAC,CAAC;QACX,IAAI,KAAK,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACnH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,MAAM,GAAG,CAAC,CAAmB,EAAE,CAAmB,EAAU,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEtH,2HAA2H;AAC3H,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,QAAkB,EAAE,IAAc,EAAE,OAA2B;IACxF,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;IAC7B,MAAM,OAAO,GAAG,CAAC,QAAgB,EAAiB,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/F,MAAM,OAAO,GAAG,MAAM,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,CAAC,CAAS,EAAW,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,gBAAgB,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACpG,MAAM,KAAK,GAAG,CAAC,MAAM,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAEpG,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,qBAAqB,CAAC;QAC9C,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAgE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QACxH,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,MAAM,IAAI,GAAG;gBAAE,MAAM;YACzB,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC7I,MAAM,IAAI,CAAC,CAAC;QACd,CAAC;QACD,OAAO;YACL,IAAI,EAAE,KAAK;YACX,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;YAC7H,aAAa,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM;SACrC,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IACvC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,mBAAmB,CAAC;IAE5C,oGAAoG;IACpG,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,UAAU,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;QACtG,IAAI,KAAK,GAAG,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChJ,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC;IAC7C,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,KAAK,MAAM,OAAO,IAAI,CAAC,MAAM,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAClF,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,SAAS;QAC/E,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,UAAU,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;QACzG,IAAI,KAAK,GAAG,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACxH,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrG,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;QAC9B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,SAAS;QACnC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC1D,IAAI,KAAK,GAAG,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACjI,CAAC;IAED,OAAO;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QAC7B,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,GAAG,CAAC;QACjD,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QAC9B,eAAe,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC;KACnD,CAAC;AACJ,CAAC"}

package/dist/core/mcp/tools/gather.d.ts

@@ -0,0 +1,88 @@
+import { type GatherOutcome, type GatherResult } from '../../retrieval/pass.js';
+import type { Snapshot } from '../sync.js';
+/**
+ * remote-access spec, *`gather` returns the retrieval pass with the bodies a
+ * client cannot read itself* (design.md D8). The pass runs unchanged against
+ * the view's notes and the view's own graph, and still returns no body; this
+ * attaches them afterwards, to a prefix of the pass's order, within a byte
+ * budget — so the cap never reorders anything, exactly as the pass's own cap.
+ */
+export declare const DEFAULT_GATHER_MAX_BYTES = 60000;
+export interface GatherArgs {
+    seeds?: string[];
+    sections?: string[];
+    under?: string[];
+    entities?: string[];
+    hops?: number;
+    direction?: 'in' | 'out' | 'both';
+    type?: string;
+    max_notes?: number;
+}
+export interface GatheredNote extends GatherResult {
+    /** The note's text, frontmatter included; null once the byte budget is spent. */
+    body: string | null;
+    /** Set on the first note only, when it alone exceeded the budget and was cut to it. */
+    body_clipped?: true;
+}
+export interface GatherToolResult extends Omit<GatherOutcome, 'notes'> {
+    notes: GatheredNote[];
+    bodies: {
+        max_bytes: number;
+        returned: number;
+        omitted: number;
+    };
+}
+/** Plain on purpose (see FIND_INPUT_SCHEMA): `parseGatherArgs` enforces every limit. */
+export declare const GATHER_INPUT_SCHEMA: {
+    readonly type: 'object';
+    readonly properties: {
+        readonly seeds: {
+            readonly type: 'array';
+            readonly items: {
+                readonly type: 'string';
+            };
+            readonly description: 'Note paths to start from, usually from find.';
+        };
+        readonly sections: {
+            readonly type: 'array';
+            readonly items: {
+                readonly type: 'string';
+            };
+            readonly description: 'Catalog section ids whose notes to start from (find with no text lists them).';
+        };
+        readonly under: {
+            readonly type: 'array';
+            readonly items: {
+                readonly type: 'string';
+            };
+            readonly description: 'Folders whose notes to start from, e.g. "projects/".';
+        };
+        readonly entities: {
+            readonly type: 'array';
+            readonly items: {
+                readonly type: 'string';
+            };
+            readonly description: 'Note paths whose backlinks to start from: every note linking to them.';
+        };
+        readonly hops: {
+            readonly type: 'integer';
+            readonly description: 'How many links to follow out from the starting notes (default 1; 0 returns only them).';
+        };
+        readonly direction: {
+            readonly type: 'string';
+            readonly enum: readonly ['in', 'out', 'both'];
+            readonly description: 'Follow links pointing out, in, or both (default both).';
+        };
+        readonly type: {
+            readonly type: 'string';
+            readonly description: 'Follow only links of this relation type.';
+        };
+        readonly max_notes: {
+            readonly type: 'integer';
+            readonly description: 'Cap on how many notes to return; the omitted count is reported.';
+        };
+    };
+};
+export declare function parseGatherArgs(args: Record<string, unknown>): GatherArgs;
+export declare function gatherWithBodies(snapshot: Snapshot, args: GatherArgs, maxBytes?: number): Promise<GatherToolResult>;
+//# sourceMappingURL=gather.d.ts.map

package/dist/core/mcp/tools/gather.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gather.d.ts","sourceRoot":"","sources":["../../../../src/core/mcp/tools/gather.ts"],"names":[],"mappings":"AAKA,OAAO,EAAqB,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEnG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;GAMG;AAEH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,MAAM,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,iFAAiF;IACjF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,uFAAuF;IACvF,YAAY,CAAC,EAAE,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC;IACpE,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAClE;AAED,wFAAwF;AACxF,eAAO,MAAM,mBAAmB;aAC9B,IAAI,EAAE,QAAQ;aACd,UAAU;iBACR,KAAK;qBAAI,IAAI,EAAE,OAAO;qBAAE,KAAK;yBAAI,IAAI,EAAE,QAAQ;;qBAAI,WAAW,EAAE,8CAA8C;;iBAC9G,QAAQ;qBAAI,IAAI,EAAE,OAAO;qBAAE,KAAK;yBAAI,IAAI,EAAE,QAAQ;;qBAAI,WAAW,EAAE,+EAA+E;;iBAClJ,KAAK;qBAAI,IAAI,EAAE,OAAO;qBAAE,KAAK;yBAAI,IAAI,EAAE,QAAQ;;qBAAI,WAAW,EAAE,sDAAsD;;iBACtH,QAAQ;qBAAI,IAAI,EAAE,OAAO;qBAAE,KAAK;yBAAI,IAAI,EAAE,QAAQ;;qBAAI,WAAW,EAAE,uEAAuE;;iBAC1I,IAAI;qBAAI,IAAI,EAAE,SAAS;qBAAE,WAAW,EAAE,wFAAwF;;iBAC9H,SAAS;qBAAI,IAAI,EAAE,QAAQ;qBAAE,IAAI,YAAG,IAAI,EAAE,KAAK,EAAE,MAAM;qBAAG,WAAW,EAAE,wDAAwD;;iBAC/H,IAAI;qBAAI,IAAI,EAAE,QAAQ;qBAAE,WAAW,EAAE,0CAA0C;;iBAC/E,SAAS;qBAAI,IAAI,EAAE,SAAS;qBAAE,WAAW,EAAE,iEAAiE;;;CAEtG,CAAC;AAqBX,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAuBzE;AAED,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,SAA2B,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiD3I"}

package/dist/core/mcp/tools/gather.js

@@ -0,0 +1,123 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isUnderAnyPrefix } from '../../fs/prefix.js';
+import { readAdmittedGraph } from '../../graph/persist.js';
+import { listNotes } from '../../notes/list.js';
+import { gather as runPass } from '../../retrieval/pass.js';
+import { ToolRefusal } from '../jsonrpc.js';
+/**
+ * remote-access spec, *`gather` returns the retrieval pass with the bodies a
+ * client cannot read itself* (design.md D8). The pass runs unchanged against
+ * the view's notes and the view's own graph, and still returns no body; this
+ * attaches them afterwards, to a prefix of the pass's order, within a byte
+ * budget — so the cap never reorders anything, exactly as the pass's own cap.
+ */
+export const DEFAULT_GATHER_MAX_BYTES = 60_000;
+/** Plain on purpose (see FIND_INPUT_SCHEMA): `parseGatherArgs` enforces every limit. */
+export const GATHER_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        seeds: { type: 'array', items: { type: 'string' }, description: 'Note paths to start from, usually from find.' },
+        sections: { type: 'array', items: { type: 'string' }, description: 'Catalog section ids whose notes to start from (find with no text lists them).' },
+        under: { type: 'array', items: { type: 'string' }, description: 'Folders whose notes to start from, e.g. "projects/".' },
+        entities: { type: 'array', items: { type: 'string' }, description: 'Note paths whose backlinks to start from: every note linking to them.' },
+        hops: { type: 'integer', description: 'How many links to follow out from the starting notes (default 1; 0 returns only them).' },
+        direction: { type: 'string', enum: ['in', 'out', 'both'], description: 'Follow links pointing out, in, or both (default both).' },
+        type: { type: 'string', description: 'Follow only links of this relation type.' },
+        max_notes: { type: 'integer', description: 'Cap on how many notes to return; the omitted count is reported.' },
+    },
+};
+function stringList(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    const list = typeof value === 'string' ? [value] : value;
+    if (!Array.isArray(list) || !list.every((v) => typeof v === 'string' && v.trim().length > 0)) {
+        throw new ToolRefusal('mcp.invalid_arguments', `"${key}" must be a list of non-empty strings.`);
+    }
+    return list.map((v) => v.trim().replace(/^\.?\/+/, ''));
+}
+function wholeNumber(args, key, min, max) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < min || value > max) {
+        throw new ToolRefusal('mcp.invalid_arguments', `"${key}" must be a whole number from ${min} to ${max}.`);
+    }
+    return value;
+}
+export function parseGatherArgs(args) {
+    const out = {
+        seeds: stringList(args, 'seeds'),
+        sections: stringList(args, 'sections'),
+        under: stringList(args, 'under'),
+        entities: stringList(args, 'entities'),
+        hops: wholeNumber(args, 'hops', 0, 5),
+        max_notes: wholeNumber(args, 'max_notes', 1, 500),
+    };
+    if (args.direction !== undefined && args.direction !== null) {
+        if (args.direction !== 'in' && args.direction !== 'out' && args.direction !== 'both') {
+            throw new ToolRefusal('mcp.invalid_arguments', '"direction" is one of in, out, both.');
+        }
+        out.direction = args.direction;
+    }
+    if (args.type !== undefined && args.type !== null) {
+        if (typeof args.type !== 'string')
+            throw new ToolRefusal('mcp.invalid_arguments', '"type" must be a string.');
+        out.type = args.type;
+    }
+    if ([out.seeds, out.sections, out.under, out.entities].every((l) => l === undefined || l.length === 0)) {
+        throw new ToolRefusal('mcp.invalid_arguments', 'Name at least one starting point: seeds, sections, under or entities. Use find first to get note paths.');
+    }
+    return out;
+}
+export async function gatherWithBodies(snapshot, args, maxBytes = DEFAULT_GATHER_MAX_BYTES) {
+    const store = snapshot.store;
+    const captureRoot = store.config.ingest.capture_root;
+    for (const seed of args.seeds ?? []) {
+        if (isUnderAnyPrefix(seed, [captureRoot])) {
+            throw new ToolRefusal('mcp.capture_not_filed', `"${seed}" is a capture that has not been filed into a note yet, so it cannot start a gather; read it with Read instead.`, { path: seed });
+        }
+    }
+    const notes = await listNotes(store.root, store.config);
+    const graph = await readAdmittedGraph(store);
+    const pass = await runPass(store, notes, graph, {
+        seeds: args.seeds,
+        sections: args.sections,
+        under: args.under,
+        entities: args.entities,
+        hops: args.hops,
+        direction: args.direction,
+        type: args.type,
+        maxNotes: args.max_notes,
+    });
+    let spent = 0;
+    let open = true;
+    let returned = 0;
+    const withBodies = [];
+    for (const [index, note] of pass.notes.entries()) {
+        if (!open) {
+            withBodies.push({ ...note, body: null });
+            continue;
+        }
+        const text = await readFile(path.join(store.root, note.path), 'utf8');
+        const bytes = Buffer.byteLength(text, 'utf8');
+        if (spent + bytes <= maxBytes) {
+            spent += bytes;
+            returned += 1;
+            withBodies.push({ ...note, body: text });
+        }
+        else if (index === 0) {
+            // A call never comes back with no text at all: the first note is cut to the budget and says so.
+            withBodies.push({ ...note, body: Buffer.from(text, 'utf8').subarray(0, maxBytes).toString('utf8'), body_clipped: true });
+            returned += 1;
+            open = false;
+        }
+        else {
+            withBodies.push({ ...note, body: null });
+            open = false;
+        }
+    }
+    return { ...pass, notes: withBodies, bodies: { max_bytes: maxBytes, returned, omitted: pass.notes.length - returned } };
+}
+//# sourceMappingURL=gather.js.map

package/dist/core/mcp/tools/gather.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gather.js","sourceRoot":"","sources":["../../../../src/core/mcp/tools/gather.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,MAAM,IAAI,OAAO,EAAyC,MAAM,yBAAyB,CAAC;AACnG,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAyB/C,wFAAwF;AACxF,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,8CAA8C,EAAE;QAChH,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,+EAA+E,EAAE;QACpJ,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,sDAAsD,EAAE;QACxH,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,uEAAuE,EAAE;QAC5I,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,wFAAwF,EAAE;QAChI,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,wDAAwD,EAAE;QACjI,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,0CAA0C,EAAE;QACjF,SAAS,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,iEAAiE,EAAE;KAC/G;CACO,CAAC;AAEX,SAAS,UAAU,CAAC,IAA6B,EAAE,GAAW;IAC5D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACzD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QAC7F,MAAM,IAAI,WAAW,CAAC,uBAAuB,EAAE,IAAI,GAAG,wCAAwC,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,WAAW,CAAC,IAA6B,EAAE,GAAW,EAAE,GAAW,EAAE,GAAW;IACvF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,GAAG,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;QACxF,MAAM,IAAI,WAAW,CAAC,uBAAuB,EAAE,IAAI,GAAG,iCAAiC,GAAG,OAAO,GAAG,GAAG,CAAC,CAAC;IAC3G,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAA6B;IAC3D,MAAM,GAAG,GAAe;QACtB,KAAK,EAAE,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC;QAChC,QAAQ,EAAE,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC;QACtC,KAAK,EAAE,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC;QAChC,QAAQ,EAAE,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC;QACtC,IAAI,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;QACrC,SAAS,EAAE,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,GAAG,CAAC;KAClD,CAAC;IACF,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAC5D,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,SAAS,KAAK,KAAK,IAAI,IAAI,CAAC,SAAS,KAAK,MAAM,EAAE,CAAC;YACrF,MAAM,IAAI,WAAW,CAAC,uBAAuB,EAAE,sCAAsC,CAAC,CAAC;QACzF,CAAC;QACD,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACjC,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAClD,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,IAAI,WAAW,CAAC,uBAAuB,EAAE,0BAA0B,CAAC,CAAC;QAC9G,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACvB,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QACvG,MAAM,IAAI,WAAW,CAAC,uBAAuB,EAAE,yGAAyG,CAAC,CAAC;IAC5J,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,QAAkB,EAAE,IAAgB,EAAE,QAAQ,GAAG,wBAAwB;IAC9G,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;IAC7B,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC;IACrD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;QACpC,IAAI,gBAAgB,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,WAAW,CAAC,uBAAuB,EAAE,IAAI,IAAI,iHAAiH,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5L,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE;QAC9C,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,QAAQ,EAAE,IAAI,CAAC,SAAS;KACzB,CAAC,CAAC;IAEH,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,MAAM,UAAU,GAAmB,EAAE,CAAC;IACtC,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QACjD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACzC,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;QACtE,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC9C,IAAI,KAAK,GAAG,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC9B,KAAK,IAAI,KAAK,CAAC;YACf,QAAQ,IAAI,CAAC,CAAC;YACd,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,CAAC;aAAM,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YACvB,gGAAgG;YAChG,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;YACzH,QAAQ,IAAI,CAAC,CAAC;YACd,IAAI,GAAG,KAAK,CAAC;QACf,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACzC,IAAI,GAAG,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,QAAQ,EAAE,EAAE,CAAC;AAC1H,CAAC"}

package/dist/core/mcp/tools/index.d.ts

@@ -0,0 +1,21 @@
+import type { ToolDefinition } from '../jsonrpc.js';
+import type { Principal } from '../oauth.js';
+import type { Mutex, WriteDeps } from '../sessions.js';
+import type { McpView, SyncDeps } from '../sync.js';
+/**
+ * The remote surface's tool set and the prose that describes it
+ * (templates/mcp/, shipped-prose-lives-in-templates). Built per request from
+ * the server's current state. Reads go through `view.read`, so each sees one
+ * commit and names it; writes go through the one mutex (design.md D9, D13).
+ */
+export declare function serverInstructions(storeName: string): string;
+export interface ToolContext {
+    view: McpView;
+    syncDeps: SyncDeps;
+    write: WriteDeps;
+    mutex: Mutex;
+    /** `serve.base_url` from the loaded configuration. */
+    baseUrl: string | undefined;
+}
+export declare function buildTools(ctx: ToolContext): ToolDefinition<Principal>[];
+//# sourceMappingURL=index.d.ts.map

package/dist/core/mcp/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/mcp/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAoBpD;;;;;GAKG;AAEH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,sDAAsD;IACtD,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAWD,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,cAAc,CAAC,SAAS,CAAC,EAAE,CAuGxE"}

package/dist/core/mcp/tools/index.js

@@ -0,0 +1,129 @@
+import { packagedTemplate } from '../../templates.js';
+import { asToolRefusal, capture, CAPTURE_INPUT_SCHEMA, parseCaptureArgs } from './capture.js';
+import { EDIT_INPUT_SCHEMA, editTool, parseEditArgs, parseWriteArgs, WRITE_INPUT_SCHEMA, writeTool } from './edit.js';
+import { GLOB_INPUT_SCHEMA, globTool, GREP_INPUT_SCHEMA, grepTool, parseGlobArgs, parseGrepArgs, parseReadArgs, READ_INPUT_SCHEMA, readTool, renderGlob, renderGrep, renderRead, } from './files.js';
+import { find, FIND_INPUT_SCHEMA, parseFindArgs } from './find.js';
+import { GATHER_INPUT_SCHEMA, gatherWithBodies, parseGatherArgs } from './gather.js';
+/**
+ * The remote surface's tool set and the prose that describes it
+ * (templates/mcp/, shipped-prose-lives-in-templates). Built per request from
+ * the server's current state. Reads go through `view.read`, so each sees one
+ * commit and names it; writes go through the one mutex (design.md D9, D13).
+ */
+export function serverInstructions(storeName) {
+    return packagedTemplate('mcp', 'server-instructions').replaceAll('__STORE_NAME__', storeName);
+}
+/** Writes surface a WriteRefusal as a refusal the client model can read. */
+async function writing(ctx, fn) {
+    try {
+        return await ctx.mutex.run(fn);
+    }
+    catch (err) {
+        throw asToolRefusal(err);
+    }
+}
+export function buildTools(ctx) {
+    const read = (fn) => ctx.view.read(ctx.syncDeps, fn);
+    return [
+        {
+            name: 'find',
+            title: 'Find in the store',
+            description: packagedTemplate('mcp', 'find'),
+            inputSchema: FIND_INPUT_SCHEMA,
+            scope: 'read',
+            readOnly: true,
+            run: (args) => {
+                const parsed = parseFindArgs(args);
+                return read((snapshot) => find(snapshot, parsed, ctx.baseUrl));
+            },
+        },
+        {
+            name: 'gather',
+            title: 'Gather related notes',
+            description: packagedTemplate('mcp', 'gather'),
+            inputSchema: GATHER_INPUT_SCHEMA,
+            scope: 'read',
+            readOnly: true,
+            run: (args) => {
+                const parsed = parseGatherArgs(args);
+                return read((snapshot) => gatherWithBodies(snapshot, parsed));
+            },
+        },
+        {
+            name: 'Read',
+            title: 'Read a file',
+            description: packagedTemplate('mcp', 'Read'),
+            inputSchema: READ_INPUT_SCHEMA,
+            scope: 'read',
+            readOnly: true,
+            render: renderRead,
+            run: (args, principal) => {
+                const parsed = parseReadArgs(args);
+                return read((snapshot) => readTool(snapshot, ctx.write, principal.email, parsed));
+            },
+        },
+        {
+            name: 'Grep',
+            title: 'Search file contents',
+            description: packagedTemplate('mcp', 'Grep'),
+            inputSchema: GREP_INPUT_SCHEMA,
+            scope: 'read',
+            readOnly: true,
+            render: renderGrep,
+            run: (args) => {
+                const parsed = parseGrepArgs(args);
+                return read((snapshot) => grepTool(snapshot, parsed));
+            },
+        },
+        {
+            name: 'Glob',
+            title: 'Find files by name',
+            description: packagedTemplate('mcp', 'Glob'),
+            inputSchema: GLOB_INPUT_SCHEMA,
+            scope: 'read',
+            readOnly: true,
+            render: renderGlob,
+            run: (args) => {
+                const parsed = parseGlobArgs(args);
+                return read((snapshot) => globTool(snapshot, parsed));
+            },
+        },
+        {
+            name: 'capture',
+            title: 'Capture into the store',
+            description: packagedTemplate('mcp', 'capture'),
+            inputSchema: CAPTURE_INPUT_SCHEMA,
+            scope: 'capture',
+            readOnly: false,
+            run: (args, principal) => {
+                const parsed = parseCaptureArgs(args);
+                return writing(ctx, () => capture({ view: ctx.view, syncDeps: ctx.syncDeps, write: ctx.write }, principal.email, parsed));
+            },
+        },
+        {
+            name: 'Edit',
+            title: 'Edit a note',
+            description: packagedTemplate('mcp', 'Edit'),
+            inputSchema: EDIT_INPUT_SCHEMA,
+            scope: 'edit',
+            readOnly: false,
+            run: (args, principal) => {
+                const parsed = parseEditArgs(args);
+                return writing(ctx, () => editTool({ view: ctx.view, syncDeps: ctx.syncDeps, write: ctx.write }, principal.email, parsed));
+            },
+        },
+        {
+            name: 'Write',
+            title: 'Create a note',
+            description: packagedTemplate('mcp', 'Write'),
+            inputSchema: WRITE_INPUT_SCHEMA,
+            scope: 'edit',
+            readOnly: false,
+            run: (args, principal) => {
+                const parsed = parseWriteArgs(args);
+                return writing(ctx, () => writeTool({ view: ctx.view, syncDeps: ctx.syncDeps, write: ctx.write }, principal.email, parsed));
+            },
+        },
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/core/mcp/tools/index.js.map

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

package/dist/core/skills.d.ts.map

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

package/dist/core/skills.js

@@ -281,25 +281,30 @@ const RESEARCH = {
         .split('\n'),
 };
 /**
- * circleback-sweep: the first opt-in owned skill, and the first that names a
- * capture source. It exists only in a store that declares a `circleback`
- * block, so the generic capture skill stays source-neutral. Named for the
- * source rather than a command: there is no `ctxr circleback`. Its runner
- * drives Circleback's own CLI, which holds its own credential; nothing here
- * reads or stores one. `settings.json` is rendered because the runner, being
- * stdlib-only, cannot parse `contexture.yaml`.
+ * circleback-sweep, revised by capture-circleback-is-retrieval: the first
+ * opt-in owned skill, and the first that names a capture source. It is the
+ * capture skill's retrieval step for Circleback — it decides which meetings
+ * this store owes and writes each as the verbatim record — and hands back to
+ * `ctxr-capture` at step 2, so there is one capture procedure. Named into the
+ * capture family (`ctxr-capture-<source>`), which `ctxr-capture` step 1
+ * delegates to without naming any source. There is no `ctxr capture` command,
+ * so the name claims none. It exists only in a store that declares a
+ * `circleback` block. Its runner drives Circleback's own CLI, which holds its
+ * own credential; nothing here reads or stores one. `settings.json` is
+ * rendered because the runner, being stdlib-only, cannot parse
+ * `contexture.yaml`.
  */
-const CIRCLEBACK = {
-    file: 'ctxr-circleback',
-    name: 'Circleback',
-    description: "Find the Circleback meetings this store's tag says it owes, render their captures into the inbox on a review branch, add the speaker judgment, and open the pull request.",
-    body: (config) => skillTemplate('ctxr-circleback')
+const CAPTURE_CIRCLEBACK = {
+    file: 'ctxr-capture-circleback',
+    name: 'Capture from Circleback',
+    description: "Retrieve the Circleback meetings this store's tag says it owes, written into the inbox as verbatim records with their identity, then continue with ctxr-capture from step 2.",
+    body: (config) => skillTemplate('ctxr-capture-circleback')
         .replaceAll('__SKILLS_PATH__', config.harness.skills_path.replace(/\/+$/, ''))
         .replaceAll('__INBOX_PATH__', config.ingest.inbox_path)
         .replaceAll('__DEFAULT_BRANCH__', config.git.default_branch)
         .split('\n'),
     supportingFiles: (config) => {
-        const files = new Map(skillSupportingFiles('ctxr-circleback'));
+        const files = new Map(skillSupportingFiles('ctxr-capture-circleback'));
         files.set('settings.json', circlebackSettings(config));
         return files;
     },
@@ -321,7 +326,7 @@ function circlebackSettings(config) {
     return `${JSON.stringify(settings, null, 2)}\n`;
 }
 /** Owned skills a store gets only by opting in; each carries `enabled`. */
-export const OPTIONAL_SKILLS = [CIRCLEBACK];
+export const OPTIONAL_SKILLS = [CAPTURE_CIRCLEBACK];
 /** Every owned skill this store is shipped: the full set plus the opt-in ones its config enables. */
 export function activeSkillSeeds(config) {
     return [...SKILLS, ...OPTIONAL_SKILLS.filter((seed) => seed.enabled?.(config) === true)];