import { FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FolioAITextRangeHandle, FolioDocumentOperationIssue, FolioDocumentOperationReceipt, FolioDocumentOutlineEntry, FolioDocumentSectionHandle, FolioDocumentStoryHandle, FolioReviewChange } from "@stll/folio-core/server"; //#region src/types.d.ts /** * Provider-neutral tool-layer types. `FolioAgentToolDefinition` describes a * tool the same way every model provider ends up wanting it described (name + * prose description + a JSON-Schema-shaped input schema); `providers.ts` maps * that single shape onto each SDK's own tool-definition envelope. */ declare const folioAgentToolDefinitionBrand: unique symbol; type FolioAgentJsonObjectSchema = { readonly type: "object"; readonly properties: Record; readonly required: readonly string[]; readonly additionalProperties: false; } & Record; /** Every tool name this package exposes, as a stable string union (no enums). */ declare const FOLIO_AGENT_TOOL_NAMES: { readonly readDocument: "read_document"; readonly getDocumentOutline: "get_document_outline"; readonly readSection: "read_section"; readonly listStories: "list_stories"; readonly readStory: "read_story"; readonly findText: "find_text"; readonly readComments: "read_comments"; readonly readChanges: "read_changes"; readonly addComment: "add_comment"; readonly suggestChanges: "suggest_changes"; readonly replyComment: "reply_comment"; readonly resolveComment: "resolve_comment"; readonly readPage: "read_page"; readonly readSelection: "read_selection"; readonly scrollToBlock: "scroll_to_block"; readonly showInDocument: "show_in_document"; }; type FolioAgentToolName = (typeof FOLIO_AGENT_TOOL_NAMES)[keyof typeof FOLIO_AGENT_TOOL_NAMES]; /** * A provider-neutral tool definition: name, an LLM-facing description (when to * call it, what it returns), and a JSON-Schema (draft-07-ish) object schema for * its arguments. `providers.ts` maps a list of these onto Anthropic's or * OpenAI's tool-definition shape. */ type FolioAgentToolDefinition = { name: FolioAgentToolName; description: string; inputSchema: Record; }; type FolioAgentTypedToolDefinition = FolioAgentToolDefinition & { readonly name: TName; readonly inputSchema: TSchema; readonly [folioAgentToolDefinitionBrand]?: { readonly input: TInput; readonly output: TOutput; }; }; /** * Result of executing one tool call. `ok: false` covers every EXPECTED failure * (bad arguments, an unknown tool, a capability the bridge does not support, a * domain-level skip) — never throw for these, since the whole point is to feed * the reason back to the model so it can retry or adjust. `executeFolioToolCall` * is the only boundary layer allowed to catch an unexpected throw and fold it * into this shape too. */ type FolioToolCallResult = { ok: true; result: TResult; } | { ok: false; error: string; }; /** One document block as exposed to a model: id, kind, and its plain text. */ type FolioAgentBlock = { blockId: string; kind: string; text: string; /** * Normalized-text hash of this block at read time. Echo it back as * `precondition.blockTextHash` on a `suggest_changes` / `add_comment` * operation targeting this block so the apply call is guarded against * edits made to the document between this read and that apply — without * it, only same-call staleness within one `suggest_changes` batch is * caught. */ blockTextHash: string; }; /** One main-story `find_text` match. Existing consumers can keep using its block and range directly. */ type FolioAgentTextMatch = { /** Present on results from the current executor; optional for source compatibility with older hosts. */ type?: "main"; story?: { type: "main"; }; blockId: string; /** Normalized-text hash of the whole containing block; see {@link FolioAgentBlock.blockTextHash}. */ blockTextHash: string; /** Stable handle that can be passed directly to `show_in_document` or a range operation. */ range: FolioAITextRangeHandle; /** 0-based index of this occurrence within its block. */ occurrenceInBlock: number; /** Real rendered page when a live paginated surface supplies it. */ page?: number; context: string; }; type FolioAgentStoryTextMatch = { type: "story"; story: Exclude; startOffset: number; endOffset: number; /** 0-based index of this occurrence within the story. */ occurrenceInStory: number; context: string; }; type FolioAgentOutlineEntry = FolioDocumentOutlineEntry & { page?: number; }; type FolioAgentDocumentOutline = { sections: FolioAgentOutlineEntry[]; totalSections: number; truncated: boolean; }; type FolioAgentSectionRead = { handle: FolioDocumentSectionHandle; heading: FolioDocumentOutlineEntry; blocks: FolioAgentBlock[]; totalBlocks: number; truncated: boolean; nextAfterBlockId?: string; }; /** * Result of {@link FOLIO_AGENT_TOOL_NAMES.findText}. `matches` is capped at a * fixed limit; when the query has more hits than that, `truncated` is `true` * and `totalMatches` reports the real count so the model knows to narrow the * query instead of assuming it saw everything. */ type FolioAgentFindTextResult = { matches: FolioAgentTextMatch[]; truncated: boolean; totalMatches: number; }; type FolioAgentStoryFindTextResult = { matches: FolioAgentStoryTextMatch[]; truncated: boolean; totalMatches: number; }; type FolioAgentScopedFindTextResult = FolioAgentFindTextResult | FolioAgentStoryFindTextResult; /** One reply within a comment thread. */ type FolioAgentCommentReply = { id: string; author: string; text: string; }; /** * A comment thread, shaped to match what {@link FolioDocxReviewer.getComments} * (from `@stll/folio-core/server`) returns, minus fields a tool-calling model * has no use for (raw dates). `resolved` mirrors the underlying model's * `done` flag; `quote` mirrors `anchoredText` (the text the comment is * attached to, empty when unavailable). */ type FolioAgentComment = { id: string; author: string; text: string; resolved: boolean; blockId: string | null; quote: string; replies: FolioAgentCommentReply[]; }; /** A pending tracked change, shaped to match {@link FolioDocxReviewer.getChanges}. */ type FolioAgentChange = { id: string; type: FolioReviewChange["type"]; author: string; text: string; blockId: string | null; }; /** Filter for {@link FOLIO_AGENT_TOOL_NAMES.readComments}. */ type FolioAgentCommentFilter = "all" | "open" | "resolved"; /** * One lenient-decoding step the parser took on a tool call's arguments * (a `kind` key read as `type`, an operation supplied as a JSON string, a * stray property dropped). Reported back to the model so sloppy calls * still succeed without the normalisation going unnoticed. */ type FolioAgentInputNormalization = { /** Where in the arguments, e.g. `operations[2].kind`. */ path: string; message: string; }; /** Result of {@link FOLIO_AGENT_TOOL_NAMES.addComment} / `suggest_changes`. */ type FolioAgentApplyOperationsSummary = { version: typeof FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION; applied: { id: string; }[]; /** Operations a host review-queue bridge accepted for later human review instead of applying. */ queued: { id: string; }[]; skipped: { id: string; reason: string; }[]; issues: FolioDocumentOperationIssue[]; receipts: FolioDocumentOperationReceipt[]; normalizations: FolioAgentInputNormalization[]; }; //#endregion export { FOLIO_AGENT_TOOL_NAMES, FolioAgentApplyOperationsSummary, FolioAgentBlock, FolioAgentChange, FolioAgentComment, FolioAgentCommentFilter, FolioAgentCommentReply, FolioAgentDocumentOutline, FolioAgentFindTextResult, FolioAgentInputNormalization, FolioAgentJsonObjectSchema, FolioAgentOutlineEntry, FolioAgentScopedFindTextResult, FolioAgentSectionRead, FolioAgentStoryFindTextResult, FolioAgentStoryTextMatch, FolioAgentTextMatch, FolioAgentToolDefinition, FolioAgentToolName, FolioAgentTypedToolDefinition, FolioToolCallResult };