@stll/folio-agents 0.0.1 → 0.1.0

package/dist/compare.js

@@ -0,0 +1,285 @@
+import { diffWordSegments } from "@stll/folio-core/ai-edits";
+import { FolioDocxReviewer, getFolioParaIdFromBlockId } from "@stll/folio-core/server";
+//#region src/compare.ts
+/**
+* Document version-diff engine: compare two `.docx` buffers block by block
+* and produce a structured, LLM-summarizable diff.
+*
+* Both buffers are parsed through {@link FolioDocxReviewer} — the same
+* headless parsing + clean-text path `read_document` / `read_changes` use —
+* so the comparison runs over each document's AS-ACCEPTED view: any pending
+* tracked changes already present in EITHER buffer count as applied before
+* the two are compared. Two documents that agree once their own pending
+* redlines are accepted report as unchanged, even if the underlying
+* tracked-change history differs.
+*
+* ## Alignment
+*
+* Blocks are paired across the two snapshots in three passes, each only
+* considering blocks the previous pass left unpaired:
+*
+* 1. **Stable-id pairing.** Blocks whose ids are equal AND not a `seq-NNNN`
+*    positional fallback ({@link getFolioParaIdFromBlockId} returns non-null)
+*    are paired directly. This covers both id shapes a snapshot can carry:
+*    - A real Word `w14:paraId`: stable identity, independent of text — an
+*      equal-id pair with different text is a genuine edit (`modified`).
+*    - `FolioDocxReviewer`'s deterministic fallback id (assigned when the
+*      source paragraph has no `w14:paraId`), which hashes the paragraph's
+*      TEXT plus its document ordinal. It is structurally indistinguishable
+*      from a real paraId ({@link getFolioParaIdFromBlockId} can't tell them
+*      apart), but pairing on equality is still safe: two equal deterministic
+*      ids necessarily came from identical text at an identical ordinal, so
+*      the pair is always text-equal (`unchanged`) — never a false
+*      `modified`. What it can't do is FIND a paragraph whose ordinal shifted
+*      (an insertion/deletion earlier in the document) even though its text
+*      is unchanged: that pair has two different fallback ids and falls
+*      through to pass 2.
+* 2. **Exact-text pairing.** An order-preserving LCS over remaining blocks,
+*    matched by exact text equality. This is what recovers same-text blocks
+*    that pass 1 missed because a fallback id shifted with the ordinal. Its
+*    O(m·n) table is skipped ({@link exceedsLcsBudget}) once the unpaired
+*    counts on both sides would exceed a fixed cell budget, so a document
+*    with few/no stable ids can't force a quadratic-sized allocation; those
+*    blocks fall through to pass 3 instead.
+* 3. **Positional fallback.** Whatever a monotonicity filter leaves
+*    unpaired is split into the gaps between anchored pairs (pass 1 + 2,
+*    time-ordered); within each gap the shorter side is zipped positionally
+*    against the longer one (`modified`), and any excess on either side is
+*    reported as `added` / `deleted`.
+*
+* The combined anchor set from passes 1 and 2 is re-filtered to the longest
+* increasing subsequence by revised-side index before pass 3 runs, so a
+* pathological crossing match (content reordered across versions) can't
+* produce an out-of-order gap — the alignment always walks both documents
+* forward.
+*/
+const isStableBlockId = (id) => getFolioParaIdFromBlockId(id) !== null;
+const index = (blocks) => blocks.map((block, blockIndex) => ({
+	block,
+	index: blockIndex
+}));
+/**
+* Longest increasing subsequence by `revisedIndex`, assuming `pairs` is
+* already sorted by `baseIndex` ascending. Drops any pair that would make
+* the alignment walk backward in the revised document — the guard against
+* both id collisions (pass 1) and any crossing match (pass 1 + 2 combined).
+*/
+const longestIncreasingByRevisedIndex = (pairs) => {
+	if (pairs.length === 0) return [];
+	const lengths = Array.from({ length: pairs.length }).fill(1);
+	const predecessors = Array.from({ length: pairs.length }).fill(-1);
+	let bestEnd = 0;
+	for (let i = 0; i < pairs.length; i++) {
+		for (let j = 0; j < i; j++) {
+			const current = pairs[j];
+			const candidate = pairs[i];
+			if (!current || !candidate) continue;
+			if (current.revisedIndex < candidate.revisedIndex && (lengths[j] ?? 0) + 1 > (lengths[i] ?? 0)) {
+				lengths[i] = (lengths[j] ?? 0) + 1;
+				predecessors[i] = j;
+			}
+		}
+		if ((lengths[i] ?? 0) > (lengths[bestEnd] ?? 0)) bestEnd = i;
+	}
+	const ordered = [];
+	for (let cursor = bestEnd; cursor !== -1; cursor = predecessors[cursor] ?? -1) {
+		const pair = pairs[cursor];
+		if (pair) ordered.push(pair);
+	}
+	return ordered.toReversed();
+};
+/** Pass 1: pair blocks with equal, non-`seq-NNNN` ids. See the module doc comment. */
+const pairByStableId = (base, revised) => {
+	const revisedIndexById = /* @__PURE__ */ new Map();
+	revised.forEach((block, revisedIndex) => {
+		if (isStableBlockId(block.id)) revisedIndexById.set(block.id, revisedIndex);
+	});
+	const candidates = [];
+	base.forEach((block, baseIndex) => {
+		if (!isStableBlockId(block.id)) return;
+		const revisedIndex = revisedIndexById.get(block.id);
+		if (revisedIndex !== void 0) candidates.push({
+			baseIndex,
+			revisedIndex
+		});
+	});
+	return longestIncreasingByRevisedIndex(candidates);
+};
+/**
+* Cell budget for pass 2's O(m·n) exact-text LCS table (`dp` below allocates
+* `(m + 1) * (n + 1)` numbers). A document with no `w14:paraId`s — or an
+* adversarial one crafted to defeat pass 1 — can leave thousands of blocks
+* unpaired on both sides; without a cap, `pairByExactText` would allocate a
+* quadratic-sized table for it. Past this budget, {@link exceedsLcsBudget}
+* makes pass 2 back off entirely so alignment falls through to pass 3's
+* linear positional zip instead — pairing is less precise for these
+* degenerate inputs, but memory use stays bounded.
+*/
+const MAX_LCS_CELLS = 4e6;
+/** True when an `unpairedBaseCount * unpairedRevisedCount` LCS table would exceed {@link MAX_LCS_CELLS}. */
+const exceedsLcsBudget = (unpairedBaseCount, unpairedRevisedCount) => unpairedBaseCount * unpairedRevisedCount > MAX_LCS_CELLS;
+/** Pass 2: order-preserving LCS by exact text equality over the blocks pass 1 left unpaired. */
+const pairByExactText = (base, revised) => {
+	const m = base.length;
+	const n = revised.length;
+	if (m === 0 || n === 0) return [];
+	if (exceedsLcsBudget(m, n)) return [];
+	const stride = n + 1;
+	const dp = new Int32Array((m + 1) * stride);
+	for (let i = m - 1; i >= 0; i--) {
+		const rowOffset = i * stride;
+		const nextRowOffset = (i + 1) * stride;
+		for (let j = n - 1; j >= 0; j--) {
+			const baseText = base[i]?.block.text;
+			const revisedText = revised[j]?.block.text;
+			dp[rowOffset + j] = baseText === revisedText ? (dp[nextRowOffset + j + 1] ?? 0) + 1 : Math.max(dp[nextRowOffset + j] ?? 0, dp[rowOffset + j + 1] ?? 0);
+		}
+	}
+	const pairs = [];
+	let i = 0;
+	let j = 0;
+	while (i < m && j < n) {
+		const baseEntry = base[i];
+		const revisedEntry = revised[j];
+		if (!baseEntry || !revisedEntry) break;
+		if (baseEntry.block.text === revisedEntry.block.text) {
+			pairs.push({
+				baseIndex: baseEntry.index,
+				revisedIndex: revisedEntry.index
+			});
+			i++;
+			j++;
+			continue;
+		}
+		if ((dp[(i + 1) * stride + j] ?? 0) >= (dp[i * stride + j + 1] ?? 0)) i++;
+		else j++;
+	}
+	return pairs;
+};
+const ELLIPSIS = "…";
+const UNCHANGED_EDGE_CHARS = 30;
+/** Collapse a long `equal`-type run to ~30 chars on each side with an ellipsis in between. */
+const truncateUnchangedRun = (text) => {
+	if (text.length <= 61) return text;
+	return `${text.slice(0, UNCHANGED_EDGE_CHARS)}${ELLIPSIS}${text.slice(-30)}`;
+};
+/** Render one word-diff segment: plain for `equal` (truncated if long), bracketed for `del` / `ins`. */
+const renderSegment = (segment) => {
+	switch (segment.type) {
+		case "equal": return truncateUnchangedRun(segment.text);
+		case "del": return `[-${segment.text}-]`;
+		case "ins": return `{+${segment.text}+}`;
+		default: return "";
+	}
+};
+const formatChangeLine = (change) => {
+	if (change.type === "added") return `+ [${change.blockId}] added: ${change.text}`;
+	if (change.type === "deleted") return `- [${change.blockId}] deleted: ${change.text}`;
+	return `~ [${change.blockId}] modified: ${change.segments.map(renderSegment).join("")}`;
+};
+/**
+* Compare two `.docx` buffers and return a structured, block-level diff.
+* See the module doc comment for the as-accepted comparison semantics and
+* the three-pass alignment algorithm.
+*/
+const compareDocxVersions = async (base, revised) => {
+	const [baseReviewer, revisedReviewer] = await Promise.all([FolioDocxReviewer.fromBuffer(base), FolioDocxReviewer.fromBuffer(revised)]);
+	const baseBlocks = baseReviewer.snapshot().blocks;
+	const revisedBlocks = revisedReviewer.snapshot().blocks;
+	const stableIdAnchors = pairByStableId(baseBlocks, revisedBlocks);
+	const usedBaseIndexes = new Set(stableIdAnchors.map((anchor) => anchor.baseIndex));
+	const usedRevisedIndexes = new Set(stableIdAnchors.map((anchor) => anchor.revisedIndex));
+	const exactTextAnchors = pairByExactText(index(baseBlocks).filter(({ index: i }) => !usedBaseIndexes.has(i)), index(revisedBlocks).filter(({ index: i }) => !usedRevisedIndexes.has(i)));
+	const anchors = longestIncreasingByRevisedIndex([...stableIdAnchors, ...exactTextAnchors].toSorted((a, b) => a.baseIndex - b.baseIndex));
+	const changes = [];
+	const counts = {
+		added: 0,
+		deleted: 0,
+		modified: 0,
+		unchanged: 0
+	};
+	/** Pass 3: positionally zip the leftover blocks in one gap between anchors. */
+	const emitGap = (baseFrom, baseTo, revisedFrom, revisedTo) => {
+		const baseSlice = baseBlocks.slice(baseFrom, baseTo);
+		const revisedSlice = revisedBlocks.slice(revisedFrom, revisedTo);
+		const pairedCount = Math.min(baseSlice.length, revisedSlice.length);
+		for (let k = 0; k < pairedCount; k++) {
+			const baseBlock = baseSlice[k];
+			const revisedBlock = revisedSlice[k];
+			if (!baseBlock || !revisedBlock) continue;
+			if (baseBlock.text === revisedBlock.text) {
+				counts.unchanged++;
+				continue;
+			}
+			counts.modified++;
+			changes.push({
+				type: "modified",
+				blockId: revisedBlock.id,
+				kind: revisedBlock.kind,
+				segments: diffWordSegments(baseBlock.text, revisedBlock.text)
+			});
+		}
+		for (let k = pairedCount; k < baseSlice.length; k++) {
+			const baseBlock = baseSlice[k];
+			if (!baseBlock) continue;
+			counts.deleted++;
+			changes.push({
+				type: "deleted",
+				blockId: baseBlock.id,
+				kind: baseBlock.kind,
+				text: baseBlock.text
+			});
+		}
+		for (let k = pairedCount; k < revisedSlice.length; k++) {
+			const revisedBlock = revisedSlice[k];
+			if (!revisedBlock) continue;
+			counts.added++;
+			changes.push({
+				type: "added",
+				blockId: revisedBlock.id,
+				kind: revisedBlock.kind,
+				text: revisedBlock.text
+			});
+		}
+	};
+	let baseCursor = 0;
+	let revisedCursor = 0;
+	for (const anchor of anchors) {
+		emitGap(baseCursor, anchor.baseIndex, revisedCursor, anchor.revisedIndex);
+		const baseBlock = baseBlocks[anchor.baseIndex];
+		const revisedBlock = revisedBlocks[anchor.revisedIndex];
+		if (baseBlock && revisedBlock) if (baseBlock.text === revisedBlock.text) counts.unchanged++;
+		else {
+			counts.modified++;
+			changes.push({
+				type: "modified",
+				blockId: revisedBlock.id,
+				kind: revisedBlock.kind,
+				segments: diffWordSegments(baseBlock.text, revisedBlock.text)
+			});
+		}
+		baseCursor = anchor.baseIndex + 1;
+		revisedCursor = anchor.revisedIndex + 1;
+	}
+	emitGap(baseCursor, baseBlocks.length, revisedCursor, revisedBlocks.length);
+	return {
+		changes,
+		summaryCounts: counts
+	};
+};
+/**
+* Render a {@link FolioAgentVersionDiff} as compact, deterministic text for a
+* model prompt: a header line with the summary counts, then one line per
+* change — `~ [blockId] modified: …`, `+ [blockId] added: …`,
+* `- [blockId] deleted: …`. A modified block's segments render inline using
+* `git diff --word-diff` porcelain conventions (`[-removed-]`, `{+added+}`,
+* plain text for unchanged runs, truncated to ~30 characters on each side
+* when long). The format is stable across calls — do not change it without
+* checking `compare.test.ts`.
+*/
+const formatVersionDiffForLLM = (diff) => {
+	const { added, deleted, modified, unchanged } = diff.summaryCounts;
+	return [`Version diff: ${added} added, ${deleted} deleted, ${modified} modified, ${unchanged} unchanged`, ...diff.changes.map(formatChangeLine)].join("\n");
+};
+//#endregion
+export { compareDocxVersions, exceedsLcsBudget, formatVersionDiffForLLM };

