@stll/folio-agents/dist/bridge.d.ts

Framework-neutral LLM tool layer over folio's ai-edits engine: function-calling tools so an agent can read and mutate .docx documents through @stll/folio-core.

import { FolioAgentCommentId } from "./codecs.js";
import { FolioAgentChange, FolioAgentComment } from "./types.js";
import { FolioAIEditSnapshot, FolioDocumentNavigationTarget, FolioDocumentOperationBatch, FolioDocumentOperationMode, FolioDocumentOperationResult, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, FolioDocumentStory, FolioDocumentStoryHandle } 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;
  /**
   * Default document-operation mode this surface applies when a batch omits
   * `mode`. The executor uses it when it prepares already-parsed batches so
   * the bridge can usually forward them without rebuilding the batch object.
   */
  documentOperationMode?: FolioDocumentOperationMode;
  /**
   * Apply a versioned operation batch against the current document. The
   * bridge decides mode (tracked-changes by default) and author internally.
   */
  applyDocumentOperations(batch: FolioDocumentOperationBatch): FolioDocumentOperationResult;
  /** Undo the latest unchanged batch when the execution surface supports it. */
  undoDocumentOperations?(undoHandle: FolioDocumentOperationUndoHandle): FolioDocumentOperationUndoResult;
  /**
   * The host's opaque version token for the document this bridge holds (an
   * entity version id, a collaboration checkpoint). When a `suggest_changes`
   * batch carries `precondition.documentVersion`, the executor compares it
   * to this value before applying and skips the whole batch with
   * `documentVersionMismatch` on a difference. Omit on a surface without a
   * version notion; such a surface then refuses version-pinned batches.
   */
  getDocumentVersion?(): string;
  /** The comment threads present in the document. */
  getComments(): FolioAgentComment[];
  /** The pending tracked changes (insertions/deletions) present in the document. */
  getChanges(): FolioAgentChange[];
  /** Discover typed document stories when the surface exposes package parts. */
  listStories?(): FolioDocumentStory[];
  /** Read one previously discovered story. */
  readStory?(handle: FolioDocumentStoryHandle): FolioDocumentStory | null;
  /** 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;
  /** Resolve a main-story block or exact text range to its real rendered page. */
  getTargetPage?(target: FolioDocumentNavigationTarget): number | null;
  /** Select and reveal a stable block or text range in the live editor. */
  showInDocument?(target: FolioDocumentNavigationTarget): boolean;
};
type DecodedCommentHandlers = {
  replyToComment(commentId: FolioAgentCommentId, text: string): boolean;
  resolveComment(commentId: FolioAgentCommentId, resolved: boolean): boolean;
};
declare const registerDecodedCommentHandlers: (bridge: FolioAgentBridge, handlers: DecodedCommentHandlers) => FolioAgentBridge;
declare const getDecodedCommentHandlers: (bridge: FolioAgentBridge) => DecodedCommentHandlers | undefined;
//#endregion
export { FolioAgentBridge, getDecodedCommentHandlers, registerDecodedCommentHandlers };