@mulmoclaude/core 4.1.0 → 4.1.1

package/dist/{server-DSrRdPvf.cjs → server-meS6kjBN.cjs}

@@ -7,6 +7,7 @@ const require_promptSafety = require("./promptSafety-CuczAN9d.cjs");
 const require_discovery = require("./discovery-B9EESjHP.cjs");
 const require_feeds_paths = require("./feeds/paths.cjs");
 const require_skill_bridge_index = require("./skill-bridge/index.cjs");
+let node_fs = require("node:fs");
 let node_path = require("node:path");
 node_path = require_rolldown_runtime.__toESM(node_path, 1);
 let node_crypto = require("node:crypto");
@@ -1558,6 +1559,26 @@ var SCHEMA_FILE = "schema.json";
 var SCHEMA_DOCS_FILE = "collection-skills.md";
 /** Cap the rejected-schema issue list so a deeply-broken schema can't flood the result. */
 var MAX_SCHEMA_ISSUES = 20;
+/** Cap the rows one putItems call may write. `putOneItem` validates and
+*  writes one record at a time, so a large `itemsFile` holds the tool call
+*  open for minutes. Over the cap the call is refused WHOLE — a truncating
+*  write that reported success would leave a half-filled collection nobody
+*  knows is half-filled. */
+var MAX_PUT_ITEMS = 1e3;
+/** Refuse an `itemsFile` larger than this, from `stat` and before any read.
+*  The row cap alone cannot bound the work: the file has to be read and parsed
+*  WHOLE before there are rows to count, so a huge blob is paid for in full
+*  first. 8 MiB is far past what 1000 records need and far short of trouble. */
+var MAX_ITEMS_FILE_BYTES = 8388608;
+/** `itemsFile` is opened read-only, without following a symlink, and without
+*  blocking on a fifo — see `openContainedItemsFile`.
+*
+*  `O_NOFOLLOW` and `O_NONBLOCK` are POSIX-only: on Windows they are absent, and
+*  `x | undefined` is `x`, so the flags silently soften to a plain read-only
+*  open. They are hardening where they exist, never the guarantee — the symlink
+*  refusal is an explicit `lstat` (`verifyOpenedItemsFile`) so it holds on every
+*  platform. `?? 0` states that rather than leaving it to coercion. */
+var OPEN_ITEMS_FILE_FLAGS = node_fs.constants.O_RDONLY | (node_fs.constants.O_NOFOLLOW ?? 0) | (node_fs.constants.O_NONBLOCK ?? 0);
 /** The workspace help-docs dir both hosts seed (`@mulmoclaude/core/workspace-setup`
 *  syncs the bundled assets here) — the user-editable copy schemaDocs prefers. */
 var HELPS_DIR = "config/helps";
@@ -1758,13 +1779,167 @@ async function handleQueryItems(collection, queryArg, deps) {
 		rows
 	});
 }