package/dist/execute.d.ts

@@ -0,0 +1,19 @@
+import { FolioToolCallResult } from "./types.js";
+import { FolioAgentBridge } from "./bridge.js";
+
+//#region src/execute.d.ts
+/**
+ * Execute one tool call against a {@link FolioAgentBridge}. Every EXPECTED
+ * failure — bad arguments, an unknown tool name, a capability the bridge does
+ * not implement, a domain-level skip — comes back as `{ ok: false, error }`
+ * with a message meant to be fed straight back to the model; it is never
+ * thrown. This function is the sole boundary layer allowed to catch an
+ * unexpected throw from the bridge and fold it into that same shape (per
+ * AGENTS.md, try/catch is acceptable at boundary layers).
+ *
+ * Every bridge member used here ({@link FolioDocxReviewer} and the live-editor
+ * ref) is synchronous, so this stays synchronous too.
+ */
+declare const executeFolioToolCall: (name: string, args: unknown, bridge: FolioAgentBridge) => FolioToolCallResult;
+//#endregion
+export { executeFolioToolCall };

package/dist/execute.js

@@ -0,0 +1,188 @@
+import { explainTextTooLong, parseAddCommentInput, parseSuggestChangesInput } from "./parse.js";
+import { FOLIO_AGENT_TOOL_NAMES } from "./types.js";
+//#region src/execute.ts
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isNonEmptyString = (value) => typeof value === "string" && value.length > 0;
+const ok = (result) => ({
+	ok: true,
+	result
+});
+const fail = (error) => ({
+	ok: false,
+	error
+});
+const VALID_TOOL_NAMES = Object.values(FOLIO_AGENT_TOOL_NAMES);
+/** `find_text` requires a short `query` and caps how much of a large match set it returns in one call. */
+const MAX_QUERY_LENGTH = 1e3;
+const MAX_FIND_MATCHES = 200;
+/**
+* Execute one tool call against a {@link FolioAgentBridge}. Every EXPECTED
+* failure — bad arguments, an unknown tool name, a capability the bridge does
+* not implement, a domain-level skip — comes back as `{ ok: false, error }`
+* with a message meant to be fed straight back to the model; it is never
+* thrown. This function is the sole boundary layer allowed to catch an
+* unexpected throw from the bridge and fold it into that same shape (per
+* AGENTS.md, try/catch is acceptable at boundary layers).
+*
+* Every bridge member used here ({@link FolioDocxReviewer} and the live-editor
+* ref) is synchronous, so this stays synchronous too.
+*/
+const executeFolioToolCall = (name, args, bridge) => {
+	if (!VALID_TOOL_NAMES.includes(name)) return fail(`Unknown tool "${name}". Valid tools: ${VALID_TOOL_NAMES.join(", ")}.`);
+	try {
+		return dispatch(name, args, bridge);
+	} catch (error) {
+		return fail(error instanceof Error ? error.message : String(error));
+	}
+};
+const dispatch = (name, args, bridge) => {
+	if (name === FOLIO_AGENT_TOOL_NAMES.readDocument) return readDocument(bridge);
+	if (name === FOLIO_AGENT_TOOL_NAMES.findText) return findText(args, bridge);
+	if (name === FOLIO_AGENT_TOOL_NAMES.readComments) return readComments(args, bridge);
+	if (name === FOLIO_AGENT_TOOL_NAMES.readChanges) return ok(bridge.getChanges());
+	if (name === FOLIO_AGENT_TOOL_NAMES.addComment) return addComment(args, bridge);
+	if (name === FOLIO_AGENT_TOOL_NAMES.suggestChanges) return suggestChanges(args, bridge);
+	if (name === FOLIO_AGENT_TOOL_NAMES.replyComment) return replyComment(args, bridge);
+	if (name === FOLIO_AGENT_TOOL_NAMES.resolveComment) return resolveComment(args, bridge);
+	if (name === FOLIO_AGENT_TOOL_NAMES.readPage) return readPage(args, bridge);
+	if (name === FOLIO_AGENT_TOOL_NAMES.readSelection) return readSelection(bridge);
+	if (name === FOLIO_AGENT_TOOL_NAMES.scrollToBlock) return scrollToBlock(args, bridge);
+	return fail(`Unknown tool "${name}".`);
+};
+const readDocument = (bridge) => {
+	const { blocks } = bridge.snapshot();
+	return ok(blocks.map((block) => ({
+		blockId: block.id,
+		kind: block.kind,
+		text: block.text
+	})));
+};
+const CONTEXT_RADIUS = 40;
+const findTextMatches = (blocks, query, matchCase) => {
+	const matches = [];
+	let totalMatches = 0;
+	const needle = matchCase ? query : query.toLowerCase();
+	for (const block of blocks) {
+		const haystack = matchCase ? block.text : block.text.toLowerCase();
+		let occurrence = 0;
+		let fromIndex = 0;
+		for (;;) {
+			const at = haystack.indexOf(needle, fromIndex);
+			if (at === -1) break;
+			totalMatches += 1;
+			if (matches.length < MAX_FIND_MATCHES) {
+				const contextStart = Math.max(0, at - CONTEXT_RADIUS);
+				const contextEnd = Math.min(block.text.length, at + query.length + CONTEXT_RADIUS);
+				matches.push({
+					blockId: block.id,
+					occurrenceInBlock: occurrence,
+					context: block.text.slice(contextStart, contextEnd)
+				});
+			}
+			occurrence += 1;
+			fromIndex = at + needle.length;
+		}
+	}
+	return {
+		matches,
+		totalMatches
+	};
+};
+const findText = (args, bridge) => {
+	if (!isPlainObject(args)) return fail("find_text expects an object with a non-empty `query` string.");
+	const query = args["query"];
+	const matchCase = args["matchCase"];
+	if (!isNonEmptyString(query)) return fail("find_text requires a non-empty string `query`.");
+	if (query.length > MAX_QUERY_LENGTH) return fail(`find_text's \`query\` is ${query.length.toLocaleString()} characters, over the ${MAX_QUERY_LENGTH.toLocaleString()}-character limit; shorten it.`);
+	if (matchCase !== void 0 && typeof matchCase !== "boolean") return fail("find_text's `matchCase` must be a boolean when provided.");
+	const { blocks } = bridge.snapshot();
+	const { matches, totalMatches } = findTextMatches(blocks, query, matchCase === true);
+	return ok({
+		matches,
+		truncated: totalMatches > matches.length,
+		totalMatches
+	});
+};
+const isCommentFilter = (value) => value === "all" || value === "open" || value === "resolved";
+const readComments = (args, bridge) => {
+	const filter = isPlainObject(args) ? args["filter"] : void 0;
+	if (filter !== void 0 && !isCommentFilter(filter)) return fail("read_comments' `filter` must be one of \"all\", \"open\", \"resolved\" when provided.");
+	const comments = bridge.getComments();
+	if (filter === void 0 || filter === "all") return ok(comments);
+	const wantResolved = filter === "resolved";
+	return ok(comments.filter((comment) => comment.resolved === wantResolved));
+};
+/**
+* Turn a `FolioAIEditSkipReason` into a plain-language reason a model can act
+* on — what to change and retry, not just a machine code.
+*/
+const explainSkipReason = (reason) => {
+	if (reason === "missingBlock") return "blockId not found; re-read the document (read_document or find_text) and retry with a fresh block id.";
+	if (reason === "changedBlock") return "the block changed since your snapshot; re-read the document and retry with fresh ids.";
+	if (reason === "ambiguousFind") return "`find` matches more than once in this block; narrow it so it matches exactly once, or use a replaceBlock operation instead.";
+	if (reason === "missingFind") return "`find` was not found in this block; re-read the block's current text and retry.";
+	if (reason === "unsupportedBlock") return "this block kind does not support this operation.";
+	if (reason === "emptyOperation") return "this operation has no effect; nothing to apply.";
+	if (reason === "noopOperation") return "this operation would not change the document (the text already matches what you asked for).";
+	return reason;
+};
+const summarizeApplyResult = (result) => ({
+	applied: result.applied.map((entry) => ({ id: entry.id })),
+	skipped: result.skipped.map((entry) => ({
+		id: entry.id,
+		reason: explainSkipReason(entry.reason)
+	}))
+});
+const addComment = (args, bridge) => {
+	const parsed = parseAddCommentInput(args);
+	if (!parsed.ok) return fail(parsed.error);
+	return ok(summarizeApplyResult(bridge.applyOperations([parsed.operation])));
+};
+const suggestChanges = (args, bridge) => {
+	const parsed = parseSuggestChangesInput(args);
+	if (!parsed.ok) return fail(parsed.error);
+	return ok(summarizeApplyResult(bridge.applyOperations(parsed.operations)));
+};
+const replyComment = (args, bridge) => {
+	if (!isPlainObject(args)) return fail("reply_comment expects an object with `commentId` and `text` strings.");
+	const commentId = args["commentId"];
+	const text = args["text"];
+	if (!isNonEmptyString(commentId)) return fail("reply_comment requires a non-empty string `commentId`.");
+	if (!isNonEmptyString(text)) return fail("reply_comment requires a non-empty string `text`.");
+	if (text.length > 1e5) return fail(explainTextTooLong("reply_comment's `text`", text.length));
+	if (!bridge.replyToComment(commentId, text)) return fail(`No comment with id "${commentId}" was found.`);
+	return ok({ replied: true });
+};
+const resolveComment = (args, bridge) => {
+	if (!isPlainObject(args)) return fail("resolve_comment expects an object with a `commentId` string.");
+	const commentId = args["commentId"];
+	const reopen = args["reopen"];
+	if (!isNonEmptyString(commentId)) return fail("resolve_comment requires a non-empty string `commentId`.");
+	if (reopen !== void 0 && typeof reopen !== "boolean") return fail("resolve_comment's `reopen` must be a boolean when provided.");
+	const resolved = reopen !== true;
+	if (!bridge.resolveComment(commentId, resolved)) return fail(`No comment with id "${commentId}" was found.`);
+	return ok({ resolved });
+};
+const readPage = (args, bridge) => {
+	if (!bridge.getPageText) return fail("This editor surface does not support read_page (no live paginated view).");
+	const page = isPlainObject(args) ? args["page"] : void 0;
+	if (typeof page !== "number" || !Number.isInteger(page) || page < 1) return fail("read_page requires an integer `page` >= 1.");
+	const pageCount = bridge.getPageCount?.();
+	if (pageCount !== void 0 && page > pageCount) return fail(`read_page's \`page\` (${page}) exceeds the document's page count (${pageCount}).`);
+	return ok({
+		page,
+		text: bridge.getPageText(page)
+	});
+};
+const readSelection = (bridge) => {
+	if (!bridge.getSelectionText) return fail("This editor surface does not support read_selection (no live selection).");
+	return ok({ text: bridge.getSelectionText() });
+};
+const scrollToBlock = (args, bridge) => {
+	if (!bridge.scrollToBlock) return fail("This editor surface does not support scroll_to_block (no live editor view).");
+	const blockId = isPlainObject(args) ? args["blockId"] : void 0;
+	if (!isNonEmptyString(blockId)) return fail("scroll_to_block requires a non-empty string `blockId`.");
+	return ok({ scrolled: bridge.scrollToBlock(blockId) });
+};
+//#endregion
+export { executeFolioToolCall };

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { FOLIO_AGENT_TOOL_NAMES, FolioAgentApplyOperationsSummary, FolioAgentBlock, FolioAgentChange, FolioAgentComment, FolioAgentCommentFilter, FolioAgentCommentReply, FolioAgentTextMatch, FolioAgentToolDefinition, FolioAgentToolName, FolioToolCallResult } from "./types.js";
+import { FolioAgentBridge } from "./bridge.js";
+import { CreateEditorRefBridgeOptions, FolioAgentEditorRefLike, createEditorRefBridge } from "./bridges/editor-ref.js";
+import { CreateReviewerBridgeOptions, createReviewerBridge } from "./bridges/reviewer.js";
+import { FolioAgentBlockDiff, FolioAgentVersionDiff, FolioAgentVersionDiffSegment, compareDocxVersions, formatVersionDiffForLLM } from "./compare.js";
+import { executeFolioToolCall } from "./execute.js";
+import { ParseAddCommentResult, ParseSuggestChangesResult, parseAddCommentInput, parseSuggestChangesInput } from "./parse.js";
+import { AnthropicToolDefinition, OpenAIToolDefinition, toAnthropicTools, toOpenAITools } from "./providers.js";
+import { FOLIO_AGENT_TOOLS, getFolioToolDefinitions } from "./tools.js";
+export { type AnthropicToolDefinition, type CreateEditorRefBridgeOptions, type CreateReviewerBridgeOptions, FOLIO_AGENT_TOOLS, FOLIO_AGENT_TOOL_NAMES, type FolioAgentApplyOperationsSummary, type FolioAgentBlock, type FolioAgentBlockDiff, type FolioAgentBridge, type FolioAgentChange, type FolioAgentComment, type FolioAgentCommentFilter, type FolioAgentCommentReply, type FolioAgentEditorRefLike, type FolioAgentTextMatch, type FolioAgentToolDefinition, type FolioAgentToolName, type FolioAgentVersionDiff, type FolioAgentVersionDiffSegment, type FolioToolCallResult, type OpenAIToolDefinition, type ParseAddCommentResult, type ParseSuggestChangesResult, compareDocxVersions, createEditorRefBridge, createReviewerBridge, executeFolioToolCall, formatVersionDiffForLLM, getFolioToolDefinitions, parseAddCommentInput, parseSuggestChangesInput, toAnthropicTools, toOpenAITools };

