@stll/folio-agents/dist/tools.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 { FolioAgentApplyOperationsSummary, FolioAgentBlock, FolioAgentChange, FolioAgentComment, FolioAgentCommentFilter, FolioAgentDocumentOutline, FolioAgentScopedFindTextResult, FolioAgentSectionRead, FolioAgentToolDefinition, FolioAgentTypedToolDefinition } from "./types.js";
import { FolioAgentToolOptions, FolioSuggestChangesOptions } from "./suggest-changes-options.js";
import { FolioAgentFindTextScope, FolioAgentShowInDocumentArgs } from "./tool-contract.js";
//#region src/tools.d.ts
/**
 * `suggest_changes` is a host-configurable projection of the document-operation
 * contract (see `FOLIO_DOCUMENT_OPERATION_JSON_SCHEMA` in `operation-schema.ts`):
 * the allowed operation types, the review-metadata policy, the per-call cap,
 * and an optional document-version pin all come from
 * {@link FolioSuggestChangesOptions}. The schema is derived from the resolved
 * options and from core's per-type key map, so the properties it advertises
 * are exactly the ones the contract parser accepts for the allowed types.
 * Two model-facing conveniences differ from the contract on the wire:
 * `id` is optional (the parser mints unique ids) and `comment` may be a plain
 * string (the parser wraps it into `{ text }`). `suggestionId` is host-side
 * grouping state and is never exposed to the model.
 */
declare const SUGGEST_CHANGES_OPERATION_TYPES: readonly ("replaceInBlock" | "replaceRange" | "commentOnRange" | "formatRange" | "insertAfterBlock" | "insertBeforeBlock" | "replaceBlock" | "deleteBlock" | "commentOnBlock" | "insertSignatureTable" | "insertTableRow" | "deleteTableRow" | "insertTableColumn" | "deleteTableColumn" | "mergeTableCells" | "splitTableCell")[];
/**
 * Plain-language capability statement for a configured `suggest_changes`
 * surface: the allowed operations, the structural knobs they unlock, the
 * limits, and the review-metadata and document-version requirements. Used
 * inside the tool description and exported so a host can paste the same
 * text into its system prompt instead of hand-maintaining a copy that drifts.
 */
declare const describeSuggestChangesCapabilities: (options?: FolioSuggestChangesOptions) => string;
/**
 * The tools this package exposes, described for an LLM. Every tool that reads
 * or mutates the document expects `blockId` values that came from
 * `read_document` or `find_text` in THIS conversation — block ids are not
 * guessable and change whenever the document's structure changes. Every
 * mutation (`add_comment`, `suggest_changes`) becomes a tracked change or
 * comment pending human review; nothing is silently finalized.
 */
declare const FOLIO_AGENT_TOOL_REGISTRY: {
  readonly read_document: FolioAgentTypedToolDefinition<"read_document", Readonly<Record<string, never>>, FolioAgentBlock[]>;
  readonly get_document_outline: FolioAgentTypedToolDefinition<"get_document_outline", {
    maxDepth?: number;
  }, FolioAgentDocumentOutline>;
  readonly read_section: FolioAgentTypedToolDefinition<"read_section", {
    handle: import("@stll/folio-core/server").FolioDocumentSectionHandle;
    maxBlocks?: number;
    afterBlockId?: string;
  }, FolioAgentSectionRead>;
  readonly list_stories: FolioAgentTypedToolDefinition<"list_stories", Readonly<Record<string, never>>, import("@stll/folio-core/server").FolioDocumentStory[]>;
  readonly read_story: FolioAgentTypedToolDefinition<"read_story", {
    handle: import("@stll/folio-core/server").FolioDocumentStoryHandle;
  }, import("@stll/folio-core/server").FolioDocumentStory>;
  readonly find_text: FolioAgentTypedToolDefinition<"find_text", {
    query: string;
    matchCase?: boolean;
    wholeWord?: boolean;
    scope?: FolioAgentFindTextScope;
  }, FolioAgentScopedFindTextResult>;
  readonly read_comments: FolioAgentTypedToolDefinition<"read_comments", {
    filter?: FolioAgentCommentFilter;
  }, FolioAgentComment[]>;
  readonly read_changes: FolioAgentTypedToolDefinition<"read_changes", Readonly<Record<string, never>>, FolioAgentChange[]>;
  readonly add_comment: FolioAgentTypedToolDefinition<"add_comment", {
    blockId: string;
    quote?: string;
    text: string;
    precondition?: {
      blockTextHash: string;
    };
  }, FolioAgentApplyOperationsSummary>;
  readonly suggest_changes: FolioAgentTypedToolDefinition<"suggest_changes", {
    operations: unknown[];
    documentVersion?: string;
  }, FolioAgentApplyOperationsSummary>;
  readonly reply_comment: FolioAgentTypedToolDefinition<"reply_comment", {
    commentId: string;
    text: string;
  }, {
    replied: true;
  }>;
  readonly resolve_comment: FolioAgentTypedToolDefinition<"resolve_comment", {
    commentId: string;
    reopen?: boolean;
  }, {
    resolved: boolean;
  }>;
  readonly read_page: FolioAgentTypedToolDefinition<"read_page", {
    page: number;
  }, {
    page: number;
    totalPages?: number;
    text: string;
  }>;
  readonly read_selection: FolioAgentTypedToolDefinition<"read_selection", Readonly<Record<string, never>>, {
    text: string;
  }>;
  readonly show_in_document: FolioAgentTypedToolDefinition<"show_in_document", FolioAgentShowInDocumentArgs, {
    shown: boolean;
  }>;
  readonly scroll_to_block: FolioAgentTypedToolDefinition<"scroll_to_block", {
    blockId: string;
  }, {
    scrolled: boolean;
  }>;
};
declare const FOLIO_AGENT_TOOLS: FolioAgentToolDefinition[];
/**
 * The tool definitions this package exposes. Without options this is
 * {@link FOLIO_AGENT_TOOLS}; with `suggestChanges` options the
 * `suggest_changes` definition is rebuilt for that surface. Pass the same
 * options to `executeFolioToolCall` so the parser enforces what the schema
 * advertises.
 */
declare const getFolioToolDefinitions: (options?: FolioAgentToolOptions) => FolioAgentToolDefinition[];
//#endregion
export { FOLIO_AGENT_TOOLS, FOLIO_AGENT_TOOL_REGISTRY, SUGGEST_CHANGES_OPERATION_TYPES, describeSuggestChangesCapabilities, getFolioToolDefinitions };