+/** Rewrite a sandbox-mount prefix to the host's workspace root, so the path the
+*  agent wrote to and the file this process reads are the same bytes. Anything
+*  not under the mount is returned untouched — a host with no sandbox hands the
+*  agent real paths already. */
+function toHostWorkspacePath(absPath, sandboxRoot, workspaceRoot) {
+	if (!sandboxRoot) return absPath;
+	if (absPath === sandboxRoot) return workspaceRoot;
+	const prefix = sandboxRoot.endsWith("/") ? sandboxRoot : `${sandboxRoot}/`;
+	if (!absPath.startsWith(prefix)) return absPath;
+	return node_path.default.join(workspaceRoot, ...absPath.slice(prefix.length).split("/"));
+}
+/** The host path an `itemsFile` names — translated out of the sandbox, and
+*  required to land INSIDE the workspace.
+*
+*  Containment is not tidiness. `manageCollection` is always available to a
+*  sandboxed agent, and an unconstrained absolute path would turn this
+*  host-side handler into a read primitive for the whole host filesystem —
+*  point it at any JSON array the server user can open, store the rows, read
+*  them back with `getItems`. The sandbox mounts a few app directories besides
+*  the workspace, but nothing that gives the agent that reach, and the
+*  workspace is where its own generated files land — so confining reads to it
+*  denies the primitive without costing the feature anything.
+*
+*  This is the CHEAP check, for the ordinary case and a precise message. The
+*  binding one is on the opened descriptor (`verifyOpenedItemsFile`) — a path
+*  checked here and read again later is a path that can change in between. */
+function resolveItemsFilePath(itemsFile, deps) {
+	const root = resolveBase(deps);
+	const hostPath = toHostWorkspacePath(itemsFile, deps.sandboxWorkspacePath, root);
+	if (!require_discovery.isContainedInRoot(hostPath, root)) return outsideWorkspaceRefusal(require_promptSafety.defangForPrompt(itemsFile));
+	return { hostPath };
+}
+function outsideWorkspaceRefusal(shown) {
+	return `manageCollection: \`itemsFile\` must be inside the workspace — '${shown}' is not, and the host reads this file on your behalf. Write the generated rows under the workspace and pass that path.`;
+}
+function symlinkRefusal(shown) {
+	return `manageCollection: \`itemsFile\` '${shown}' is a symbolic link. Pass the real path of a regular file inside the workspace.`;
+}
+function openItemsFileRefusal(err, shown) {
+	if (require_dist.isErrorWithCode(err) && (err.code === "ELOOP" || err.code === "EMLINK")) return symlinkRefusal(shown);
+	return `manageCollection: could not read \`itemsFile\` '${shown}' — ${require_promptSafety.defangForPrompt(require_dist.errorMessage(err))}. It must exist inside the workspace and be readable by the host.`;
+}
+/** Everything decided about the file, decided about the OPEN DESCRIPTOR rather
+*  than about the path a second time.
+*
+*  Re-`stat`ing and re-`readFile`ing the pathname would leave a TOCTOU window
+*  the containment check cannot close: the caller is a sandboxed agent with
+*  write access to the workspace, so it can point `rows.json` at an in-workspace
+*  file, call the tool, and swap the symlink to a host file outside the mount
+*  while the first `await` is pending — restoring exactly the read primitive
+*  containment exists to deny. Bound to one descriptor, a swap after the open
+*  changes nothing about the bytes this call goes on to read.
+*
+*  The `dev`/`ino` comparison is what ties the two together: it proves the
+*  descriptor's inode is the one reachable at a contained path. A hardlink
+*  would satisfy it, but the agent cannot create one across the mount boundary
+*  — only the workspace is mounted, and a hardlink cannot cross filesystems. */
+async function verifyOpenedItemsFile(handle, hostPath, root, shown) {
+	const opened = await handle.stat();
+	if (!opened.isFile()) return `manageCollection: \`itemsFile\` '${shown}' is not a regular file. It must be a JSON file holding an array of record objects.`;
+	if (opened.size > 8388608) return `manageCollection: \`itemsFile\` '${shown}' is ${opened.size} bytes, over the limit of ${MAX_ITEMS_FILE_BYTES}. Nothing was read; split the rows across several files and call once per file.`;
+	let real;
+	let atPath;
+	let link;
+	try {
+		link = await (0, node_fs_promises.lstat)(hostPath);
+		real = await (0, node_fs_promises.realpath)(hostPath);
+		atPath = await (0, node_fs_promises.stat)(real);
+	} catch (err) {
+		return openItemsFileRefusal(err, shown);
+	}
+	if (link.isSymbolicLink()) return symlinkRefusal(shown);
+	if (!require_discovery.isContainedInRoot(real, root)) return outsideWorkspaceRefusal(shown);
+	if (atPath.ino !== opened.ino || atPath.dev !== opened.dev) return `manageCollection: \`itemsFile\` '${shown}' changed while it was being opened. Nothing was read; write the file, then call putItems.`;
+	return { size: opened.size };
+}
+/** Open the file ONCE, then prove that descriptor is the contained file.
+*  `O_NOFOLLOW` refuses a symlink outright rather than resolving it, and
+*  `O_NONBLOCK` keeps a fifo from parking this call on `open` itself — the
+*  descriptor is what `verifyOpenedItemsFile` then judges. */
+async function openContainedItemsFile(hostPath, root, shown) {
+	let handle;
+	try {
+		handle = await (0, node_fs_promises.open)(hostPath, OPEN_ITEMS_FILE_FLAGS);
+	} catch (err) {
+		return openItemsFileRefusal(err, shown);
+	}
+	const verified = await verifyOpenedItemsFile(handle, hostPath, root, shown);
+	if (typeof verified !== "string") return {
+		handle,
+		size: verified.size
+	};
+	await handle.close();
+	return verified;
+}
+/** Read the descriptor into a buffer bounded by the size that was CHECKED,
+*  rather than to EOF.
+*
+*  `FileHandle.readFile()` reads until end-of-file, which the size check cannot
+*  bound: the agent can hold the same file open and append to it after the
+*  `stat` and before the read, and because appending does not change the inode,
+*  the identity check cannot see it either. A 2-byte file that passed the gate
+*  can hand back gigabytes. Allocating `size + 1` makes the cap hold on the
+*  bytes actually taken, whatever the file does meanwhile — and that one extra
+*  byte is what detects the growth, so a file being written under us is refused
+*  rather than parsed as the truncated half it would otherwise look like. */
+async function readItemsBytes(handle, size, shown) {
+	const buffer = Buffer.allocUnsafe(size + 1);
+	const { bytesRead } = await handle.read(buffer, 0, size + 1, 0);
+	if (bytesRead > size) return `manageCollection: \`itemsFile\` '${shown}' grew while it was being read. Nothing was written; finish writing the file, then call putItems.`;
+	return { raw: buffer.subarray(0, bytesRead).toString("utf-8") };
+}
+function parseItemsJson(raw, shown) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		return `manageCollection: \`itemsFile\` '${shown}' could not be read as JSON — ${require_promptSafety.defangForPrompt(require_dist.errorMessage(err))}. It must hold a JSON array of record objects.`;
+	}
+	if (!isRecordArray(parsed) || parsed.length === 0) return `manageCollection: \`itemsFile\` '${shown}' must hold a non-empty JSON array of record objects.`;
+	return parsed;
+}
+/** Read the rows an `itemsFile` holds. Every failure comes back as tool text,
+*  never a throw: a bad path or a malformed file is something the agent can fix
+*  and retry. The path it passed is what the messages name, even when the bytes
+*  were read from the translated host path — it is the one the agent recognises. */
+async function readItemsFile(itemsFile, deps) {
+	const shown = require_promptSafety.defangForPrompt(itemsFile);
+	const resolved = resolveItemsFilePath(itemsFile, deps);
+	if (typeof resolved === "string") return resolved;
+	const opened = await openContainedItemsFile(resolved.hostPath, resolveBase(deps), shown);
+	if (typeof opened === "string") return opened;
+	let read;
+	try {
+		read = await readItemsBytes(opened.handle, opened.size, shown);
+	} catch (err) {
+		return openItemsFileRefusal(err, shown);
+	} finally {
+		await opened.handle.close();
+	}
+	return typeof read === "string" ? read : parseItemsJson(read.raw, shown);
+}
+/** The rows this call will write, from whichever source it named. The cap is
+*  checked here — on the resolved rows, so it holds for `items` and `itemsFile`
+*  alike — and BEFORE the first write, so an over-cap call leaves the
+*  collection exactly as it found it instead of half-filled. */
+async function resolvePutRows(args, deps) {
+	const rows = args.itemsFile === void 0 ? args.items : await readItemsFile(args.itemsFile, deps);
+	if (typeof rows === "string") return rows;
+	if (rows.length > 1e3) return `manageCollection: refused — ${rows.length} rows is over the putItems limit of ${MAX_PUT_ITEMS}. Nothing was written; split them across several calls.`;
+	return rows;
+}
 async function handlePutItems(collection, args, deps) {
 	const store = require_discovery.storeFor(collection, { workspaceRoot: deps.workspaceRoot });
 	const { write } = store;
 	if (!write) return `manageCollection: ${require_discovery.readOnlyRefusal(collection.slug)} (its records are the rows of '${collection.schema.dataSource?.path}'; edit that file to change the data).`;
+	const rows = await resolvePutRows(args, deps);
+	if (typeof rows === "string") return rows;
 	const written = [];
 	const rejected = [];
-	for (const record of args.items) {
+	for (const record of rows) {
 		const outcome = await putOneItem(collection, store, write, record, args.mode, deps);
 		if (outcome.written) written.push(outcome.written);
 		if (outcome.rejected) rejected.push(outcome.rejected);
@@ -1827,14 +2002,36 @@ function parsePutMode(mode) {
 function isRecordArray(value) {
 	return require_dist.isUnknownArray(value) && value.every(require_dist.isRecord);
 }
+/** `items` and `itemsFile` are ALTERNATIVES, never a pair: two row sets in one
+*  call has no correct reading — honouring one silently discards the other, and
+*  concatenating them writes rows the caller never asked to write together. So
+*  both present is refused, rather than resolved by precedence.
+*
+*  A relative `itemsFile` is refused too, for a reason the agent cannot see from
+*  where it stands: this tool runs inside the HOST'S SERVER PROCESS, whose
+*  working directory is not the agent's. A relative path would not reliably
+*  fail — it would resolve against an unrelated directory and either miss or,
+*  worse, read a different file that happens to share the name. */
+function parseItemsSource(items, itemsFile) {
+	if (items !== void 0 && itemsFile !== void 0) return "manageCollection: pass either `items` or `itemsFile` for putItems, not both — two row sets in one call is ambiguous.";
+	if (itemsFile !== void 0) return parseItemsFile(itemsFile);
+	if (!isRecordArray(items) || items.length === 0) return "manageCollection: putItems needs `items` (a non-empty array of record objects) or `itemsFile` (an absolute path to a JSON file of them — use it for a set a script generated, so the rows never pass through your context).";
+	return { items };
+}
+function parseItemsFile(itemsFile) {
+	const file = typeof itemsFile === "string" ? itemsFile.trim() : "";
+	if (!file) return "manageCollection: `itemsFile` must be a non-empty absolute path to a JSON file of record objects.";
+	if (!node_path.default.isAbsolute(file)) return `manageCollection: \`itemsFile\` must be an ABSOLUTE path — '${require_promptSafety.defangForPrompt(file)}' is relative, and this tool runs in the host's server process, whose working directory is not yours. Pass the full path.`;
+	return { itemsFile: file };
+}
 function parsePutItems(args, slug) {
-	const { items, mode } = args;
-	if (!isRecordArray(items) || items.length === 0) return "manageCollection: `items` is required for putItems — a non-empty array of record objects.";
-	const putMode = parsePutMode(mode);
+	const source = parseItemsSource(args.items, args.itemsFile);
+	if (typeof source === "string") return source;
+	const putMode = parsePutMode(args.mode);
 	if (putMode === null) return "manageCollection: `mode` must be \"upsert\" (default), \"create\", or \"merge\".";
 	return {
+		...source,
 		slug,
-		items,
 		mode: putMode
 	};
 }
@@ -1960,7 +2157,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 — 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.";
+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. When the rows come from a script rather than from you (a generated schedule, an imported set, anything past a few dozen records), write them to a JSON file UNDER THE WORKSPACE and pass its absolute path as `itemsFile` instead of `items` — the host reads the file, so the rows never pass through your context. Do NOT hand-transcribe a generated file into `items`, and never drive the collection by spawning the MCP bridge yourself. 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");
@@ -2051,7 +2248,11 @@ var MANAGE_COLLECTION_DEFINITION = {
 			items: {
 				type: "array",
 				items: { type: "object" },
-				description: "putItems: the record objects to store. Each must carry the schema's primaryKey value (it doubles as the filename)."
+				description: "putItems: the record objects to store, inline. Each must carry the schema's primaryKey value (it doubles as the filename). For rows a script generated, pass `itemsFile` instead — never both."
+			},
+			itemsFile: {
+				type: "string",
+				description: "putItems: an ABSOLUTE path to a JSON file holding the array of record objects, read by the host — the alternative to `items` for rows a script produced. Use it whenever the data already exists as a file: passing a generated set of several hundred records through `items` means writing every byte of it yourself. The path must be absolute (this tool runs in the host's server process, whose working directory is not yours) and must be INSIDE the workspace — write the generated file under the workspace, not to a system temp dir. The file must hold a non-empty JSON array, and `items` and `itemsFile` are mutually exclusive."
 			},
 			mode: {
 				type: "string",
@@ -2087,6 +2288,18 @@ function makeManageCollectionTool(deps = {}) {
 	};
 }
 //#endregion
+Object.defineProperty(exports, "MAX_ITEMS_FILE_BYTES", {
+	enumerable: true,
+	get: function() {
+		return MAX_ITEMS_FILE_BYTES;
+	}
+});
+Object.defineProperty(exports, "MAX_PUT_ITEMS", {
+	enumerable: true,
+	get: function() {
+		return MAX_PUT_ITEMS;
+	}
+});
 Object.defineProperty(exports, "MAX_RECORD_ISSUES", {
 	enumerable: true,
 	get: function() {
@@ -2304,4 +2517,4 @@ Object.defineProperty(exports, "validateRecordObject", {
 	}
 });
 
-//# sourceMappingURL=server-DSrRdPvf.cjs.map
+//# sourceMappingURL=server-meS6kjBN.cjs.map