@stll/folio-cli 0.3.4 → 0.4.0

package/README.md

@@ -69,6 +69,14 @@ bare array. The operation types and fields are those of `suggest_changes` in
 targets come from a read of the same `fileVersion`. Edits are tracked changes;
 `--direct` edits the text instead and must be asked for.
 
+Two more operations are expanded against the file before the batch applies:
+`{ "type": "replaceAll", "find", "replace", "matchCase"?, "wholeWord"? }`
+replaces every match in the body, tables included, keeping each run's
+formatting (refused when nothing matches); and
+`{ "type": "addComment", "comment", "blockId"?, "quote"? }` comments on a
+block, or with only `quote` on the one block containing that text
+(`ambiguous_target` when several do).
+
 Every change commits, so there is no separate save:
 
 - **Destination.** Exactly one of `--in-place` or `-o <path>`, and only a
@@ -235,8 +243,11 @@ unless the file still has that version.
 
 A block id is the paragraph's own `w14:paraId` when it has one
 (`blockIdSource: "package"`). A paragraph without one gets an id derived from
-its text and position (`blockIdSource: "synthetic"`): stable across reads of
-the same bytes, but valid only for the `fileVersion` it was read at.
+the file's bytes (`blockIdSource: "synthetic"`): stable across reads of the
+same bytes, and written into the file as its `w14:paraId` by the first change,
+so a paragraph keeps its id across edits. A signed package is never rewritten
+for this; its id-less paragraphs keep ids derived from text and position,
+valid only for the `fileVersion` they were read at.
 
 `read` pages with `--max-blocks`; a page that stops early carries
 `nextCursor`, which `--cursor` continues. A cursor is bound to the version it
@@ -280,11 +291,17 @@ args = ["-y", "@stll/folio-cli", "mcp", "--root", "/path/to/contracts"]
 env = { FOLIO_AUTHOR = "Jane Doe" }
 ```
 
-Tools: `read_document`, `get_document_outline`, `read_section`,
-`list_stories`, `read_story`, `find_text`, `read_comments`, `read_changes`,
-`suggest_changes`, `add_comment`, `reply_comment`, `resolve_comment`,
-`resolve_changes`, and `compare_documents`. Each takes its folio-agents
-arguments plus a file envelope:
+A model is sent the tool list on every turn, so the server lists only the
+frequent tools, with compact schemas: `read_document`, `find_text`,
+`read_comments`, `read_changes`, `suggest_changes`, and `add_comment`. The
+rest (`get_document_outline`, `read_section`, `list_stories`, `read_story`,
+`reply_comment`, `resolve_comment`, `resolve_changes`, and
+`compare_documents`) are reached through `list_capabilities`,
+`describe_capability` (a tool's parameter outline, short guidance and an
+example, listed tools included; `detail: "full"` for its full input schema),
+and `invoke_capability` (`{ capability, input, validate_only }`).
+Every tool is also callable by name. Each takes its folio-agents arguments
+plus a file envelope:
 
 | Field                        | Meaning                                                                                                                       |
 | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
@@ -308,8 +325,19 @@ annotated `destructiveHint: true`; there is no way to skip the version check.
 One call returns at most 200 `read_document` blocks by default (up to
 1,000 with `maxBlocks`), 100 `find_text` matches, and 256 KiB; a longer read
 pages with `nextCursor`, and a result that cannot be paged is refused with
-`too_large` and a hint to narrow it. Results are the `{ ok, data | error }`
-envelope as JSON text, with `isError` set on failures.
+`too_large` and a hint to narrow it.
+
+Results carry what the next call needs. `read_document` returns
+`[id] text` lines, a table row as `| [id] cell | [id] cell |`
+(`formatting: true` for each block's fields), a write returns the new
+`fileVersion` plus what it produced (`applied`, `replaced`, `commentIds`,
+...), and block ids stay valid across writes, so a successful write needs no
+verification read. A failure is
+`{ "error": { code, message, hint, retryable } }` with `isError` set.
+Arguments are read leniently (`"true"`, `"20"`, an enum value in another
+case) with an `Input read:` note; an unknown or ambiguous argument is refused
+with `validation_error`, and `overwrite` and `allowRepack` count only as JSON
+`true`.
 
 Resources: `folio://about` (these rules and the roots) and
 `folio://schema/operations` (the JSON Schema of an operation batch).