package/dist/index.js

@@ -0,0 +1,9 @@
+import { compareDocxVersions, formatVersionDiffForLLM } from "./compare.js";
+import { parseAddCommentInput, parseSuggestChangesInput } from "./parse.js";
+import { FOLIO_AGENT_TOOL_NAMES } from "./types.js";
+import { executeFolioToolCall } from "./execute.js";
+import { createEditorRefBridge } from "./bridges/editor-ref.js";
+import { createReviewerBridge } from "./bridges/reviewer.js";
+import { toAnthropicTools, toOpenAITools } from "./providers.js";
+import { FOLIO_AGENT_TOOLS, getFolioToolDefinitions } from "./tools.js";
+export { FOLIO_AGENT_TOOLS, FOLIO_AGENT_TOOL_NAMES, compareDocxVersions, createEditorRefBridge, createReviewerBridge, executeFolioToolCall, formatVersionDiffForLLM, getFolioToolDefinitions, parseAddCommentInput, parseSuggestChangesInput, toAnthropicTools, toOpenAITools };

package/dist/parse.d.ts

@@ -0,0 +1,45 @@
+import { FolioAIEditOperation } from "@stll/folio-core/server";
+
+//#region src/parse.d.ts
+/**
+ * Hard caps on `suggest_changes` / `add_comment` / `reply_comment` input
+ * size. Without these, a single tool call could ask the bridge to apply an
+ * unbounded number of operations, or push an arbitrarily large string into
+ * the tracked-changes engine, in one shot. `execute.ts` reuses
+ * {@link MAX_OPERATION_TEXT_LENGTH} for `reply_comment`'s text cap too, so
+ * the limit stays a single number shared across every text-bearing tool.
+ */
+declare const MAX_OPERATIONS_PER_CALL = 50;
+declare const MAX_OPERATION_TEXT_LENGTH = 100000;
+/** Plain-language error for a string argument over {@link MAX_OPERATION_TEXT_LENGTH}. */
+declare const explainTextTooLong: (label: string, length: number) => string;
+/** Result of {@link parseAddCommentInput}. */
+type ParseAddCommentResult = {
+  ok: true;
+  operation: FolioAIEditOperation;
+} | {
+  ok: false;
+  error: string;
+};
+/**
+ * Validate `add_comment`'s raw tool-call arguments and build the
+ * `commentOnBlock` {@link FolioAIEditOperation} it applies. Pure: does not
+ * touch a bridge or document.
+ */
+declare const parseAddCommentInput: (args: unknown) => ParseAddCommentResult;
+/** Result of {@link parseSuggestChangesInput}. */
+type ParseSuggestChangesResult = {
+  ok: true;
+  operations: FolioAIEditOperation[];
+} | {
+  ok: false;
+  error: string;
+};
+/**
+ * Validate `suggest_changes`' raw tool-call arguments and build the
+ * {@link FolioAIEditOperation}s it applies. Pure: does not touch a bridge or
+ * document.
+ */
+declare const parseSuggestChangesInput: (args: unknown) => ParseSuggestChangesResult;
+//#endregion
+export { MAX_OPERATIONS_PER_CALL, MAX_OPERATION_TEXT_LENGTH, ParseAddCommentResult, ParseSuggestChangesResult, explainTextTooLong, parseAddCommentInput, parseSuggestChangesInput };