@stll/folio-agents 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,225 @@
+# @stll/folio-agents
+
+A framework-neutral (React-free, DOM-free) LLM tool layer over
+[`@stll/folio-core`](https://www.npmjs.com/package/@stll/folio-core)'s AI-edits
+engine: function-calling tool definitions and an executor so a model can read
+and mutate a `.docx` document, with every mutation landing as a tracked change
+or comment pending human review.
+
+Part of [stella](https://github.com/stella/stella), an open-source legal workspace.
+
+## Install
+
+```sh
+bun add @stll/folio-agents
+```
+
+`@stll/folio-core` is installed automatically as a dependency.
+
+## Tools
+
+| Tool              | What it does                                                                                                                  |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `read_document`   | Read the document body as `{ blockId, kind, text }` blocks                                                                    |
+| `find_text`       | Search block text for a string; returns block id, occurrence, and context per match                                           |
+| `read_comments`   | Read comment threads (author, text, resolved, anchored block, replies)                                                        |
+| `read_changes`    | Read pending tracked changes (insertions/deletions) awaiting review                                                           |
+| `add_comment`     | Attach a comment to a block, optionally quoting specific text                                                                 |
+| `suggest_changes` | Propose `replaceInBlock` / `insertAfterBlock` / `insertBeforeBlock` / `replaceBlock` / `deleteBlock` edits as tracked changes |
+| `reply_comment`   | Reply to a comment thread                                                                                                     |
+| `resolve_comment` | Resolve or reopen a comment thread                                                                                            |
+| `read_page`       | Read a page's plain text (live editor only)                                                                                   |
+| `read_selection`  | Read the current text selection (live editor only)                                                                            |
+| `scroll_to_block` | Scroll the live editor to a block (live editor only)                                                                          |
+
+Block ids and comment ids always come from a prior tool call
+(`read_document`, `find_text`, `read_comments`) within the same conversation —
+never guess them. `suggest_changes` reports a plain-language reason when an
+operation is skipped (e.g. the block changed since it was last read), so the
+model can re-read and retry.
+
+### Untrusted documents
+
+`read_document`, `read_comments`, `read_changes`, and `find_text` return
+document content verbatim. If a `.docx` comes from an untrusted party, its
+text can carry prompt-injection payloads straight into the model's context —
+treat any document-derived tool result as untrusted model input, the same way
+you would treat a fetched web page. Mutations stay safe by design regardless:
+`suggest_changes` and `add_comment` land as tracked changes or comments
+pending human review, so an injected instruction can propose an edit but
+cannot silently apply one.
+
+## Headless quickstart
+
+```ts
+import { FolioDocxReviewer } from "@stll/folio-core/server";
+import {
+  createReviewerBridge,
+  executeFolioToolCall,
+  getFolioToolDefinitions,
+  toAnthropicTools,
+} from "@stll/folio-agents";
+
+const reviewer = await FolioDocxReviewer.fromBuffer(docxBuffer, { author: "AI" });
+const bridge = createReviewerBridge(reviewer);
+const tools = toAnthropicTools(getFolioToolDefinitions());
+
+// Inside your tool-use loop, for each tool_use block the model emits:
+const result = executeFolioToolCall(toolName, toolInput, bridge);
+// result: { ok: true, result } | { ok: false, error } — feed either back to the model.
+
+const reviewedBuffer = await reviewer.toBuffer();
+```
+
+## Live-editor quickstart
+
+```ts
+import { createEditorRefBridge, executeFolioToolCall } from "@stll/folio-agents";
+
+// `docxEditorRef` is a DocxEditorRef from @stll/folio-react (or any object
+// structurally matching FolioAgentEditorRefLike).
+const bridge = createEditorRefBridge({
+  ref: docxEditorRef.current,
+  author: "AI",
+  getComments: () => comments,
+  setComments: (next) => setComments(next),
+});
+
+const result = executeFolioToolCall("suggest_changes", { operations: [...] }, bridge);
+```
+
+On a `DocxEditorRef` that implements the read surface (`getTrackedChanges`,
+`getCommentAnchors`, `getSelectionText`, `getPageText`), the editor-ref bridge
+has full parity with the headless one: `read_changes` returns real tracked
+changes, comment entries carry a resolved `blockId` / `quote`, and `read_page`
+/ `read_selection` work against the live view. Against an older ref that
+predates those methods, the bridge degrades per-member: `read_changes`
+returns `[]`, comment entries fall back to `blockId: null` / `quote: ""`, and
+`read_page` / `read_selection` report an unsupported-capability error — see
+`src/bridges/editor-ref.ts` for the exact fallback per method.
+
+### Host-managed review queue
+
+A host with its own review-queue UX (its own place to store proposed edits
+pending approval, distinct from folio's tracked-changes redlines) can validate
+a model's `suggest_changes` / `add_comment` tool-call arguments with the same
+canonical rules `executeFolioToolCall` uses, without applying them through a
+bridge at all:
+
+```ts
+import { parseSuggestChangesInput } from "@stll/folio-agents";
+
+const parsed = parseSuggestChangesInput(toolInput);
+if (!parsed.ok) {
+  // Feed `parsed.error` back to the model as the tool result, same as
+  // executeFolioToolCall would.
+} else {
+  // `parsed.operations` is FolioAIEditOperation[] — route it into your own
+  // review queue instead of bridge.applyOperations(...).
+  reviewQueue.enqueue(parsed.operations);
+}
+```
+
+`parseAddCommentInput` is the equivalent for `add_comment`, returning
+`{ ok: true; operation }` on success.
+
+## Summarizing changes
+
+Two different questions come up under "what changed":
+
+**1. Pending tracked changes in one document** — what a human reviewer would
+see as redlines right now. Use the `read_changes` tool (or
+`reviewer.getChanges()` directly) and hand the insertions/deletions to the
+model:
+
+```ts
+const changes = reviewer.getChanges();
+const prompt = `Summarize these pending edits for a reviewer:\n${changes
+  .map((c) => `${c.type === "insertion" ? "+" : "-"} [${c.blockId}] ${c.text}`)
+  .join("\n")}`;
+```
+
+**2. Between two saved versions** — what changed across two `.docx` buffers,
+independent of whether either one has any tracked changes at all. Use
+`compareDocxVersions` + `formatVersionDiffForLLM`:
+
+```ts
+import { compareDocxVersions, formatVersionDiffForLLM } from "@stll/folio-agents";
+
+const diff = await compareDocxVersions(previousVersionBuffer, currentVersionBuffer);
+const prompt = `Summarize what changed between these two document versions:\n${formatVersionDiffForLLM(diff)}`;
+// -> feed `prompt` to your model as a normal user/system message.
+```
+
+Both recipes compare the AS-ACCEPTED view of a document: any tracked changes
+already pending in a buffer count as already applied before the comparison
+runs (`compareDocxVersions` parses each buffer through the same
+`FolioDocxReviewer` snapshot `read_document` uses). Diffing two versions that
+each have their own uncommitted redlines still produces a clean, readable diff
+instead of raw markup noise.
+
+`compareDocxVersions` ships as a plain async function, not a tool definition:
+a model can describe a tool call, but it can't attach two document buffers to
+one — buffers aren't JSON-serializable tool arguments a model could produce.
+The natural shape is a host-side tool keyed by version identifiers instead
+(e.g. a server tool the model calls with two stored version ids, which your
+backend resolves to buffers, diffs, and returns the formatted text for).
+
+## TanStack AI
+
+TanStack AI's `toolDefinition` accepts a raw JSON Schema object as
+`inputSchema`, so the definitions plug in without any wrapper:
+
+```ts
+import { toolDefinition } from "@tanstack/ai";
+import { getFolioToolDefinitions } from "@stll/folio-agents";
+
+const defs = getFolioToolDefinitions().map((def) =>
+  toolDefinition({
+    name: def.name,
+    description: def.description,
+    inputSchema: def.inputSchema,
+  }),
+);
+// Client-executed tools: run executeFolioToolCall(name, args, bridge) where the
+// live editor lives and report the payload back via your chat client's
+// addToolResult; server-executed tools: chain .server((args) => ...) instead.
+```
+
+The schemas stay within a conservative JSON Schema subset (`type: "object"`,
+`properties`, `required`, `enum`, `additionalProperties: false`, plain arrays).
+Some providers (e.g. Gemini's OpenAPI-3.0 subset) reject less common keywords;
+if your stack projects tool schemas through a provider-safe filter, these
+definitions pass through it unchanged.
+
+## Vercel AI SDK
+
+This package ships no `ai` dependency; map its tool definitions with the AI
+SDK's own `jsonSchema()` / `tool()` helpers:
+
+```ts
+import { jsonSchema, tool } from "ai";
+import { executeFolioToolCall, getFolioToolDefinitions } from "@stll/folio-agents";
+
+const tools = Object.fromEntries(
+  getFolioToolDefinitions().map((def) => [
+    def.name,
+    tool({
+      description: def.description,
+      inputSchema: jsonSchema(def.inputSchema),
+      execute: async (input) => executeFolioToolCall(def.name, input, bridge),
+    }),
+  ]),
+);
+```
+
+## Acknowledgements
+
+folio began as a private fork of [Eigenpal](https://eigenpal.com)'s
+[docx-editor](https://github.com/eigenpal/docx-editor). The original license
+and copyright are preserved in
+[`NOTICE.md`](https://github.com/stella/folio/blob/main/packages/core/NOTICE.md).
+
+## License
+
+Apache-2.0

package/dist/bridge.d.ts

@@ -0,0 +1,36 @@
+import { FolioAgentChange, FolioAgentComment } from "./types.js";
+import { FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditSnapshot } from "@stll/folio-core/server";
+
+//#region src/bridge.d.ts
+/**
+ * The structural contract every folio surface (headless reviewer, live
+ * editor) implements so the tool executor can drive either one identically.
+ * `bridges/reviewer.ts` and `bridges/editor-ref.ts` are the two shipped
+ * implementations; a host app can also hand-write one.
+ *
+ * The required members are available on every surface. The optional members
+ * are live-editor-only capabilities (paging, selection, scrolling): when a
+ * bridge omits one, {@link executeFolioToolCall} reports the corresponding
+ * tool call as an unsupported-capability error rather than throwing, so a
+ * model driving a headless reviewer gets a plain-language reason instead of a
+ * crash.
+ */
+type FolioAgentBridge = {
+  /** Snapshot the current document into AI-facing blocks + anchors. */snapshot(): FolioAIEditSnapshot;
+  /**
+   * Apply operations against the current document. The bridge decides mode
+   * (tracked-changes by default) and author internally — callers only supply
+   * the operations.
+   */
+  applyOperations(operations: FolioAIEditOperation[]): FolioAIEditApplyResult; /** The comment threads present in the document. */
+  getComments(): FolioAgentComment[]; /** The pending tracked changes (insertions/deletions) present in the document. */
+  getChanges(): FolioAgentChange[]; /** Reply to a comment thread. Returns `false` when the target comment does not exist. */
+  replyToComment(commentId: string, text: string): boolean; /** Mark a comment thread resolved or reopen it. Returns `false` when the target comment does not exist. */
+  resolveComment(commentId: string, resolved: boolean): boolean; /** Scroll the live editor to the given block and select it. */
+  scrollToBlock?(blockId: string): boolean; /** The user's current text selection in the live editor, as plain text. */
+  getSelectionText?(): string; /** Total page count in the live, paginated editor. */
+  getPageCount?(): number; /** Plain text of the given 1-based page in the live editor. */
+  getPageText?(page: number): string;
+};
+//#endregion
+export { FolioAgentBridge };

package/dist/bridges/editor-ref.d.ts

@@ -0,0 +1,90 @@
+import { FolioAgentBridge } from "../bridge.js";
+import { FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditSnapshot } from "@stll/folio-core/server";
+import { FolioCommentAnchor, FolioReviewChange as FolioReviewChange$1 } from "@stll/folio-core/ai-edits";
+import { Comment } from "@stll/folio-core/types/content";
+
+//#region src/bridges/editor-ref.d.ts
+/**
+ * Minimal structural slice of `DocxEditorRef` (`packages/react`) this bridge
+ * drives — declared locally per AGENTS.md's react-free-core rule (agents
+ * stays framework-neutral; it may not import a React-package type), covering
+ * ONLY the members actually called below.
+ *
+ * The read-surface members (`getTrackedChanges`, `getCommentAnchors`,
+ * `getSelectionText`, `getPageText`) are OPTIONAL here even though the
+ * current `DocxEditorRef` always implements them: a ref built against an
+ * older `@stll/folio-react` (before these methods existed) still
+ * structurally satisfies this type, and `createEditorRefBridge` below falls
+ * back to the pre-existing degraded behavior for each one it does not find.
+ */
+type FolioAgentEditorRefLike = {
+  /** `DocxEditorRef.createAIEditSnapshot`. `null` before the editor view mounts. */createAIEditSnapshot(): FolioAIEditSnapshot | null; /** `DocxEditorRef.applyAIEditOperations`. */
+  applyAIEditOperations(options: {
+    snapshot: FolioAIEditSnapshot;
+    operations: FolioAIEditOperation[];
+    mode?: FolioAIEditApplyMode;
+    author?: string;
+  }): FolioAIEditApplyResult; /** `DocxEditorRef.scrollToBlock`. */
+  scrollToBlock(blockId: string, snapshot?: FolioAIEditSnapshot): boolean; /** `DocxEditorRef.getTotalPages`. */
+  getTotalPages(): number;
+  /**
+   * `DocxEditorRef.getTrackedChanges`. When present, `getChanges()` maps its
+   * output to {@link FolioAgentChange} (same mapping as the reviewer
+   * bridge's); when absent, `getChanges()` returns `[]`.
+   */
+  getTrackedChanges?(): FolioReviewChange$1[];
+  /**
+   * `DocxEditorRef.getCommentAnchors`. When present, `getComments()` merges
+   * each anchor's `blockId` / `quote` into the matching host-state comment
+   * by `commentId`; when absent, those fields stay `null` / `""`.
+   */
+  getCommentAnchors?(): FolioCommentAnchor[];
+  /**
+   * `DocxEditorRef.getSelectionText`. The bridge exposes `getSelectionText`
+   * only when this is present, so `read_selection` reports an
+   * unsupported-capability error on a ref that lacks it.
+   */
+  getSelectionText?(): string;
+  /**
+   * `DocxEditorRef.getPageText`. The bridge exposes `getPageText` only when
+   * this is present, so `read_page` reports an unsupported-capability error
+   * on a ref that lacks it. See {@link createEditorRefBridge} for how a
+   * `null` return (page in range, layout not yet computed) is handled.
+   */
+  getPageText?(page: number): string | null;
+};
+/** Options for {@link createEditorRefBridge}. */
+type CreateEditorRefBridgeOptions = {
+  ref: FolioAgentEditorRefLike; /** Author attributed to tracked changes, comments, and replies this bridge creates. */
+  author: string; /** Read the host app's current comment state (e.g. the `DocxEditor` `comments` prop). */
+  getComments(): Comment[]; /** Replace the host app's comment state (e.g. the setter backing that same prop). */
+  setComments(comments: Comment[]): void; /** `"tracked-changes"` (default) produces ins/del redlines; `"direct"` edits in place. */
+  mode?: FolioAIEditApplyMode;
+};
+/**
+ * Build a {@link FolioAgentBridge} over a live `DocxEditor` ref plus the host
+ * app's comment state.
+ *
+ * Comments live in app-controlled React state (the `DocxEditor` `comments`
+ * prop), not on the ref, so this factory takes `getComments`/`setComments` to
+ * read and write that state directly — the same pair the host already passes
+ * to `DocxEditor`.
+ *
+ * KNOWN LIMITATIONS (only apply to a `ref` that predates the read-surface
+ * additions below; the current `DocxEditorRef` implements all four):
+ * - `getChanges()` returns `[]` when `ref.getTrackedChanges` is absent, since
+ *   there is then no ref-level way to enumerate tracked changes from
+ *   ProseMirror mark attributes.
+ * - Comment entries fall back to `blockId: null` / `quote: ""` when
+ *   `ref.getCommentAnchors` is absent, since there is then no ref-level way
+ *   to resolve a comment's anchor against the live ProseMirror document.
+ * - `read_page` / `read_selection` report an unsupported-capability error
+ *   when `ref.getPageText` / `ref.getSelectionText` are absent: this bridge
+ *   omits the corresponding `getPageText` / `getSelectionText` member
+ *   entirely rather than implementing it as a no-op, which is what tells
+ *   `executeFolioToolCall` to report the tool as unsupported instead of
+ *   throwing.
+ */
+declare const createEditorRefBridge: (options: CreateEditorRefBridgeOptions) => FolioAgentBridge;
+//#endregion
+export { CreateEditorRefBridgeOptions, FolioAgentEditorRefLike, createEditorRefBridge };

package/dist/bridges/editor-ref.js

@@ -0,0 +1,139 @@
+import { toAgentChange } from "./shared.js";
+import { createReply } from "@stll/folio-core/docx/replyToComment";
+//#region src/bridges/editor-ref.ts
+const toAgentCommentReply = (reply) => ({
+	id: String(reply.id),
+	author: reply.author,
+	text: replyPlainText(reply)
+});
+/**
+* Parse a tool-supplied comment id into the numeric `Comment.id` this bridge
+* matches against, rejecting anything but a bare non-negative integer.
+* `Number.parseInt` alone would silently accept trailing junk (`"12abc"` ->
+* `12`), which could reply to or resolve the wrong comment on malformed tool
+* input.
+*/
+const parseCommentId = (commentId) => /^\d+$/.test(commentId) ? Number.parseInt(commentId, 10) : null;
+/** A host-state `Comment`'s plain text, its paragraphs joined by newlines (mirrors `FolioDocxReviewer`'s reading). */
+const replyPlainText = (comment) => comment.content.map(paragraphPlainText).join("\n");
+const paragraphPlainText = (paragraph) => {
+	const parts = [];
+	for (const item of paragraph.content ?? []) {
+		if (item.type !== "run") continue;
+		for (const runItem of item.content ?? []) if (runItem.type === "text") parts.push(runItem.text);
+	}
+	return parts.join("");
+};
+/**
+* Build a {@link FolioAgentBridge} over a live `DocxEditor` ref plus the host
+* app's comment state.
+*
+* Comments live in app-controlled React state (the `DocxEditor` `comments`
+* prop), not on the ref, so this factory takes `getComments`/`setComments` to
+* read and write that state directly — the same pair the host already passes
+* to `DocxEditor`.
+*
+* KNOWN LIMITATIONS (only apply to a `ref` that predates the read-surface
+* additions below; the current `DocxEditorRef` implements all four):
+* - `getChanges()` returns `[]` when `ref.getTrackedChanges` is absent, since
+*   there is then no ref-level way to enumerate tracked changes from
+*   ProseMirror mark attributes.
+* - Comment entries fall back to `blockId: null` / `quote: ""` when
+*   `ref.getCommentAnchors` is absent, since there is then no ref-level way
+*   to resolve a comment's anchor against the live ProseMirror document.
+* - `read_page` / `read_selection` report an unsupported-capability error
+*   when `ref.getPageText` / `ref.getSelectionText` are absent: this bridge
+*   omits the corresponding `getPageText` / `getSelectionText` member
+*   entirely rather than implementing it as a no-op, which is what tells
+*   `executeFolioToolCall` to report the tool as unsupported instead of
+*   throwing.
+*/
+const createEditorRefBridge = (options) => {
+	const { ref, author, getComments, setComments } = options;
+	const mode = options.mode ?? "tracked-changes";
+	const requireSnapshot = () => {
+		const snapshot = ref.createAIEditSnapshot();
+		if (!snapshot) throw new Error("The editor view is not mounted; no snapshot is available yet.");
+		return snapshot;
+	};
+	const bridge = {
+		snapshot: requireSnapshot,
+		applyOperations: (operations) => ref.applyAIEditOperations({
+			snapshot: requireSnapshot(),
+			operations,
+			mode,
+			author
+		}),
+		getComments: () => {
+			const comments = getComments();
+			const anchors = ref.getCommentAnchors?.();
+			const anchorByCommentId = /* @__PURE__ */ new Map();
+			if (anchors) for (const anchor of anchors) anchorByCommentId.set(anchor.commentId, anchor);
+			const repliesByParent = /* @__PURE__ */ new Map();
+			const topLevel = [];
+			for (const comment of comments) {
+				if (comment.parentId == null) {
+					topLevel.push(comment);
+					continue;
+				}
+				const siblings = repliesByParent.get(comment.parentId) ?? [];
+				siblings.push(comment);
+				repliesByParent.set(comment.parentId, siblings);
+			}
+			return topLevel.map((comment) => {
+				const anchor = anchorByCommentId.get(comment.id);
+				return {
+					id: String(comment.id),
+					author: comment.author,
+					text: replyPlainText(comment),
+					resolved: comment.done ?? false,
+					blockId: anchor?.blockId ?? null,
+					quote: anchor?.quote ?? "",
+					replies: (repliesByParent.get(comment.id) ?? []).map(toAgentCommentReply)
+				};
+			});
+		},
+		getChanges: () => {
+			const changes = ref.getTrackedChanges?.();
+			return changes ? changes.map(toAgentChange) : [];
+		},
+		replyToComment: (commentId, text) => {
+			const parentId = parseCommentId(commentId);
+			if (parentId === null) return false;
+			const comments = getComments();
+			const reply = createReply(comments, parentId, {
+				author,
+				text
+			});
+			if (!reply) return false;
+			setComments([...comments, reply]);
+			return true;
+		},
+		resolveComment: (commentId, resolved) => {
+			const targetId = parseCommentId(commentId);
+			if (targetId === null) return false;
+			const comments = getComments();
+			let found = false;
+			const next = comments.map((comment) => {
+				if (comment.id !== targetId) return comment;
+				found = true;
+				return {
+					...comment,
+					done: resolved
+				};
+			});
+			if (!found) return false;
+			setComments(next);
+			return true;
+		},
+		scrollToBlock: (blockId) => ref.scrollToBlock(blockId),
+		getPageCount: () => ref.getTotalPages()
+	};
+	const getSelectionText = ref.getSelectionText;
+	if (getSelectionText) bridge.getSelectionText = () => getSelectionText();
+	const getPageText = ref.getPageText;
+	if (getPageText) bridge.getPageText = (page) => getPageText(page) ?? "";
+	return bridge;
+};
+//#endregion
+export { createEditorRefBridge };

package/dist/bridges/reviewer.d.ts

@@ -0,0 +1,19 @@
+import { FolioAgentBridge } from "../bridge.js";
+import { FolioAIEditApplyMode, FolioDocxReviewer } from "@stll/folio-core/server";
+
+//#region src/bridges/reviewer.d.ts
+/** Options for {@link createReviewerBridge}. */
+type CreateReviewerBridgeOptions = {
+  /** `"tracked-changes"` (default) produces ins/del redlines; `"direct"` edits in place. */mode?: FolioAIEditApplyMode;
+};
+/**
+ * Build a {@link FolioAgentBridge} over a headless {@link FolioDocxReviewer}
+ * (`@stll/folio-core/server`). No optional capability members are
+ * implemented: a headless document has no live page/selection/scroll
+ * surface, so `read_page`, `read_selection`, and `scroll_to_block` report an
+ * unsupported-capability error via {@link executeFolioToolCall} on this
+ * bridge.
+ */
+declare const createReviewerBridge: (reviewer: FolioDocxReviewer, options?: CreateReviewerBridgeOptions) => FolioAgentBridge;
+//#endregion
+export { CreateReviewerBridgeOptions, createReviewerBridge };

package/dist/bridges/reviewer.js

@@ -0,0 +1,48 @@
+import { toAgentChange } from "./shared.js";
+//#region src/bridges/reviewer.ts
+const toAgentCommentReply = (reply) => ({
+	id: String(reply.id),
+	author: reply.author,
+	text: reply.text
+});
+const toAgentComment = (comment) => ({
+	id: String(comment.id),
+	author: comment.author,
+	text: comment.text,
+	resolved: comment.done,
+	blockId: comment.blockId,
+	quote: comment.anchoredText,
+	replies: comment.replies.map(toAgentCommentReply)
+});
+/**
+* Parse a tool-supplied comment id into the numeric id `FolioDocxReviewer`
+* expects, rejecting anything but a bare non-negative integer. `Number.
+* parseInt` alone would silently accept trailing junk (`"12abc"` -> `12`),
+* which could reply to the wrong comment thread on malformed tool input.
+*/
+const parseCommentId = (commentId) => /^\d+$/.test(commentId) ? Number.parseInt(commentId, 10) : null;
+/**
+* Build a {@link FolioAgentBridge} over a headless {@link FolioDocxReviewer}
+* (`@stll/folio-core/server`). No optional capability members are
+* implemented: a headless document has no live page/selection/scroll
+* surface, so `read_page`, `read_selection`, and `scroll_to_block` report an
+* unsupported-capability error via {@link executeFolioToolCall} on this
+* bridge.
+*/
+const createReviewerBridge = (reviewer, options = {}) => {
+	const mode = options.mode ?? "tracked-changes";
+	return {
+		snapshot: () => reviewer.snapshot(),
+		applyOperations: (operations) => reviewer.applyOperations(operations, { mode }),
+		getComments: () => reviewer.getComments().map(toAgentComment),
+		getChanges: () => reviewer.getChanges().map(toAgentChange),
+		replyToComment: (commentId, text) => {
+			const parentId = parseCommentId(commentId);
+			if (parentId === null) return false;
+			return reviewer.replyTo(parentId, { text }) !== null;
+		},
+		resolveComment: (commentId, resolved) => reviewer.resolveComment(commentId, { resolved })
+	};
+};
+//#endregion
+export { createReviewerBridge };

package/dist/bridges/shared.d.ts

@@ -0,0 +1,16 @@
+import { FolioAgentChange } from "../types.js";
+import { FolioReviewChange } from "@stll/folio-core/server";
+
+//#region src/bridges/shared.d.ts
+/**
+ * Map a core {@link FolioReviewChange} — from `FolioDocxReviewer.getChanges`
+ * (headless bridge, `bridges/reviewer.ts`) or `DocxEditorRef.getTrackedChanges`
+ * (live-editor bridge, `bridges/editor-ref.ts`) — to the tool-facing
+ * {@link FolioAgentChange} shape. Both bridges read the same underlying
+ * tracked-change record (`getTrackedChangesFromDoc` in
+ * `@stll/folio-core/ai-edits`), so they share this one mapping instead of
+ * drifting into two subtly different shapes.
+ */
+declare const toAgentChange: (change: FolioReviewChange) => FolioAgentChange;
+//#endregion
+export { toAgentChange };

package/dist/bridges/shared.js

@@ -0,0 +1,19 @@
+//#region src/bridges/shared.ts
+/**
+* Map a core {@link FolioReviewChange} — from `FolioDocxReviewer.getChanges`
+* (headless bridge, `bridges/reviewer.ts`) or `DocxEditorRef.getTrackedChanges`
+* (live-editor bridge, `bridges/editor-ref.ts`) — to the tool-facing
+* {@link FolioAgentChange} shape. Both bridges read the same underlying
+* tracked-change record (`getTrackedChangesFromDoc` in
+* `@stll/folio-core/ai-edits`), so they share this one mapping instead of
+* drifting into two subtly different shapes.
+*/
+const toAgentChange = (change) => ({
+	id: String(change.id),
+	type: change.type,
+	author: change.author,
+	text: change.text,
+	blockId: change.blockId
+});
+//#endregion
+export { toAgentChange };

package/dist/compare.d.ts

@@ -0,0 +1,53 @@
+import { WordDiffSegment } from "@stll/folio-core/ai-edits";
+
+//#region src/compare.d.ts
+/** One word-level diff segment within a `modified` block. Mirrors {@link WordDiffSegment}. */
+type FolioAgentVersionDiffSegment = WordDiffSegment;
+/** One block-level change between two document versions, in revised-side document order. */
+type FolioAgentBlockDiff = {
+  type: "added";
+  blockId: string;
+  kind: string;
+  text: string;
+} | {
+  type: "deleted";
+  blockId: string;
+  kind: string;
+  text: string;
+} | {
+  type: "modified";
+  blockId: string;
+  kind: string;
+  segments: FolioAgentVersionDiffSegment[];
+};
+/** Result of {@link compareDocxVersions}. */
+type FolioAgentVersionDiff = {
+  /** Every added, deleted, or modified block, in revised-side document order (deletions slotted where they sat). */changes: FolioAgentBlockDiff[]; /** Counts across every paired/unpaired block, including the unchanged blocks `changes` omits. */
+  summaryCounts: {
+    added: number;
+    deleted: number;
+    modified: number;
+    unchanged: number;
+  };
+};
+/** True when an `unpairedBaseCount * unpairedRevisedCount` LCS table would exceed {@link MAX_LCS_CELLS}. */
+declare const exceedsLcsBudget: (unpairedBaseCount: number, unpairedRevisedCount: number) => boolean;
+/**
+ * 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.
+ */
+declare const compareDocxVersions: (base: ArrayBuffer, revised: ArrayBuffer) => Promise<FolioAgentVersionDiff>;
+/**
+ * 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`.
+ */
+declare const formatVersionDiffForLLM: (diff: FolioAgentVersionDiff) => string;
+//#endregion
+export { FolioAgentBlockDiff, FolioAgentVersionDiff, FolioAgentVersionDiffSegment, compareDocxVersions, exceedsLcsBudget, formatVersionDiffForLLM };