package/dist/batch-operations.d.ts

@@ -0,0 +1,29 @@
+import { FolioCliError } from "./errors.js";
+import { JsonObjectSchema } from "./registry.js";
+import { Result } from "better-result";
+import { FolioAgentBridge } from "@stll/folio-agents/bridge";
+import { FolioAgentToolOptions } from "@stll/folio-agents/suggest-changes-options";
+//#region src/batch-operations.d.ts
+declare const BATCH_OPERATION_TYPES: readonly ["replaceAll", "addComment"];
+/**
+ * `suggest_changes`' arguments with the batch operations added to the
+ * operation schema: their types in the `type` enum and their extra fields.
+ */
+declare const withBatchOperations: (schema: JsonObjectSchema) => JsonObjectSchema;
+type ExpandedBatch = {
+  operations: unknown[];
+  /** Options the expanded batch needs from `suggest_changes`. */
+  options: FolioAgentToolOptions;
+  /** How many replacements each `replaceAll`, in batch order, produced. */
+  replaced: {
+    find: string;
+    count: number;
+  }[];
+};
+/**
+ * Expand the batch operations of a `suggest_changes` call against the
+ * document the bridge holds. Contract operations pass through unchanged.
+ */
+declare const expandBatchOperations: (operations: unknown, bridge: FolioAgentBridge) => Result<ExpandedBatch, FolioCliError>;
+//#endregion
+export { BATCH_OPERATION_TYPES, ExpandedBatch, expandBatchOperations, withBatchOperations };

package/dist/batch-operations.js

