@stll/folio-agents/dist/parse.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 { FolioAgentInputNormalization } from "./types.js";
import { FolioSuggestChangesOptions } from "./suggest-changes-options.js";
import { FolioAIEditOperation, FolioDocumentOperationBatch, FolioDocumentOperationBatchPrecondition, FolioDocumentOperationMode } 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.
 * The per-call operation count is a host option
 * (`FolioSuggestChangesOptions.maxOperations`), defaulting to
 * {@link DEFAULT_MAX_OPERATIONS_PER_CALL}.
 */
declare const MAX_OPERATION_TEXT_LENGTH = 100000;
/**
 * Aggregate cap on the SUM of every text-bearing field's length across one
 * `suggest_changes` call. Each field alone is bounded by
 * {@link MAX_OPERATION_TEXT_LENGTH} and each call by the operation cap, but
 * an operation can carry several capped fields (e.g. `comment` plus `text`),
 * and a table-insertion operation can carry up to
 * {@link MAX_TABLE_INSERTION_CELL_TEXTS} capped cell texts — so a
 * maximally-shaped batch could still push an unbounded total into the
 * tracked-changes engine in one call even though every per-field cap was
 * respected. This budget bounds the running total instead.
 */
declare const MAX_TOTAL_OPERATION_TEXT_LENGTH = 2000000;
/** Plain-language error for a string argument over {@link MAX_OPERATION_TEXT_LENGTH}. */
declare const explainTextTooLong: (label: string, length: number) => string;
type PrepareFolioAgentDocumentOperationBatchOptions = {
  operations: readonly FolioAIEditOperation[];
  mode?: FolioDocumentOperationMode;
  atomic?: boolean;
  dryRun?: boolean;
  precondition?: FolioDocumentOperationBatchPrecondition;
};
/**
 * Wrap agent-preprocessed operations in the versioned batch envelope and
 * delegate the canonical contract validation to core's parser. The returned
 * batch is safe to hand straight to `applyDocumentOperations`; core marks
 * parsed batches internally so the downstream apply path can skip reparsing.
 */
declare const prepareFolioAgentDocumentOperationBatch: ({ operations, mode, atomic, dryRun, precondition }: PrepareFolioAgentDocumentOperationBatchOptions) => FolioDocumentOperationBatch;
/** 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[];
  /** Present when the call pinned a host document version. */
  precondition?: FolioDocumentOperationBatchPrecondition;
  normalizations: FolioAgentInputNormalization[];
} | {
  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. `options` must match the {@link FolioSuggestChangesOptions} the
 * tool definition was built with.
 */
declare const parseSuggestChangesInput: (args: unknown, options?: FolioSuggestChangesOptions) => ParseSuggestChangesResult;
//#endregion
export { MAX_OPERATION_TEXT_LENGTH, MAX_TOTAL_OPERATION_TEXT_LENGTH, ParseAddCommentResult, ParseSuggestChangesResult, PrepareFolioAgentDocumentOperationBatchOptions, explainTextTooLong, parseAddCommentInput, parseSuggestChangesInput, prepareFolioAgentDocumentOperationBatch };