import { z } from 'zod'; type ToolAnnotations = { readOnlyHint: boolean; destructiveHint: boolean; }; /** * Contract-surface classification for a tool's writes (#118 / #122). * * - `revisionable` — AI-attributed writes land as native OOXML tracked-change * markup (Table A of SUPPORT.md). Enforced by the write-time emitter (#120) * and validator (#121); exercised by the revisionable-surface property test. * - `package-mutation` — writes mutate package-level parts with no native * revision wrapper (Table B). Recorded in the session non-revision change * manifest and surfaced in the save report rather than tracked. * - `internal` — outside the AI-authoring contract: read-only utilities, * tracked-change consumers (accept_changes), and derived-output tools * (export, convert_to_odt). Matches SUPPORT.md's "Internal / non-contract". * * A tool may be primarily `revisionable` yet also touch package parts; those * set `emitsNonRevisionChanges` and record manifest entries for the untracked * portion (e.g. add_comment tracks the body reference but writes comment text * to comments.xml). * * @see packages/docx-core/SUPPORT.md for the ratified per-tool inventory (#119). */ type ToolSurface = 'revisionable' | 'package-mutation' | 'internal'; export declare const SAFE_DOCX_TOOL_CATALOG: readonly [{ readonly name: "read_file"; readonly surface: "internal"; readonly description: "Read document content (DOCX, ODT, or Google Doc). Output is token-limited (~14k tokens) by default with pagination metadata (has_more, next_offset). Use offset/limit to paginate."; readonly input: z.ZodObject<{ offset: z.ZodOptional; limit: z.ZodOptional; node_ids: z.ZodOptional>; format: z.ZodOptional>; comment_rendering: z.ZodOptional>; show_formatting: z.ZodOptional; include_fingerprint: z.ZodOptional; include_fingerprint_ordinal: z.ZodOptional; include_footnotes: z.ZodOptional; google_doc_id: z.ZodOptional; file_path: z.ZodOptional; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: true; readonly destructiveHint: false; }; }, { readonly name: "get_document_outline"; readonly surface: "internal"; readonly description: "Get a compact structural map of a document's headings (DOCX only). Each entry is `{paragraph_id, text, level, source}`. Deterministic sources are `word_style`, `list_metadata`, and `outline_level`, selected in that precedence order and included by default. Heuristic sources are `run_in_header`, `title_with_period`, `title_with_colon`, `title_caps_centered`, and `title_bare`; set include_heuristic_headings=true to include them. JSON preserves levels 1-9; Markdown clamps visual ATX depth to 6. Read-only."; readonly input: z.ZodObject<{ format: z.ZodOptional>; include_heuristic_headings: z.ZodOptional; file_path: z.ZodOptional; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: true; readonly destructiveHint: false; }; }, { readonly name: "grep"; readonly surface: "internal"; readonly description: "Search paragraphs with regex. Use file_path for session-based search, file_paths for stateless multi-file search, or google_doc_id for Google Docs. ODT supported via file_path (single-file) only."; readonly input: z.ZodObject<{ file_paths: z.ZodOptional>; patterns: z.ZodOptional>; pattern: z.ZodOptional; case_sensitive: z.ZodOptional; whole_word: z.ZodOptional; max_results: z.ZodOptional; context_chars: z.ZodOptional; dedupe_by_paragraph: z.ZodOptional; search_xml: z.ZodOptional; include_context: z.ZodOptional; google_doc_id: z.ZodOptional; file_path: z.ZodOptional; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: true; readonly destructiveHint: false; }; }, { readonly name: "batch_edit"; readonly surface: "revisionable"; readonly description: "Single-agent front door for applying multiple edit steps (replace_text, insert_paragraph) to a document in one call. Validates all steps first, rejects conflicts before applying anything, then executes valid steps sequentially. Accepts inline steps or a plan_file_path JSON array. Surface: revisionable — every applied step emits native OOXML tracked changes."; readonly input: z.ZodObject<{ steps: z.ZodOptional>>>; plan_file_path: z.ZodOptional; file_path: z.ZodString; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "replace_text"; readonly surface: "revisionable"; readonly description: "Replace text in a paragraph by provider paragraph id, preserving formatting where supported. Supports DOCX, ODT, and Google Docs. Surface: revisionable — DOCX edits emit native OOXML tracked changes (w:ins/w:del/w:rPrChange)."; readonly input: z.ZodObject<{ target_paragraph_id: z.ZodString; old_string: z.ZodString; new_string: z.ZodString; instruction: z.ZodString; normalize_first: z.ZodOptional; google_doc_id: z.ZodOptional; file_path: z.ZodOptional; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "insert_paragraph"; readonly surface: "revisionable"; readonly description: "Insert a paragraph before/after an anchor paragraph by paragraph id. Supports DOCX, ODT, and Google Docs. (ODT paragraph ids are positional and shift after insertion — re-read before further edits.) Surface: revisionable — DOCX insertions emit native OOXML tracked changes."; readonly input: z.ZodObject<{ positional_anchor_node_id: z.ZodString; new_string: z.ZodString; instruction: z.ZodString; position: z.ZodOptional>; style_source_id: z.ZodOptional; google_doc_id: z.ZodOptional; file_path: z.ZodOptional; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "save"; readonly surface: "revisionable"; readonly description: "Persist the current in-memory document session. For DOCX: saves clean and/or tracked changes output. For ODT: saves an .odt package. For Google Docs: checkpoint (default) returns revisionId, or snapshot exports as DOCX. Surface: revisionable — the save report lists both the AI revisions applied and a non-revision change manifest of any package-level mutations (comment/footnote side parts, relationships) that have no tracked-change wrapper."; readonly input: z.ZodObject<{ save_to_local_path: z.ZodString; clean_bookmarks: z.ZodOptional; save_format: z.ZodOptional>; allow_overwrite: z.ZodOptional; allow_discard_preserved_revisions: z.ZodOptional; tracked_save_to_local_path: z.ZodOptional; tracked_changes_author: z.ZodOptional; tracked_changes_engine: z.ZodOptional>; fail_on_rebuild_fallback: z.ZodOptional; google_doc_id: z.ZodOptional; file_path: z.ZodOptional; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "export"; readonly surface: "internal"; readonly description: "Export a document to a portable rendering (Markdown, semantic HTML, or plain text). Writes an output file (default: source path with the format extension, e.g. .md, .html, or .txt) and returns its path, byte count, and the rendered content (under `content`). Intentionally lossy (no round-trip); HTML is the semantic tier, not pixel-faithful. DOCX only — Google Docs is not supported."; readonly input: z.ZodObject<{ format: z.ZodOptional>; output_path: z.ZodOptional; allow_overwrite: z.ZodOptional; include_markdown: z.ZodOptional; file_path: z.ZodOptional; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: false; }; }, { readonly name: "convert_to_odt"; readonly surface: "internal"; readonly description: "Convert a DOCX document to OpenDocument Text (.odt) using the native model-to-model converter (no LibreOffice involved). Writes the .odt (default: source path with the .odt extension), validates ODF packaging safety before writing, and returns the output path plus a `lossiness` summary itemizing every downgraded construct. Conversion is semantic and intentionally lossy: text, headings, bold/italic/underline, hyperlinks, lists, and tables are mapped; richer styling, tracked changes, comments, and headers/footers are not. DOCX in, ODT out — Google Docs and .odt inputs are not supported."; readonly input: z.ZodObject<{ output_path: z.ZodOptional; allow_overwrite: z.ZodOptional; file_path: z.ZodOptional; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: false; }; }, { readonly name: "format_layout"; readonly surface: "revisionable"; readonly description: "Apply layout controls (paragraph spacing, table row height, cell padding). Google Docs supports paragraph spacing only. Surface: revisionable — DOCX geometry edits emit native property-change revisions (w:pPrChange/w:trPrChange/w:tcPrChange)."; readonly input: z.ZodObject<{ strict: z.ZodOptional; paragraph_spacing: z.ZodOptional>; before_twips: z.ZodOptional; after_twips: z.ZodOptional; line_twips: z.ZodOptional; line_rule: z.ZodOptional>; }, z.core.$strip>>; row_height: z.ZodOptional>; row_indexes: z.ZodOptional>; value_twips: z.ZodOptional; rule: z.ZodOptional>; }, z.core.$strip>>; cell_padding: z.ZodOptional>; row_indexes: z.ZodOptional>; cell_indexes: z.ZodOptional>; top_dxa: z.ZodOptional; bottom_dxa: z.ZodOptional; left_dxa: z.ZodOptional; right_dxa: z.ZodOptional; }, z.core.$strip>>; google_doc_id: z.ZodOptional; file_path: z.ZodOptional; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "accept_changes"; readonly surface: "internal"; readonly description: "Accept all tracked changes in the document body, producing a clean document with no revision markup. Returns acceptance stats."; readonly input: z.ZodObject<{ file_path: z.ZodString; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "accept_ai_edits"; readonly surface: "internal"; readonly description: "Selectively accept tracked changes by revision id or author in the in-memory session, leaving all other (e.g. third-party reviewer) revisions byte-untouched. This does not write file_path; call save to persist the mutation. Provide revision_ids (array of w:id values) to target specific revisions, or author to accept every revision by one actor. Sweeps document.xml and supported side-story parts (footnotes, endnotes, comments). An ambiguous overlap — a targeted revision structurally containing, or contained by, a non-targeted revision (nested ins/del/move) — hard-errors with code AMBIGUOUS_REVISION_OVERLAP and a structured `overlaps` list unless normalize_first is set (best-effort, no byte-identical promise)."; readonly input: z.ZodObject<{ revision_ids: z.ZodOptional>>; author: z.ZodOptional; normalize_first: z.ZodOptional; file_path: z.ZodString; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "reject_ai_edits"; readonly surface: "internal"; readonly description: "Selectively reject tracked changes by revision id or author in the in-memory session (restoring their pre-edit state), leaving all other revisions byte-untouched. This does not write file_path; call save to persist the mutation. Symmetric to accept_ai_edits: provide revision_ids or author, sweeps document.xml and supported side-story parts, and hard-errors on an ambiguous overlap (code AMBIGUOUS_REVISION_OVERLAP with a structured `overlaps` list) unless normalize_first is set."; readonly input: z.ZodObject<{ revision_ids: z.ZodOptional>>; author: z.ZodOptional; normalize_first: z.ZodOptional; file_path: z.ZodString; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "has_tracked_changes"; readonly surface: "internal"; readonly description: "Check whether the document body contains tracked-change markers (insertions, deletions, moves, and property-change records). Read-only."; readonly input: z.ZodObject<{ file_path: z.ZodString; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: true; readonly destructiveHint: false; }; }, { readonly name: "get_file_status"; readonly surface: "internal"; readonly description: "Get file/session metadata including edit count, normalization stats, and cache info. Supports DOCX, ODT, and Google Docs."; readonly input: z.ZodObject<{ google_doc_id: z.ZodOptional; file_path: z.ZodOptional; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: true; readonly destructiveHint: false; }; }, { readonly name: "close_file"; readonly surface: "internal"; readonly description: "Close an open file session, or close all sessions with explicit confirmation. Supports DOCX, ODT, and Google Docs."; readonly input: z.ZodObject<{ clear_all: z.ZodOptional; confirm: z.ZodOptional; google_doc_id: z.ZodOptional; file_path: z.ZodOptional; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "add_comment"; readonly surface: "revisionable"; readonly emitsNonRevisionChanges: true; readonly description: "Add a comment or threaded reply to a document. Provide target_paragraph_id + anchor_text for root comments, or parent_comment_id for replies. Supports DOCX and ODT (ODT backs comments with office:annotation; threaded replies are DOCX-only). Surface: revisionable + package-mutation — the body-story comment reference is tracked (w:ins), while comment text and author metadata are recorded in the save report non-revision change manifest."; readonly input: z.ZodObject<{ target_paragraph_id: z.ZodOptional; anchor_text: z.ZodOptional; parent_comment_id: z.ZodOptional; author: z.ZodString; text: z.ZodString; initials: z.ZodOptional; file_path: z.ZodString; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "get_comments"; readonly surface: "internal"; readonly description: "Get all comments from the document with IDs, authors, dates, text, and anchored paragraph IDs. Range-anchored DOCX comments also expose optional end_paragraph_id, start_run_index, start_char_offset, end_run_index, and end_char_offset fields describing the covered span. Includes threaded replies (DOCX). Supports DOCX and ODT. Read-only."; readonly input: z.ZodObject<{ file_path: z.ZodString; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: true; readonly destructiveHint: false; }; }, { readonly name: "delete_comment"; readonly surface: "revisionable"; readonly emitsNonRevisionChanges: true; readonly description: "Delete a comment and all its threaded replies from the document. Cascade-deletes all descendants. Surface: revisionable + package-mutation — the body-story comment reference removal is tracked (w:del), while comment/reply text cleanup is recorded in the save report non-revision change manifest."; readonly input: z.ZodObject<{ comment_id: z.ZodNumber; file_path: z.ZodString; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "compare_documents"; readonly surface: "revisionable"; readonly description: "Compare two documents and produce a tracked-changes output document. Provide original_file_path + revised_file_path for standalone comparison, or file_path to compare session edits against the original. DOCX and ODF (.odt) support both modes. DOCX stats count insertions/deletions as contiguous ranges, expose atom totals as insertedAtoms/deletedAtoms, and report formatChanges separately from modifiedParagraphs. ODF compares at inline granularity (a modified paragraph is marked up in place — only the changed spans are struck or inserted)."; readonly input: z.ZodObject<{ save_to_local_path: z.ZodString; author: z.ZodOptional; engine: z.ZodOptional>; ignore_formatting: z.ZodOptional; compare_moves: z.ZodOptional; file_path: z.ZodOptional; original_file_path: z.ZodOptional; revised_file_path: z.ZodOptional; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: true; readonly destructiveHint: false; }; }, { readonly name: "get_footnotes"; readonly surface: "internal"; readonly description: "Get all footnotes from the document with IDs, display numbers, text, and anchored paragraph IDs. Read-only."; readonly input: z.ZodObject<{ file_path: z.ZodString; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: true; readonly destructiveHint: false; }; }, { readonly name: "add_footnote"; readonly surface: "revisionable"; readonly emitsNonRevisionChanges: true; readonly description: "Add a footnote anchored to a paragraph. Optionally position the reference after specific text using after_text. Note: [^N] markers in read_file output are display-only and not part of the editable text used by replace_text. Surface: revisionable + package-mutation — the footnote reference and note text are tracked (w:ins), while footnote-part creation and registration are recorded in the save report non-revision change manifest."; readonly input: z.ZodObject<{ target_paragraph_id: z.ZodString; after_text: z.ZodOptional; text: z.ZodString; file_path: z.ZodString; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "update_footnote"; readonly surface: "revisionable"; readonly description: "Update the text content of an existing footnote. Surface: revisionable — note-text changes emit native OOXML tracked changes (w:ins/w:del) inside the footnote body."; readonly input: z.ZodObject<{ note_id: z.ZodNumber; new_text: z.ZodString; file_path: z.ZodString; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "delete_footnote"; readonly surface: "revisionable"; readonly description: "Delete a footnote and its reference from the document. Surface: revisionable — the reference and note text are removed as native OOXML tracked deletions (w:del)."; readonly input: z.ZodObject<{ note_id: z.ZodNumber; file_path: z.ZodString; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "clear_formatting"; readonly surface: "revisionable"; readonly description: "Clear specific run-level formatting (bold, italic, underline, highlight, color, font) from paragraphs. Surface: revisionable — clearing emits a native run-property-change revision (w:rPrChange)."; readonly input: z.ZodObject<{ paragraph_ids: z.ZodOptional>; clear_highlight: z.ZodOptional; clear_bold: z.ZodOptional; clear_italic: z.ZodOptional; clear_underline: z.ZodOptional; clear_color: z.ZodOptional; clear_font: z.ZodOptional; file_path: z.ZodString; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: false; readonly destructiveHint: true; }; }, { readonly name: "extract_revisions"; readonly surface: "internal"; readonly description: "Extract tracked changes as structured JSON with before/after text per paragraph, revision details, and comments. Supports pagination via offset and limit. Read-only - does not modify the document."; readonly input: z.ZodObject<{ offset: z.ZodOptional; limit: z.ZodOptional; file_path: z.ZodString; }, z.core.$strip>; readonly annotations: { readonly readOnlyHint: true; readonly destructiveHint: false; }; }]; export declare const SAFE_DOCX_MCP_TOOLS: { name: string; description: string; inputSchema: Record; annotations: ToolAnnotations; surface: ToolSurface; emitsNonRevisionChanges: boolean; }[]; /** * Programmatic index of the contract surface each tool writes to (#122), * mirroring the ratified inventory in `packages/docx-core/SUPPORT.md`. * Consumed by the revisionable-surface property test and by the classification * coverage test. */ export declare const TOOL_SURFACE_INDEX: Record; export type SafeDocxToolName = (typeof SAFE_DOCX_TOOL_CATALOG)[number]['name']; export {}; //# sourceMappingURL=tool_catalog.d.ts.map