@@ -0,0 +1,226 @@
+import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
+import { Result } from "better-result";
+import { executeFolioToolCallUntyped } from "@stll/folio-agents/execute";
+import { DEFAULT_MAX_OPERATIONS_PER_CALL, MAX_OPERATIONS_PER_CALL_LIMIT } from "@stll/folio-agents/suggest-changes-options";
+import { SUGGEST_CHANGES_OPERATION_TYPES } from "@stll/folio-agents/tools";
+import { FOLIO_AGENT_TOOL_NAMES } from "@stll/folio-agents/types";
+//#region src/batch-operations.ts
+/**
+* Batch operations the file surface adds to `suggest_changes`, expanded into
+* contract operations against the document they are about to change:
+*
+* - `replaceAll {find, replace, matchCase?, wholeWord?}` becomes one
+*   `replaceRange` per `find_text` match in the body (tables included), so a
+*   rename needs no search call and keeps each run's formatting.
+* - `addComment {comment, blockId?, quote?}` becomes `commentOnBlock`; with
+*   only a quote, it anchors to the one block containing that text.
+*
+* Matching is `find_text`'s own; nothing here searches text itself.
+*/
+const BATCH_OPERATION_TYPES = ["replaceAll", "addComment"];
+/** Fields each batch operation accepts, besides `type`. */
+const BATCH_OPERATION_KEYS = {
+	replaceAll: /* @__PURE__ */ new Set([
+		"id",
+		"find",
+		"replace",
+		"matchCase",
+		"wholeWord",
+		"severity",
+		"area"
+	]),
+	addComment: /* @__PURE__ */ new Set([
+		"id",
+		"blockId",
+		"quote",
+		"comment",
+		"severity",
+		"area"
+	])
+};
+const BATCH_PROPERTY_SCHEMAS = {
+	matchCase: {
+		type: "boolean",
+		description: "For `replaceAll`: match case exactly."
+	},
+	wholeWord: {
+		type: "boolean",
+		description: "For `replaceAll`: match whole words only."
+	}
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* `suggest_changes`' arguments with the batch operations added to the
+* operation schema: their types in the `type` enum and their extra fields.
+*/
+const withBatchOperations = (schema) => {
+	const operations = schema.properties["operations"];
+	if (!isRecord(operations) || !isRecord(operations["items"])) return schema;
+	const items = operations["items"];
+	const properties = isRecord(items["properties"]) ? items["properties"] : {};
+	const type = isRecord(properties["type"]) ? properties["type"] : {};
+	const types = Array.isArray(type["enum"]) ? type["enum"] : [];
+	return {
+		...schema,
+		properties: {
+			...schema.properties,
+			operations: {
+				...operations,
+				items: {
+					...items,
+					properties: {
+						...properties,
+						type: {
+							...type,
+							enum: [...types, ...BATCH_OPERATION_TYPES],
+							description: `${typeof type["description"] === "string" ? type["description"] : ""} replaceAll (replace every match of \`find\` in the body and tables); addComment (comment on \`blockId\`, or on the one block containing \`quote\`).`
+						},
+						...BATCH_PROPERTY_SCHEMAS
+					}
+				}
+			}
+		}
+	};
+};
+const invalidInput = (message, hint) => cliError({
+	code: FOLIO_CLI_ERROR_CODES.invalidInput,
+	message,
+	hint
+});
+const findMatches = (bridge, query, matchCase, wholeWord) => {
+	const found = executeFolioToolCallUntyped(FOLIO_AGENT_TOOL_NAMES.findText, {
+		query,
+		matchCase,
+		wholeWord
+	}, bridge);
+	if (!found.ok) return Result.err(invalidInput(found.error));
+	const result = isRecord(found.result) ? found.result : {};
+	const matches = (Array.isArray(result["matches"]) ? result["matches"] : []).flatMap((match) => isRecord(match) && typeof match["blockId"] === "string" && isRecord(match["range"]) ? [{
+		blockId: match["blockId"],
+		range: match["range"]
+	}] : []);
+	return Result.ok({
+		matches,
+		truncated: result["truncated"] === true,
+		total: typeof result["totalMatches"] === "number" ? result["totalMatches"] : matches.length
+	});
+};
+const checkKeys = (operation, type, index) => {
+	const allowed = BATCH_OPERATION_KEYS[type] ?? /* @__PURE__ */ new Set();
+	const extra = Object.keys(operation).filter((key) => key !== "type" && !allowed.has(key));
+	return extra.length === 0 ? null : invalidInput(`operations[${index}] (${type}) does not take ${extra.join(", ")}.`, `${type} takes ${[...allowed].join(", ")}.`);
+};
+const metaOf = (operation) => ({
+	...operation["severity"] !== void 0 && { severity: operation["severity"] },
+	...operation["area"] !== void 0 && { area: operation["area"] }
+});
+const expandReplaceAll = (operation, index, bridge) => {
+	const { find, replace, id } = operation;
+	if (typeof find !== "string" || find === "") return Result.err(invalidInput(`operations[${index}] (replaceAll) needs a non-empty find.`));
+	if (typeof replace !== "string") return Result.err(invalidInput(`operations[${index}] (replaceAll) needs replace.`));
+	const found = findMatches(bridge, find, operation["matchCase"] === true, operation["wholeWord"] === true);
+	if (found.isErr()) return found;
+	const { matches, truncated, total } = found.value;
+	if (matches.length === 0) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.notFound,
+		message: `operations[${index}] (replaceAll) found no ${JSON.stringify(find)}; nothing was written.`,
+		hint: "Check the spelling, matchCase and wholeWord."
+	}));
+	if (truncated) return Result.err(invalidInput(`operations[${index}] (replaceAll) matches ${total} times, more than one batch can change.`, "Narrow find, or split the rename across calls with replaceInBlock."));
+	const meta = metaOf(operation);
+	return Result.ok(matches.map((match, occurrence) => {
+		const replacement = {
+			type: "replaceRange",
+			range: match.range,
+			replace
+		};
+		if (typeof id === "string") replacement["id"] = `${id}.${occurrence + 1}`;
+		return Object.assign(replacement, meta);
+	}));
+};
+const expandAddComment = (operation, index, bridge) => {
+	const { blockId, quote, comment, id } = operation;
+	if (typeof comment !== "string" || comment === "") return Result.err(invalidInput(`operations[${index}] (addComment) needs comment text.`));
+	if (quote !== void 0 && (typeof quote !== "string" || quote === "")) return Result.err(invalidInput(`operations[${index}] (addComment) quote must be text.`));
+	const anchored = (target) => Result.ok({
+		type: "commentOnBlock",
+		blockId: target,
+		comment,
+		...quote !== void 0 && { quote },
+		...typeof id === "string" && { id },
+		...metaOf(operation)
+	});
+	if (typeof blockId === "string" && blockId !== "") return anchored(blockId);
+	if (quote === void 0) return Result.err(invalidInput(`operations[${index}] (addComment) needs blockId or quote.`));
+	const found = findMatches(bridge, quote, true, false);
+	if (found.isErr()) return found;
+	const blocks = [...new Set(found.value.matches.map((match) => match.blockId))];
+	if (blocks.length === 0) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.notFound,
+		message: `operations[${index}] (addComment) quote ${JSON.stringify(quote)} is not in the document; nothing was written.`,
+		hint: "Quote exact text from read_document, or pass blockId."
+	}));
+	const [only] = blocks;
+	if (blocks.length > 1 || only === void 0) return Result.err(cliError({
+		code: FOLIO_CLI_ERROR_CODES.ambiguousTarget,
+		message: `operations[${index}] (addComment) quote ${JSON.stringify(quote)} is in ${blocks.length} blocks; nothing was written.`,
+		hint: "Pass blockId, or quote longer text.",
+		details: { blockIds: blocks.slice(0, 20) }
+	}));
+	return anchored(only);
+};
+/**
+* Expand the batch operations of a `suggest_changes` call against the
+* document the bridge holds. Contract operations pass through unchanged.
+*/
+const expandBatchOperations = (operations, bridge) => {
+	if (!Array.isArray(operations)) return Result.ok({
+		operations: [],
+		options: {},
+		replaced: []
+	});
+	const expanded = [];
+	const replaced = [];
+	let comments = false;
+	let batchOperations = false;
+	for (const [index, operation] of operations.entries()) {
+		const type = isRecord(operation) ? operation["type"] : void 0;
+		if (!isRecord(operation) || type !== "replaceAll" && type !== "addComment") {
+			expanded.push(operation);
+			continue;
+		}
+		batchOperations = true;
+		const keys = checkKeys(operation, type, index);
+		if (keys !== null) return Result.err(keys);
+		if (type === "replaceAll") {
+			const replacements = expandReplaceAll(operation, index, bridge);
+			if (replacements.isErr()) return replacements;
+			expanded.push(...replacements.value);
+			replaced.push({
+				find: String(operation["find"]),
+				count: replacements.value.length
+			});
+		} else {
+			const comment = expandAddComment(operation, index, bridge);
+			if (comment.isErr()) return comment;
+			expanded.push(comment.value);
+			comments = true;
+		}
+	}
+	if (!batchOperations) return Result.ok({
+		operations,
+		options: {},
+		replaced
+	});
+	if (expanded.length > MAX_OPERATIONS_PER_CALL_LIMIT) return Result.err(invalidInput(`The batch expands to ${expanded.length} edits, over the ${MAX_OPERATIONS_PER_CALL_LIMIT}-edit limit; nothing was written.`, "Split it across calls."));
+	return Result.ok({
+		operations: expanded,
+		options: { suggestChanges: {
+			maxOperations: Math.max(DEFAULT_MAX_OPERATIONS_PER_CALL, expanded.length),
+			...comments && { operationTypes: [...SUGGEST_CHANGES_OPERATION_TYPES, "commentOnBlock"] }
+		} },
+		replaced
+	});
+};
+//#endregion
+export { BATCH_OPERATION_TYPES, expandBatchOperations, withBatchOperations };

