@mulmoclaude/core 0.28.0 → 0.30.0

package/dist/{server-rRQkNBvO.cjs → server-BOiz_HDi.cjs}

@@ -1,8 +1,8 @@
 const require_rolldown_runtime = require("./rolldown-runtime-D6vf50IK.cjs");
 const require_errors = require("./errors-7P5eMOSX.cjs");
 const require_ids = require("./ids-DWmHjm17.cjs");
-const require_promptSafety = require("./promptSafety-BFt2g_wn.cjs");
-const require_discovery = require("./discovery-BKovdRpZ.cjs");
+const require_promptSafety = require("./promptSafety-DbE6eZmP.cjs");
+const require_discovery = require("./discovery-Bklck7Ck.cjs");
 const require_skill_bridge_index = require("./skill-bridge/index.cjs");
 let node_path = require("node:path");
 node_path = require_rolldown_runtime.__toESM(node_path, 1);
@@ -545,7 +545,8 @@ async function countRecordFiles(dataDir, workspaceRoot) {
 async function countRecords(collection, workspaceRoot) {
 	if (require_ids.storageKindFor(collection.schema) !== "file") try {
 		return (await require_discovery.storeFor(collection, { workspaceRoot }).page({ limit: 0 })).total;
-	} catch {
+	} catch (err) {
+		if (require_discovery.isBackendUnavailable(err)) return null;
 		return 0;
 	}
 	return countRecordFiles(collection.dataDir, workspaceRoot);
@@ -1126,6 +1127,151 @@ async function deleteCustomView(collection, viewId, opts = {}) {
 		viewId
 	};
 }
+/** Ceiling for ANY assembled reply — topic or default — safely inside
+*  the agent's per-result limit (the full doc is what overflowed it).
+*  A matched section too large to fit degrades to its own prose plus a
+*  list of its subsections to fetch individually; an oversized leaf is
+*  clipped outright; the default drops whole core sections into a
+*  pointer note. Sized so the CURRENT bundled doc's default reply
+*  (~33KB) fits without degrading. */
+var SCHEMA_DOCS_RESULT_BUDGET = 36e3;
+/** Hard truncation for a body no sectioning trick can shrink further.
+*  The marker tells the agent it did NOT see everything and how to get
+*  the rest, so a silent cut can't read as complete coverage. The limit
+*  is clamped at zero: a negative limit would make `slice(0, limit)`
+*  count from the END and return almost the whole body — the exact
+*  overflow this function exists to prevent. */
+function clip(text, limit) {
+	const max = Math.max(0, limit);
+	if (text.length <= max) return text;
+	return `${text.slice(0, max)}\n\n[…clipped ${text.length - max} chars — fetch a narrower \`topic\`, or read the doc file directly]`;
+}
+/** Slack a budget-spending assembler must reserve for what it adds
+*  AROUND the budgeted pieces — clip markers, join separators, pointer
+*  notes — so the final hard cap doesn't eat the reply's own tail (in
+*  renderDefault's case, the TOC). */
+var ASSEMBLY_RESERVE = 500;
+/** The sections every schema author needs, matched against headings so
+*  the doc can be reorganised without touching this list (an unmatched
+*  pattern is simply skipped): what a collection IS, the schema DSL and
+*  its field types, and the create/edit walkthroughs. Advanced sections
+*  (actions, bells, views, dataSource, storage) stay TOC-only. */
+var CORE_SECTION_PATTERNS = [
+	"anatomy",
+	"skill.md",
+	"the dsl",
+	"field types",
+	"end-to-end",
+	"editing an existing"
+];
+/** Backticks stripped + lowercased, so `topic: "dataSource"` matches the
+*  heading "External data (CSV) collections — `dataSource`". */
+var normalize = (text) => text.toLowerCase().replace(/`/g, "");
+var sliceLines = (lines, from, until) => lines.slice(from, until).join("\n").trim();
+/** All `#`–`###` headings, skipping fenced code blocks (a `# comment`
+*  inside an example must not become a section boundary). */
+function headingLines(lines) {
+	const found = [];
+	let fenced = false;
+	lines.forEach((line, index) => {
+		if (line.trimStart().startsWith("```")) fenced = !fenced;
+		const match = fenced ? null : /^(#{1,3}) (.+)$/.exec(line);
+		if (match) found.push({
+			index,
+			level: match[1].length,
+			heading: match[2].trim()
+		});
+	});
+	return found;
+}
+function parseSections(lines) {
+	const heads = headingLines(lines);
+	return heads.map((head, i) => {
+		const closer = heads.slice(i + 1).find((other) => other.level <= head.level);
+		return {
+			level: head.level,
+			heading: head.heading,
+			start: head.index,
+			ownEnd: heads[i + 1]?.index ?? lines.length,
+			deepEnd: closer?.index ?? lines.length
+		};
+	});
+}
+/** Bounded to half the reply budget: every render path appends the TOC,
+*  so a doc with thousands of headings must not blow the ceiling through
+*  the TOC itself — and renderDefault subtracts the TOC's length from
+*  its budget, which must stay positive. */
+function tableOfContents(sections) {
+	return clip(`Sections (call schemaDocs with \`topic: "<heading>"\` for any of them; \`topic: "all"\` for the full document):\n${sections.map((section) => `${"  ".repeat(section.level - 1)}- ${section.heading}`).join("\n")}`, Math.floor(SCHEMA_DOCS_RESULT_BUDGET / 2));
+}
+/** The no-topic reply: the doc's intro + the core authoring sections
+*  (own prose only — a core parent's advanced subsections stay TOC-only),
+*  closed by the full table of contents. Budgeted: a core section that
+*  no longer fits is dropped into a pointer note (the first is clipped
+*  instead, so the reply is never bodiless) — an oversized workspace
+*  copy must not recreate the overflow this module exists to prevent. */
+function renderDefault(lines, sections) {
+	const isCore = (section, index) => index === 0 || CORE_SECTION_PATTERNS.some((pattern) => normalize(section.heading).includes(pattern));
+	const toc = tableOfContents(sections);
+	const parts = [];
+	const skipped = [];
+	let remaining = SCHEMA_DOCS_RESULT_BUDGET - toc.length - ASSEMBLY_RESERVE;
+	for (const section of sections.filter(isCore)) {
+		const body = sliceLines(lines, section.start, section.ownEnd);
+		if (body.length > remaining && parts.length > 0) {
+			skipped.push(section.heading);
+			continue;
+		}
+		const fitted = clip(body, remaining);
+		parts.push(fitted);
+		remaining -= fitted.length;
+	}
+	const note = skipped.length > 0 ? `\n\n[Omitted for size — fetch each with \`topic\`: ${skipped.join(" · ")}]` : "";
+	return `${parts.join("\n\n")}${note}\n\n---\n\n${toc}`;
+}
+/** Case-insensitive substring match on headings, minus any match already
+*  contained in another match's subtree (its parent's deep body covers it). */
+function matchSections(sections, topic) {
+	const needle = normalize(topic).trim();
+	const matched = sections.filter((section) => normalize(section.heading).includes(needle));
+	return matched.filter((section) => !matched.some((other) => other !== section && other.start < section.start && section.deepEnd <= other.deepEnd));
+}
+/** One matched section: its whole subtree when that fits the budget,
+*  otherwise its own prose (budget-clipped) + a pointer list of
+*  subsections to fetch — the list clipped to what the prose left over
+*  (thousands of child headings must not overflow through the list
+*  itself) — and a leaf with no subsections to offer is simply clipped. */
+function renderSection(lines, sections, section, budget) {
+	const deep = sliceLines(lines, section.start, section.deepEnd);
+	if (deep.length <= budget) return deep;
+	const children = sections.filter((child) => child.start > section.start && child.start < section.deepEnd && child.level === section.level + 1);
+	const own = clip(sliceLines(lines, section.start, section.ownEnd), budget);
+	if (children.length === 0) return own;
+	return `${own}\n\nSubsections (too large to include together — fetch each with \`topic\`):\n${clip(children.map((child) => `- ${child.heading}`).join("\n"), budget - own.length)}`;
+}
+function renderTopic(lines, sections, topic) {
+	const matched = matchSections(sections, topic);
+	if (matched.length === 0) return `manageCollection: no schemaDocs section matches '${require_promptSafety.defangForPrompt(topic)}'.\n\n${tableOfContents(sections)}`;
+	const perMatch = Math.floor(SCHEMA_DOCS_RESULT_BUDGET / matched.length);
+	return matched.map((section) => renderSection(lines, sections, section, perMatch)).join("\n\n");
+}
+/** Render the authoring reference for one schemaDocs call. Small docs and
+*  docs without headings pass through verbatim — there is nothing better
+*  to key a section off. The assembled reply gets one final hard cap: the
+*  inner budgeting degrades gracefully, but per-piece overheads (clip
+*  markers on thousands of matches, join separators, pointer notes) add
+*  up outside any single piece's budget, and the ceiling must hold no
+*  matter what shape of document arrives. Only the explicit \`"all"\`
+*  opt-in and the small-doc verbatim path may exceed it. */
+function renderSchemaDocs(doc, topic) {
+	const requested = topic?.trim() ?? "";
+	if (normalize(requested) === "all") return doc;
+	if (doc.length <= 2e4) return doc;
+	const lines = doc.split("\n");
+	const sections = parseSections(lines);
+	if (sections.length === 0) return doc;
+	return clip(requested ? renderTopic(lines, sections, requested) : renderDefault(lines, sections), SCHEMA_DOCS_RESULT_BUDGET);
+}
 /** True for a launcher-managed preset slug (`mc-<something>`). The sync logic uses
 *  this to bound which active skills it may refresh/prune, so user-authored skills are
 *  never touched. */
@@ -1197,7 +1343,10 @@ async function loadRequestedItems(collection, ids, deps) {
 	const items = [];
 	const missing = [];
 	for (const recordId of ids) {
-		const item = await store.read(recordId).catch(() => null);
+		const item = await store.read(recordId).catch((err) => {
+			if (require_discovery.isBackendUnavailable(err)) throw err;
+			return null;
+		});
 		if (item) items.push(item);
 		else missing.push(recordId);
 	}
@@ -1258,7 +1407,8 @@ async function mergeWithExisting(collection, store, record, itemId) {
 	let existing;
 	try {
 		existing = await store.read(itemId);
-	} catch {
+	} catch (err) {
+		if (require_discovery.isBackendUnavailable(err)) throw err;
 		return `'${itemId}' has a malformed stored file — mode "merge" needs to read it; fix the file (Read → correct → Write) or replace it whole with "upsert"`;
 	}
 	if (!existing) return `'${itemId}' not found — mode "merge" updates an existing record; use "upsert" or "create" to add it`;
@@ -1390,14 +1540,17 @@ async function handleGetOntology(deps) {
 		collections
 	});
 }
-/** Return the collection-authoring reference (`collection-skills.md`).
-*  Workspace copy first (reflects user edits), bundled asset as the
-*  always-present fallback. Both reads guarded; if neither resolves the
-*  agent still gets an actionable message instead of a thrown call. */
-async function handleSchemaDocs(deps) {
+/** Return the collection-authoring reference (`collection-skills.md`),
+*  rendered by `renderSchemaDocs` — the full doc overflows the agent's
+*  per-result limit, so the default reply is the core guide + a table of
+*  contents, and `topic` fetches individual sections. Workspace copy
+*  first (reflects user edits), bundled asset as the always-present
+*  fallback. Both reads guarded; if neither resolves the agent still
+*  gets an actionable message instead of a thrown call. */
+async function handleSchemaDocs(deps, topic) {
 	const candidates = [node_path.default.join(resolveBase(deps), HELPS_DIR, SCHEMA_DOCS_FILE), ...deps.bundledHelpsDir ? [node_path.default.join(deps.bundledHelpsDir(), SCHEMA_DOCS_FILE)] : []];
 	for (const candidate of candidates) try {
-		return await (0, node_fs_promises.readFile)(candidate, "utf-8");
+		return renderSchemaDocs(await (0, node_fs_promises.readFile)(candidate, "utf-8"), topic);
 	} catch {}
 	return `manageCollection: could not read the collection-authoring reference (${SCHEMA_DOCS_FILE}).`;
 }
@@ -1476,7 +1629,7 @@ async function handlePutSchema(slug, schemaArg, deps) {
 		written: true
 	});
 }
-var MANAGE_COLLECTION_PROMPT = "Use `manageCollection` instead of raw Read/Write/Edit when working with a collection's records OR its schema (raw file I/O stays available as the escape hatch). Before authoring or changing a collection's `schema.json`, call `schemaDocs` to load the field/DSL reference, then read with `getSchema` and write with `putSchema` — `putSchema` validates the whole schema before writing and returns actionable errors instead of silently failing discovery's validation. `getItems` is the only way to see computed values — `derived` fields (e.g. a portfolio's value), `toggle` projections, and `embed` records are host-computed and never present in the stored JSON files. On large collections pass `ids` and/or `fields` to keep the result small. For a question that spans collections (\"which clients have unpaid invoices?\"), start with `getOntology`: it lists every collection with its primaryKey, record count, and outbound `ref`/`embed` relations, so you know which collections to join before reading any records. `putItems` validates every row against the schema before writing (required fields, enum values, primaryKey = record id) and returns `{ written, rejected }`; fix each rejected row using its `problem` text and retry just those rows. Never include computed fields in a row you write. To update a few fields of an existing record, use `mode: \"merge\"` with a partial row ({ id, <changed fields> }) — the default upsert replaces the WHOLE record, so a partial upsert would silently erase every optional field it omits. `deleteItems` removes records by id and returns `{ deleted, rejected }`; an id that doesn't exist comes back rejected rather than counted as deleted, so check `rejected` before reporting a deletion as done. Answer aggregation questions (counts, sums, averages, group-bys) with `queryItems` on ANY collection — on a dataSource (CSV) collection it scans the whole file (getItems is row-capped, so aggregates computed from its output can be silently wrong on large files); on a file-backed collection it aggregates the enriched records, so computed fields (derived/rollup/toggle) are queryable columns.";
+var MANAGE_COLLECTION_PROMPT = "Use `manageCollection` instead of raw Read/Write/Edit when working with a collection's records OR its schema (raw file I/O stays available as the escape hatch). Before authoring or changing a collection's `schema.json`, call `schemaDocs` to load the field/DSL reference — the default reply is the core authoring guide plus a table of contents; fetch advanced sections (actions, bells, calendar/kanban views, dataSource, storage) by passing their heading as `topic` rather than dumping `topic: \"all\"`. Then read with `getSchema` and write with `putSchema` — `putSchema` validates the whole schema before writing and returns actionable errors instead of silently failing discovery's validation. `getItems` is the only way to see computed values — `derived` fields (e.g. a portfolio's value), `toggle` projections, and `embed` records are host-computed and never present in the stored JSON files. On large collections pass `ids` and/or `fields` to keep the result small. For a question that spans collections (\"which clients have unpaid invoices?\"), start with `getOntology`: it lists every collection with its primaryKey, record count, and outbound `ref`/`embed` relations, so you know which collections to join before reading any records. `putItems` validates every row against the schema before writing (required fields, enum values, primaryKey = record id) and returns `{ written, rejected }`; fix each rejected row using its `problem` text and retry just those rows. Never include computed fields in a row you write. To update a few fields of an existing record, use `mode: \"merge\"` with a partial row ({ id, <changed fields> }) — the default upsert replaces the WHOLE record, so a partial upsert would silently erase every optional field it omits. `deleteItems` removes records by id and returns `{ deleted, rejected }`; an id that doesn't exist comes back rejected rather than counted as deleted, so check `rejected` before reporting a deletion as done. Answer aggregation questions (counts, sums, averages, group-bys) with `queryItems` on ANY collection — on a dataSource (CSV) collection it scans the whole file (getItems is row-capped, so aggregates computed from its output can be silently wrong on large files); on a file-backed collection it aggregates the enriched records, so computed fields (derived/rollup/toggle) are queryable columns.";
 /** Validate getItems' optional `ids`/`fields` args, then delegate. */
 async function dispatchGetItems(collection, args, deps) {
 	const ids = optionalStringArray(args.ids, "ids");
@@ -1510,8 +1663,16 @@ async function dispatchRecordAction(action, collection, args, deps) {
 	return typeof parsed === "string" ? parsed : handlePutItems(collection, parsed, deps);
 }
 async function manageCollectionHandler(deps, args) {
+	try {
+		return await dispatchManageCollection(deps, args);
+	} catch (err) {
+		if (require_discovery.isBackendUnavailable(err)) return `manageCollection: ${err.message}`;
+		throw err;
+	}
+}
+async function dispatchManageCollection(deps, args) {
 	const action = typeof args.action === "string" ? args.action : "";
-	if (action === "schemaDocs") return handleSchemaDocs(deps);
+	if (action === "schemaDocs") return handleSchemaDocs(deps, typeof args.topic === "string" ? args.topic : void 0);
 	if (action === "getOntology") return handleGetOntology(deps);
 	const slug = typeof args.slug === "string" ? args.slug.trim() : "";
 	if (!slug) return "manageCollection: `slug` is required (the collection's slug).";
@@ -1524,7 +1685,7 @@ async function manageCollectionHandler(deps, args) {
 }
 var MANAGE_COLLECTION_DEFINITION = {
 	name: "manageCollection",
-	description: "Read and write a schema-driven collection through the host — both its records and its structure. getItems returns records WITH computed values (derived formulas, toggles, embeds) the stored JSON files don't contain; putItems validates each row against the schema before writing; deleteItems removes records by id. getOntology maps the whole workspace: every collection with its record count and outbound ref/embed relations — call it first for cross-collection questions. schemaDocs returns the collection-authoring reference; getSchema/putSchema read and validate-then-write the collection's schema.json. Prefer it over raw file I/O on collections.",
+	description: "Read and write a schema-driven collection through the host — both its records and its structure. getItems returns records WITH computed values (derived formulas, toggles, embeds) the stored JSON files don't contain; putItems validates each row against the schema before writing; deleteItems removes records by id. getOntology maps the whole workspace: every collection with its record count and outbound ref/embed relations — call it first for cross-collection questions. schemaDocs returns the collection-authoring reference — the core guide plus a table of contents by default; pass `topic` for a specific section. getSchema/putSchema read and validate-then-write the collection's schema.json. Prefer it over raw file I/O on collections.",
 	inputSchema: {
 		type: "object",
 		properties: {
@@ -1574,6 +1735,10 @@ var MANAGE_COLLECTION_DEFINITION = {
 				type: "object",
 				description: "putSchema: the full collection schema object (same shape as schema.json — title, icon, dataPath, primaryKey, fields, …). Call getSchema first for the current one, and schemaDocs for the field DSL."
 			},
+			topic: {
+				type: "string",
+				description: "schemaDocs: fetch one section of the reference by heading (case-insensitive substring — e.g. \"field types\", \"kanban\", \"calendar\", \"dataSource\"). Omit for the core authoring guide plus a table of contents of every section; \"all\" returns the full document (large — it can exceed your tool-result limit)."
+			},
 			query: {
 				type: "object",
 				description: "queryItems: a structured aggregation query — `{ groupBy?: [\"col\"], aggregates?: { alias: { op: \"count\"|\"sum\"|\"avg\"|\"min\"|\"max\", column? } }, where?: [{ field, op, value }], orderBy?: [{ field, dir? }], limit? }`. At least one of groupBy/aggregates. On a dataSource (CSV) collection it scans the WHOLE file uncapped (unlike getItems); on a file-backed collection it aggregates the ENRICHED records, so computed fields (derived/rollup/toggle) are queryable columns. Use it for counts / sums / averages / group-bys instead of arithmetic over getItems output."
@@ -1760,4 +1925,4 @@ Object.defineProperty(exports, "validateRecordObject", {
 	}
 });
 
-//# sourceMappingURL=server-rRQkNBvO.cjs.map
+//# sourceMappingURL=server-BOiz_HDi.cjs.map