package/dist/document.d.ts

@@ -23,12 +23,26 @@ type LoadedFile = {
  * a main document part as an empty document.
  */
 declare const readDocumentFile: (inputPath: string) => Promise<Result<LoadedFile, FolioCliError>>;
+/**
+ * Where a block id comes from. `package` ids are the paragraph's own
+ * `w14:paraId` in the file; `synthetic` ids were minted for a paragraph the
+ * file gives none, and are valid for the fileVersion they were read at. The
+ * first change written to such a file stores them, so from then on they are
+ * the package's own.
+ */
+type FolioBlockIdSource = "package" | "synthetic";
+/** A reviewer over one file and which of its block ids the file itself carries. */
+type OpenedDocument = {
+  reviewer: FolioDocxReviewer;
+  /** Ids minted for paragraphs without one; `null` when none could be minted up front. */
+  mintedIds: ReadonlySet<string> | null;
+};
 /**
  * Parse a loaded file into a headless reviewer. `author` is required for a
  * reviewer that will author changes; reads pass none and never write.
  */
-declare const openReviewer: (file: LoadedFile, author?: string) => Promise<Result<FolioDocxReviewer, FolioCliError>>;
+declare const openReviewer: (file: LoadedFile, author?: string) => Promise<Result<OpenedDocument, FolioCliError>>;
 /** Refuse when the caller's expected version is not the file's current one. */
 declare const checkExpectedVersion: (file: LoadedFile, expected: string | undefined) => Result<void, FolioCliError>;
 //#endregion
-export { type FileIdentity, LoadedFile, MAX_DOCUMENT_BYTES, NO_FOLLOW, checkExpectedVersion, errnoCode, fileVersionOf, isFileVersion, openReviewer, readDocumentFile, sameFile };
+export { type FileIdentity, FolioBlockIdSource, LoadedFile, MAX_DOCUMENT_BYTES, NO_FOLLOW, OpenedDocument, checkExpectedVersion, errnoCode, fileVersionOf, isFileVersion, openReviewer, readDocumentFile, sameFile };

package/dist/document.js

@@ -5,7 +5,7 @@ import { Result } from "better-result";
 import { constants } from "node:fs";
 import { open, realpath, stat } from "node:fs/promises";
 import path from "node:path";
-import { FolioDocxReviewer } from "@stll/folio-core/server";
+import { FolioDocxReviewer, ensureParaIds } from "@stll/folio-core/server";
 //#region src/document.ts
 /** Largest `.docx` the CLI opens; larger inputs are refused before reading. */
 const MAX_DOCUMENT_BYTES = 64 * 1024 * 1024;
@@ -95,16 +95,40 @@ const readDocumentFile = async (inputPath) => {
 	});
 };
 /**
+* Give every paragraph a `w14:paraId`, deterministically from the file's
+* bytes, so the ids a read reports are the ids a later change writes into the
+* file: a paragraph edited by one call is found by the same id in the next.
+* A package the pass cannot or may not rewrite (a signed one) is opened as it
+* is, with position-derived ids.
+*/
+const withParagraphIds = async (bytes) => {
+	const normalized = await Result.tryPromise(() => ensureParaIds(bytes));
+	return normalized.isOk() ? {
+		bytes: normalized.value.docx,
+		mintedIds: new Set(normalized.value.mintedParaIds)
+	} : {
+		bytes,
+		mintedIds: null
+	};
+};
+/**
 * Parse a loaded file into a headless reviewer. `author` is required for a
 * reviewer that will author changes; reads pass none and never write.
 */
-const openReviewer = async (file, author) => await Result.tryPromise({
-	try: () => FolioDocxReviewer.fromBuffer(file.bytes.slice().buffer, { ...author !== void 0 && { author } }),
-	catch: (error) => cliError({
-		code: FOLIO_CLI_ERROR_CODES.invalidDocument,
-		message: `${file.path} is not a readable .docx package: ${describeError(error)}`
-	})
-});
+const openReviewer = async (file, author) => {
+	const { bytes, mintedIds } = await withParagraphIds(file.bytes);
+	const reviewer = await Result.tryPromise({
+		try: () => FolioDocxReviewer.fromBuffer(bytes.slice().buffer, { ...author !== void 0 && { author } }),
+		catch: (error) => cliError({
+			code: FOLIO_CLI_ERROR_CODES.invalidDocument,
+			message: `${file.path} is not a readable .docx package: ${describeError(error)}`
+		})
+	});
+	return reviewer.isErr() ? Result.err(reviewer.error) : Result.ok({
+		reviewer: reviewer.value,
+		mintedIds
+	});
+};
 /** Refuse when the caller's expected version is not the file's current one. */
 const checkExpectedVersion = (file, expected) => {
 	if (expected === void 0 || expected === file.fileVersion) return Result.ok();

package/dist/execute-read.d.ts

@@ -1,7 +1,7 @@
 import { FolioCliError } from "./errors.js";
 import { FolioFileToolSpec } from "./registry.js";
+import { FolioBlockIdSource, OpenedDocument } from "./document.js";
 import { Result } from "better-result";
-import { FolioDocxReviewer } from "@stll/folio-core/server";
 //#region src/execute-read.d.ts
 /** One call against one file: the envelope plus the tool's own arguments. */
 type FileToolCall = {
@@ -26,14 +26,17 @@ type FileReadData = {
   fileVersion: string;
   result: unknown;
 };
-/**
- * Where a block id comes from. `package` ids are the paragraph's own
- * `w14:paraId`; `synthetic` ids are derived from the paragraph's text and
- * position, valid only for the fileVersion they were read at.
- */
-type FolioBlockIdSource = "package" | "synthetic";
 type BlockIdSources = ReadonlyMap<string, FolioBlockIdSource>;
-declare const blockIdSources: (reviewer: FolioDocxReviewer) => BlockIdSources;
+declare const blockIdSources: ({ reviewer, mintedIds }: OpenedDocument) => BlockIdSources;
+/** Where a block inside a table sits: zero-based table, row, and cell indexes. */
+type FolioTableCell = {
+  table: number;
+  row: number;
+  cell: number;
+};
+type TableCells = ReadonlyMap<string, FolioTableCell>;
+/** The table cell of every block that sits in one. */
+declare const tableCells: ({ reviewer }: OpenedDocument) => TableCells;
 type ReadCursor = {
   fileVersion: string;
   afterBlockId: string;
@@ -48,6 +51,7 @@ type ReadDocumentPage = {
 type PageReadDocumentOptions = {
   blocks: readonly unknown[];
   sources: BlockIdSources;
+  cells?: TableCells;
   fileVersion: string;
   args: Readonly<Record<string, unknown>>;
   bounds: FolioReadBounds;
@@ -59,8 +63,8 @@ type PageReadDocumentOptions = {
  * the last block of the previous page and the version it was read at, so a
  * page from one version never continues on another.
  */
-declare const pageReadDocument: ({ blocks, sources, fileVersion, args, bounds, pageByteBudget }: PageReadDocumentOptions) => Result<ReadDocumentPage, FolioCliError>;
+declare const pageReadDocument: ({ blocks, sources, cells, fileVersion, args, bounds, pageByteBudget }: PageReadDocumentOptions) => Result<ReadDocumentPage, FolioCliError>;
 /** Run one read tool, or a compare without a destination. Never writes. */
 declare const executeReadTool: (tool: FolioFileToolSpec, call: FileToolCall, bounds: FolioReadBounds) => Promise<Result<FileReadData, FolioCliError>>;
 //#endregion
-export { CLI_READ_BOUNDS, FileReadData, FileToolCall, FolioBlockIdSource, FolioReadBounds, blockIdSources, encodeReadCursor, executeReadTool, pageReadDocument };
+export { CLI_READ_BOUNDS, FileReadData, FileToolCall, type FolioBlockIdSource, FolioReadBounds, FolioTableCell, blockIdSources, encodeReadCursor, executeReadTool, pageReadDocument, tableCells };

package/dist/execute-read.js

@@ -2,27 +2,38 @@ import { checkExpectedVersion, openReviewer, readDocumentFile } from "./document
 import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
 import { MAX_READ_BLOCKS } from "./registry.js";
 import { Result, panic } from "better-result";
-import { createReviewerBridge } from "@stll/folio-agents/bridges/reviewer";
-import { compareDocxVersions, formatVersionDiffForLLM } from "@stll/folio-agents/compare";
 import { executeFolioToolCallUntyped } from "@stll/folio-agents/execute";
 import { FOLIO_AGENT_TOOL_NAMES } from "@stll/folio-agents/types";
+import { createReviewerBridge } from "@stll/folio-agents/bridges/reviewer";
+import { compareDocxVersions, formatVersionDiffForLLM } from "@stll/folio-agents/compare";
 //#region src/execute-read.ts
 const CLI_READ_BOUNDS = {
 	defaultMaxBlocks: null,
 	maxMatches: 200,
 	maxResponseBytes: null
 };
-const idSourceOf = ({ idStability }) => idStability === "positional" ? "synthetic" : "package";
-const blockIdSources = (reviewer) => new Map(reviewer.snapshot().blocks.map((block) => [block.id, idSourceOf(block)]));
+const idSourceOf = ({ id, idStability }, mintedIds) => {
+	if (mintedIds !== null) return mintedIds.has(id) ? "synthetic" : "package";
+	return idStability === "positional" ? "synthetic" : "package";
+};
+const blockIdSources = ({ reviewer, mintedIds }) => new Map(reviewer.snapshot().blocks.map((block) => [block.id, idSourceOf(block, mintedIds)]));
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const blockIdOf = (block) => isRecord(block) && typeof block["blockId"] === "string" ? block["blockId"] : void 0;
-/** Label each block of a read with where its id comes from. */
-const labelBlocks = (blocks, sources) => blocks.map((block) => {
+/** The table cell of every block that sits in one. */
+const tableCells = ({ reviewer }) => new Map(reviewer.snapshot().blocks.flatMap(({ id, table }) => table === void 0 ? [] : [[id, {
+	table: table.tableIndex,
+	row: table.rowIndex,
+	cell: table.cellIndex
+}]]));
+/** Label each block of a read with where its id comes from and, in a table, its cell. */
+const labelBlocks = (blocks, sources, cells = /* @__PURE__ */ new Map()) => blocks.map((block) => {
 	const blockId = blockIdOf(block);
 	if (blockId === void 0 || !isRecord(block)) return block;
+	const cell = cells.get(blockId);
 	return {
 		...block,
-		blockIdSource: sources.get(blockId) ?? "synthetic"
+		blockIdSource: sources.get(blockId) ?? "synthetic",
+		...cell !== void 0 && { tableCell: cell }
 	};
 });
 const encodeReadCursor = ({ fileVersion, afterBlockId }) => Buffer.from(JSON.stringify({
@@ -51,7 +62,7 @@ const PAGE_ENVELOPE_RESERVE_BYTES = 512;
 * the last block of the previous page and the version it was read at, so a
 * page from one version never continues on another.
 */
-const pageReadDocument = ({ blocks, sources, fileVersion, args, bounds, pageByteBudget }) => {
+const pageReadDocument = ({ blocks, sources, cells, fileVersion, args, bounds, pageByteBudget }) => {
 	const { maxBlocks, cursor } = args;
 	if (maxBlocks !== void 0 && (typeof maxBlocks !== "number" || !Number.isInteger(maxBlocks) || maxBlocks < 1 || maxBlocks > 1e3)) return Result.err(invalidInput(`maxBlocks must be an integer from 1 to ${MAX_READ_BLOCKS}.`));
 	let start = 0;
@@ -73,7 +84,7 @@ const pageReadDocument = ({ blocks, sources, fileVersion, args, bounds, pageByte
 	}
 	const limit = typeof maxBlocks === "number" ? maxBlocks : bounds.defaultMaxBlocks;
 	const end = limit === null ? blocks.length : Math.min(blocks.length, start + limit);
-	const labelled = labelBlocks(blocks.slice(start, end), sources);
+	const labelled = labelBlocks(blocks.slice(start, end), sources, cells);
 	const page = [];
 	let bytes = 0;
 	for (const block of labelled) {
@@ -102,8 +113,8 @@ const unexpectedShape = (tool) => cliError({
 	code: FOLIO_CLI_ERROR_CODES.internal,
 	message: `${tool} returned an unexpected result shape.`
 });
-const runAgentRead = ({ tool, reviewer, fileVersion, args, bounds, pageByteBudget }) => {
-	const bridge = createReviewerBridge(reviewer);
+const runAgentRead = ({ tool, opened, fileVersion, args, bounds, pageByteBudget }) => {
+	const bridge = createReviewerBridge(opened.reviewer);
 	const isReadDocument = tool.agentTool === FOLIO_AGENT_TOOL_NAMES.readDocument;
 	const agentArgs = isReadDocument ? {} : args;
 	const executed = executeFolioToolCallUntyped(tool.agentTool, agentArgs, bridge);
@@ -113,7 +124,8 @@ const runAgentRead = ({ tool, reviewer, fileVersion, args, bounds, pageByteBudge
 		if (!Array.isArray(result)) return Result.err(unexpectedShape(tool.name));
 		return pageReadDocument({
 			blocks: result,
-			sources: blockIdSources(reviewer),
+			sources: blockIdSources(opened),
+			cells: tableCells(opened),
 			fileVersion,
 			args,
 			bounds,
@@ -124,7 +136,7 @@ const runAgentRead = ({ tool, reviewer, fileVersion, args, bounds, pageByteBudge
 		if (!isRecord(result) || !Array.isArray(result["blocks"])) return Result.err(unexpectedShape(tool.name));
 		return Result.ok({
 			...result,
-			blocks: labelBlocks(result["blocks"], blockIdSources(reviewer))
+			blocks: labelBlocks(result["blocks"], blockIdSources(opened), tableCells(opened))
 		});
 	}
 	if (tool.agentTool === FOLIO_AGENT_TOOL_NAMES.findText) {
@@ -188,7 +200,7 @@ const readWithAgentTool = async (tool, call, bounds) => {
 	const { path, fileVersion } = file.value;
 	const result = runAgentRead({
 		tool,
-		reviewer: reviewer.value,
+		opened: reviewer.value,
 		fileVersion,
 		args: call.args,
 		bounds,
@@ -217,4 +229,4 @@ const executeReadTool = async (tool, call, bounds) => {
 	}
 };
 //#endregion
-export { CLI_READ_BOUNDS, blockIdSources, encodeReadCursor, executeReadTool, pageReadDocument };
+export { CLI_READ_BOUNDS, blockIdSources, encodeReadCursor, executeReadTool, pageReadDocument, tableCells };

package/dist/execute-write.d.ts

@@ -1,7 +1,7 @@
 import { FolioCliError } from "./errors.js";
+import { FolioFileToolSpec } from "./registry.js";
 import { FileIdentity } from "./file-system.js";
 import "./document.js";
-import { FolioFileToolSpec } from "./registry.js";
 import { FileToolCall } from "./execute-read.js";
 import { WriteDestination } from "./transaction.js";
 import { Result } from "better-result";