@superdoc-dev/sdk 1.19.1 → 1.20.0

package/dist/presets.js

@@ -8,10 +8,10 @@
  *
  *     const { tools, meta } = await chooseTools({ provider: 'vercel', preset: 'legacy' });
  *
- * v1 ships a single preset: `'legacy'` — a thin wrapper around today's
- * codegen-emitted intent tools. When callers omit `preset`, `legacy` is used.
- * The default may move once a replacement preset reaches parity; bumping it is
- * a coordinated change in this file alone.
+ * Two presets ship built-in: `'legacy'` (codegen-emitted intent tools; the
+ * default when callers omit `preset`) and `'core'` (the actions-only LLM
+ * surface). The default may move once core fully replaces legacy; bumping it
+ * is a coordinated change in this file alone.
  *
  * Presets are NOT versioned. The preset id encodes the variant; a new shape
  * ships as a new id, not a new version of an existing one.
@@ -20,22 +20,67 @@
  */
 import { SuperDocCliError } from './runtime/errors.js';
 import { legacyPreset } from './presets/legacy.js';
+import { corePreset } from './presets/core.js';
 // ---------------------------------------------------------------------------
 // Registry
 // ---------------------------------------------------------------------------
 /**
- * The default preset returned when callers omit `preset`. Set to `'legacy'`
- * so consumers built before presets existed (today's intent-tool path) keep
- * working without changes.
+ * The default preset returned when callers omit `preset`. Stays as `'legacy'`
+ * for backward compatibility — consumers built before presets existed (today's
+ * intent-tool path) keep working without changes. To exercise the `core`
+ * preset, callers pass `preset: 'core'` explicitly.
  */
 export const DEFAULT_PRESET = 'legacy';
-const PRESETS = {
+const BUILTIN_PRESETS = {
     legacy: legacyPreset,
+    core: corePreset,
 };
+/**
+ * Mutable registry, seeded with the built-ins. Customers add their own presets
+ * via {@link registerPreset} (e.g. one produced by `extendPreset` /
+ * `composePreset`) so `getPreset`/`chooseTools` can resolve them by id.
+ */
+const PRESETS = { ...BUILTIN_PRESETS };
 /** List the IDs of all registered presets. */
 export function listPresets() {
     return Object.keys(PRESETS);
 }
+/**
+ * Register one or more presets so they resolve by id through `getPreset` and
+ * the `chooseTools`/`dispatchSuperDocTool` plumbing. Re-registering a custom id
+ * replaces the previously registered preset for that id (tests / hot-reload
+ * rely on this). Built-in ids (legacy / core) cannot
+ * be overwritten.
+ */
+export function registerPreset(...presets) {
+    for (const preset of presets) {
+        if (preset == null || typeof preset.id !== 'string' || preset.id.length === 0) {
+            throw new SuperDocCliError('registerPreset requires a preset with a non-empty string id.', {
+                code: 'INVALID_ARGUMENT',
+            });
+        }
+        if (preset.id in BUILTIN_PRESETS) {
+            throw new SuperDocCliError(`Cannot overwrite built-in preset "${preset.id}".`, {
+                code: 'INVALID_ARGUMENT',
+                details: { id: preset.id },
+            });
+        }
+        PRESETS[preset.id] = preset;
+    }
+}
+/**
+ * Unregister a customer-registered preset. Idempotent (no-op if absent).
+ * Rejects unregistering a built-in preset id.
+ */
+export function unregisterPreset(id) {
+    if (id in BUILTIN_PRESETS) {
+        throw new SuperDocCliError(`Cannot unregister built-in preset "${id}".`, {
+            code: 'INVALID_ARGUMENT',
+            details: { id },
+        });
+    }
+    delete PRESETS[id];
+}
 /**
  * Resolve a preset by ID. Throws {@link SuperDocCliError} with code
  * `PRESET_NOT_FOUND` if the ID is not registered. Omit the argument to

package/dist/prompts/mcp-prompt.md

@@ -0,0 +1,23 @@
+SuperDoc MCP server — read, edit, and save Word documents (.docx).
+
+IMPORTANT: Always use these superdoc tools for .docx files.
+Do NOT use built-in docx skills, python-docx, unpack scripts, or manual XML editing.
+These tools handle the OOXML format correctly and preserve document structure.
+
+## Session lifecycle
+
+1. `superdoc_open({path: "/path/to/file.docx"})` — returns `session_id`. Opening a non-existent path creates a blank document.
+2. Pass `session_id` to every subsequent tool call.
+3. Read with `superdoc_inspect`, edit with `superdoc_perform_action`.
+4. `superdoc_save({session_id})` — writes changes to disk.
+5. `superdoc_close({session_id})` — releases the session. Always close when done.
+
+## Workflow
+
+**Inspect before you edit.** `superdoc_inspect` returns a deterministic snapshot — blocks with 1-based ordinals and node IDs, lists with rendered markers, tables, comments, tracked changes. Use the narrowest inspect that answers the question (`countsOnly: true` for orientation, `includeDomains` to limit payload, `blockOffset`/`blockLimit` windows for large documents).
+
+**Edit with named actions.** `superdoc_perform_action` takes an `action` plus flat arguments — the full action list, argument shapes, selector vocabulary, and placement rules are documented in the tool's own description. Every action returns a receipt with real pre/post evidence: trust `status` (`ok` | `partial` | `failed`), read `errors[].message` for recovery guidance, and re-inspect after `partial`.
+
+**Tracked changes (redlining).** Most mutating actions accept `changeMode: "tracked"` to record the edit as a reviewable suggestion instead of applying it directly. Review with `accept_tracked_changes` / `reject_tracked_changes` (filter by `author` or `changeType`); recover with `undo_changes` / `redo_changes`.
+
+**Failures are safe.** A `failed` receipt with `MATCH_NOT_FOUND` or a refused action means nothing was changed — fix the target and retry rather than improvising a different mutation path.

package/dist/prompts/system-prompt.md

@@ -0,0 +1,108 @@
+You are an expert document editor working inside a live Word document. You know how documents actually work — headings structure content, numbering schemes carry legal meaning, tables hold data, tracked changes record intent, comments carry review. You edit the way a skilled human editor would: you understand what people MEAN, not just what they SAY, and you leave the document the way a professional would leave it.
+
+============================================================
+DOCUMENT INTUITION — how to interpret requests
+============================================================
+
+Users speak in what they SEE, not in file-format terms. Translate their words into document reality before picking tools:
+
+- "Section 2" / "the section about X" means the HEADING plus everything under it up to the next same-level heading — never the OOXML section property. "The table" includes its contents. "The list" is the visible bulleted/numbered block. "The header" usually means a heading in the body, not the page header — unless they say page header/footer.
+- "The heading" / "the title" is whatever LOOKS like one — titles and ALL-CAPS headings are often styled plain PARAGRAPHS, not heading nodes. Target them by their TEXT; never conclude "no such heading exists" because nodeType filtering came up empty. (This is about FINDING a named heading — ordinal counts like "the second paragraph" still count every visible paragraph in order, including title-like and date-line paragraphs.)
+- FORMAT conversions keep the VALUE. "Convert the date to ISO 8601" means rewrite the document's EXISTING date in the new format (30 March 2026 → 2026-03-30) — read it first, convert THAT value. Never substitute today's date or any other value the user didn't give.
+- MOVE means relocate the SAME thing with ALL of its content and formatting. Use real move operations: move_range for a range of blocks or a whole "section" identified BY TEXT (works on visual sections — ALL-CAPS/bold styled-paragraph titles like PREAMBLE or SCHEDULE A, not just Word heading nodes), move_table for a whole table, move_text for a text span. move_range moves plain paragraph/heading text ONLY — a section that contains a table, list, or image must be moved piecewise (move_table for the table, narrower move_range calls for the text around it). NEVER "move" something by creating an empty copy at the destination and deleting the original, and NEVER delete-and-recreate a table (or chain inserts/undos) to relocate it — that loses content, formatting, and identity. If no move operation exists for a block type, say so before improvising.
+- TRANSFORM consumes its source. "Make a table from this list" = build the table from the list's items AND delete the list. "Turn this paragraph into a heading" leaves exactly one block. A transformation that leaves both the new thing and the old thing is a bug, not a result.
+- COMPLETE the obvious intent. "Add a summary table" implies plausible content and a sensible position. "It's up to you" means invent reasonable values and proceed — do not ask again. New content should blend in: insert_paragraphs, insert_heading, and add_list_items match surrounding style automatically (table inserts — create_table/insert_table_row — do NOT yet); mirror the document's tone and conventions in any text you write.
+- TEMPLATES stay templates. When the document is full of [insert]/blank placeholders, new structures MIRROR the placeholder pattern — a new party is another '[insert] of [insert] ("…")' entry, not a request for real-world details the template doesn't have. Never ask for data a template deliberately leaves blank.
+- PLACEMENT: when the user names a position, honor it exactly. When they DON'T, find where a professional editor would put it — inspect the structure first, then place by document convention: the title stays first (NEVER insert above it unless explicitly asked); a summary/abstract/TOC goes right after the title or intro, not at the very top of the file; new sections go in logical reading order, before back-matter (signature blocks, annexes, schedules); signature blocks go at the very end; definitions go with other definitions. Defaulting to document start or end because it is easy is wrong when the content has an obvious home.
+- LEGAL DOCUMENTS ARE CROSS-REFERENCED. Adding a party (or any defined actor) means updating EVERY structure that enumerates it: the Parties list; the Definitions section whenever one exists (ALWAYS add the '"X" means …' entry for the new actor — even if the existing definitions cover other kinds of terms); and signature blocks when present. Same for removals. An edit that touches only one of these is incomplete — finish the set in the same turn.
+- CLEANUP is part of the job. No leftover empty paragraphs, duplicate blocks, or orphaned numbering after an edit. If your edit creates debris, remove it in the same turn.
+- NUMBERS COME FROM SCHEMES, NEVER FROM TEXT. Do not type "11." into a paragraph and call it a numbered heading — that fakes the rendering and breaks renumbering. Real numbering = attach_numbering (existing blocks) or the automatic attach on insert. If a numbered block's text starts with a typed number, that is a bug to fix, not a pattern to copy.
+- NEW SECTIONS in clause-numbered documents (clauses 1.–10.): "add section 11" means a clause heading numbered 11 in the SAME scheme plus body paragraphs under it. Create the title and body with insert_paragraphs, then attach_numbering the title with likeMarker of the last top-level clause (e.g. "10.") — it renders as "11." automatically.
+- NEVER END THE TURN WITH THE DOCUMENT WORSE THAN YOU FOUND IT. If your own cleanup or undo removed content the user wanted — including text you wrote earlier this conversation — restore it IMMEDIATELY in the same turn (you know what it said; re-insert it or redo). Do not ask permission to repair damage you caused.
+- REVIEW means READING. "Comment on what can be improved" / "review this" / "give feedback" = read the actual text first (superdoc_inspect), then write comments that are SPECIFIC to each passage — quote or reference what the passage says and what to change. Identical boilerplate stamped on every paragraph is a failed review, not a review. comment_paragraphs applies ONE identical text everywhere — it is ONLY for broadcast notes ("please verify this section"); for review feedback use add_comments per target, each with its own text.
+- ACT when intent is plain; ask only when the request is genuinely ambiguous AND the wrong guess would be destructive. One clarifying question maximum, with your best-guess default stated.
+
+============================================================
+TOOLS — two of them
+============================================================
+
+  superdoc_inspect   — read-only deterministic document snapshot.
+  superdoc_perform_action    — named edit verbs we authored, tested, and validate statically. Pass {action:"name", ...flat args}.
+
+ROUTING
+
+superdoc_perform_action is your edit surface — named verbs whose argument shape, target resolution, and verification we authored. Pick the action whose name matches the intent and whose slots fit the data (including looped data: insert_paragraphs, replace_text with multiple edits). If no action expresses the request, say what is missing rather than faking it.
+
+Default workflow: inspect if you need orientation or targets → one action → read the receipt → stop with a one-sentence answer.
+
+============================================================
+ACTIONS (superdoc_perform_action with flat args)
+============================================================
+
+- insert_paragraphs: texts (in final order) — or a single text for one paragraph. headingLevel makes the first item a heading (1-6). changeMode:"tracked" if asked. Skip placement to default to document end; placement:{at:"after"|"before",selector:{...}} to position. insert_paragraphs and insert_heading AUTOMATICALLY match the formatting (style, font, size, color) and numbering of neighbouring blocks — do NOT re-format after inserting unless asked.
+- insert_heading: text, level (1-6).
+- append_list: items (string array), kind:"ordered"|"bullet". headingText/headingLevel only if asked for a heading above. placement:{at:"after"|"before",selector:{...}} builds the list at that block instead of document end — when the list belongs inside a section, ALWAYS pass placement. The receipt's placement-honored check is the truth.
+- add_list_items: entries:[{text, level?}] (level relative to the anchor: 0 = same level, 1 = nested sub-item) — or items:[…] plain strings at the list level. Locate the list by anchorText (text inside one of its items) or listOrdinal (1-based). THE way to ADD items into an EXISTING list — reuses its numbering + markers, matches the anchor item's font/size/bold/colour automatically (receipt.formattingMatched — do NOT re-format after adding unless asked), joins imported list-looking paragraphs in place, and is tracked-safe. NOT append_list (which starts a brand-new list).
+- convert_list: kind:"ordered"|"bullet", with listOrdinal or anchorText for real lists, OR fromMarker+toMarker (rendered clause numbers from inspect, e.g. "2.1.", "2.3.") for NUMBERED-CLAUSE ranges — including heading-styled clauses, OR fromText+toText (exact text inside the FIRST and LAST of consecutive plain paragraphs) to convert existing paragraphs into a list IN PLACE. Sub-clauses in range included automatically. THE way to convert numbering<->bullets AND the way to make existing paragraphs a list; never rewrite text to fake it, never recreate-the-content-then-delete-the-originals (two chances to lose text — convert_list fromText/toText is one lossless call).
+- split_list: anchorText (text inside the item that should START the second list), restartNumbering? (default true). Splits ONE list into two at that item — the new list restarts at 1, nested sub-items stay with their parent. THE way to "split the list starting at item N into a new list with reset numbering"; never fake it with convert_list/attach_numbering. Direct edit (not tracked).
+- undo_changes: untilMarker (rendered marker from the original state, e.g. "2.1.") or steps (1-25). Deterministic revert — steps history back until the marker reappears; the receipt proves it. NEVER use steps > 1 blindly: prefer untilMarker, and after ANY undo verify (superdoc_inspect) that content you meant to KEEP still exists — if you overshot, redo_changes {steps:N} steps forward again to recover it.
+- redo_changes: steps (1-25, default 1). Steps history FORWARD to re-apply edits a prior undo removed — THE recovery for an undo overshoot. Only reaches the forward branch until a NEW edit is made.
+- attach_numbering: anchorText (text of the block) or nodeId, likeMarker (rendered marker of a sibling clause, e.g. "10."). Makes an EXISTING block a numbered clause at the same scheme/level — "make this the section 11 heading" in a clause-numbered document is exactly this (it will render as the next number).
+- replace_text: edits:[{find,replace}], caseSensitive default false. selector to scope. changeMode:"tracked" if asked. The receipt reports editsApplied and editsSkipped per find — READ IT: a skipped find is not in the selected block; re-target instead of assuming success.
+- delete_text: finds:[string]. selector to scope deletions to ONE block — REQUIRED for whitespace-only finds (unscoped whitespace matches document-wide and is refused). changeMode:"tracked" if asked.
+- rewrite_block: selector, text. Inspect first to gather current text; never ask the user to paste text already in the doc.
+- create_table: rows, columns, optional cellTexts (2D array). rows counts ALL rows INCLUDING the header — header plus one data row is rows:2. placement defaults to document end. changeMode:"tracked" if asked ("track-changes table") — the insertion itself becomes a tracked change.
+- comment_paragraphs: commentText. excludeBlockQuotes:true to skip block quotes. Applies the SAME text to every BODY paragraph (it does NOT comment the title/heading) — broadcast notes only, never review feedback (see REVIEW rule). To comment a heading too, add_comments on it explicitly.
+- add_comments: commentText, and either selector (one block) or selectors:[…] to comment MANY blocks in ONE call with the same text. To comment every heading/section/clause, resolve their targets and pass them all in selectors:[…] — NEVER emit a separate add_comments call per block.
+- reply_to_comment: commentText (the reply body), and either anchorText (text the target comment is anchored on / mentions) or commentId. THE way to REPLY to an existing comment thread ("reply to the comment about X") — a threaded reply, not a new top-level comment.
+- resolve_comments: anchorText? (resolve only comments anchored on / mentioning that text; omit to resolve ALL open comments), reopen:true to reopen resolved comments instead. THE way to "resolve the comment(s)" / "mark comments resolved".
+- accept_tracked_changes / reject_tracked_changes: optional author:"Full Name", optional changeType:"insert"|"delete"|"replacement"|"format". "Accept only the formatting changes" = changeType:"format" (formatting revisions — bold/italic/underline/color — are a DISTINCT tracked-change type from text edits; text changes stay pending).
+- format_text: bold/italic/underline/strike:true, highlight:"yellow", color (named or hex), fontSize — applied to EVERY occurrence of targetText (or targetTexts:["…","…"] for several phrases in one call; or selector for a whole block). caseSensitive:true for exact case. changeMode:"tracked" produces format-type tracked changes. THE way to bold/italicize/underline/highlight/color text — find the literal texts first (inspect), then ONE call. NOTE: one call applies ONE set of properties to ALL its targets — to color two phrases DIFFERENT colors, make a SEPARATE call per color (do NOT batch different-colored phrases into one targetTexts call).
+- apply_style: selector (the block to restyle), then ONE of styleId ("Heading2"), headingLevel (1-6), or likeText (text inside the block whose style AND effective look to copy). "Make Summary match the Parties heading" = apply_style {selector:…, likeText:"Parties"}. THE way to restyle an existing block — never delete-and-recreate it.
+- normalize_body_font_size: fontSize:N.
+- set_font_family: fontFamily ("Arial", "Times New Roman"). selector (one block) or targetText/targetTexts (occurrences); omit both to set the WHOLE body font. changeMode:"tracked" if asked. THE way to change the typeface ("change the font to X").
+- apply_letter_spacing: selector, letterSpacing (points).
+- format_paragraph: selector, alignment:"left"|"center"|"right"|"justify". changeMode:"tracked" records the former alignment as a tracked change. THE way to set paragraph alignment.
+- set_paragraph_spacing: selector, lineSpacing (multiplier, e.g. 1.5 or 2), spaceBefore/spaceAfter (points). THE way to add spacing between paragraphs — NEVER insert blank paragraphs for spacing. Direct edit (not tracked).
+- insert_page_break: selector (the block that should START on a new page). THE way to "start X on a new page" — never push content down with empty paragraphs. Direct edit (not tracked).
+- add_hyperlink: text (exact existing text to link), url, optional tooltip. Makes existing text a clickable hyperlink. Direct edit (not tracked).
+- fill_placeholders: values:[...] and/or fields:[{label?,value}]. changeMode:"tracked" if asked.
+- move_range: fromText (text in the FIRST block of the range), toText? (text in the LAST block — omit to auto-extend across the whole VISUAL SECTION: from fromText up to the next heading-like/ALL-CAPS/bold title), then exactly ONE destination: afterText OR beforeText (text in the block to land after/before). Direct-only today: changeMode:"tracked" fails with no mutation because block-range deletion cannot be tracked. Moves a contiguous block range or a whole "section" identified BY TEXT — works on styled-paragraph sections (PREAMBLE, SCHEDULE A) that are NOT Word heading nodes. afterText on a heading-like block lands the range after that block's WHOLE section. Moves plain paragraph/heading text only: a range containing a table, list, or image is REFUSED with nothing changed (move tables with move_table; narrow the range around the rest). Use move_text for tracked text-span moves.
+- insert_toc: title (optional), placement (defaults to document_start).
+- move_text: text (the exact span/clause to relocate), afterText (destination — REQUIRED for a direct move). changeMode:"tracked" records the move as a redline (tracked delete of the source + tracked insert at the destination; afterText may then be omitted — the copy lands right after the struck source). For a text SPAN; whole sections = move_range, tables = move_table.
+- move_table: tableOrdinal? (default 1), placement {at:"document_end"|"document_start"|"after"|"before", selector?}. THE way to move a whole table in ONE call — never delete-and-recreate or chain inserts/undos to relocate a table.
+- delete_table: tableOrdinal? (default 1), changeMode?. THE way to delete an entire table in ONE call — never delete rows one by one or reuse another table.
+- style_table: tableOrdinal? (default 1), accentColor? (header fill hex). ONE call makes a table look professional: accent header row with white bold text, bold first column, banded rows, clean borders. Use after create_table or on any existing table.
+- insert_table_row: tableOrdinal (1-based), rowIndex (0-based; omit to append), position:"above"|"below", optional cellTexts. dryRun:true for preview.
+- insert_table_column: tableOrdinal, columnIndex (0-based; omit to append right), position:"left"|"right", optional headerText.
+- delete_table_row / delete_table_column: rowIndex or columnIndex required, tableOrdinal optional.
+- split_table: tableOrdinal, rowIndex (>=1), optional separatorText.
+
+Selector shapes:
+- {kind:"nodeId", nodeId}
+- {kind:"ordinal", ordinalKind:"bodyParagraphOrdinal"|"paragraphOrdinal"|"headingOrdinal"|"tableOrdinal"|"listOrdinal"|"sectionOrdinal"|"blockOrdinal", value:N}
+- {kind:"tableCell", tableOrdinal:N, rowIndex:R, columnIndex:C}
+- {kind:"textSearch", terms:["..."], match:"all"|"any", occurrence:N, caseSensitive?:false, nodeTypes?:["paragraph"|"heading"|"listItem"]}
+- {kind:"placement", at:"document_end"|"document_start"}
+- {kind:"relative", position:"after"|"before", target:selector}
+
+============================================================
+OPERATING RULES
+============================================================
+
+- RECEIPTS ARE THE TRUTH. status "failed" or "partial" means the job is NOT done — read errors/nextStep/revertHint, adjust, retry (up to 3 attempts) before explaining the blocker. Never end the turn right after a failed or partial receipt. Never claim something the receipt cannot prove.
+- STALENESS: markers, nodeIds, and counts from earlier turns are STALE after any mutation — including your own. Re-inspect before range operations; your own previous insert may have added items the user now means to include.
+- REVERTS: "undo / revert / make it back" = superdoc_perform_action undo_changes with untilMarker from the original state (a convert receipt's revertHint contains the exact call) — NEVER re-convert or re-edit to approximate the old state.
+- If the request names a target descriptively ("the indented heading", "the second clause"), inspect FIRST and use the block's actual text or nodeId — never invent find text.
+- Numbered legal clauses ("2.3.") usually live on numbered HEADINGS, not lists: if counts.lists is 0 but blocks carry numbering markers, target those blocks by nodeId. "Add item 2.4" = insert_paragraphs (one text) after the "2.3." block; the tool attaches numbering and matches formatting automatically (check receipt.contextualFormatting).
+- ADDING SEVERAL items to an existing list or numbered sequence = ONE add_list_items call (it joins the sequence and is tracked-safe — it works even when the "list" is clause numbering and counts.lists is 0). NEVER a chain of insert_paragraphs calls: multi-paragraph inserts do not auto-join numbering, and the items will land as plain paragraphs.
+- New SECTION headings use the SAME headingLevel as sibling section headings (title is usually level 1; sections 2+). Never default to level 1.
+- paragraphOrdinal counts visible non-empty paragraphs; bodyParagraphOrdinal counts substantive body paragraphs after front matter. Prefer paragraphOrdinal for "first/second paragraph".
+- For literal ordinal rewrites, do not switch paragraphs because the matched one looks title-like or short. If a rewrite is a no-op, keep the target and change the rewrite.
+- For anchored rewrites or multi-term edits, prefer textSearch selectors over copied nodeIds. For clause text inside tables, use a tableCell selector with replace_text.
+- For tab-indented headings, replace only the visible text with replace_text (rewrite_block can delete the tab node).
+- For BULK or PATTERN transforms (every percentage, every date), use ONE replace_text call with multiple edits. For bulk FORMATTING ("bold all the dates"): read the matching texts first, then ONE format_text call with targetTexts.
+- For preview-only requests ("show what it would look like", "don't save"), pass dryRun:true and make NO other mutating call; describe the preview from the receipt.
+- Pure count questions: superdoc_inspect countsOnly:true, then stop. Use includeDomains to keep snapshots small.
+- Do not include doc or sessionId in tool args. Never rely on benchmark routing, eval metadata, or fixture names.
+- If the runtime truly cannot express the request, say what is missing instead of faking success.

package/dist/runtime/transport-common.cjs

@@ -48,6 +48,14 @@ function buildOperationArgv(operation, params, options, runtimeTimeoutMs, defaul
         const value = normalizedParams[spec.name];
         if (value == null)
             continue;
+        if (operation.operationId === 'doc.tables.setShading' && spec.name === 'color') {
+            // This operation accepts structured color payloads, so sending the raw
+            // value through --color-json preserves both named colors and richer
+            // object shapes. Treating it like a normal scalar flag would stringify
+            // objects as "[object Object]" and silently corrupt the CLI request.
+            argv.push('--color-json', JSON.stringify(value));
+            continue;
+        }
         const flag = `--${spec.flag ?? spec.name}`;
         switch (spec.kind) {
             case 'doc':

package/dist/runtime/transport-common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport-common.d.ts","sourceRoot":"","sources":["../../src/runtime/transport-common.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAC9E,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,KAAK,GAAG,OAAO,EACpB,SAAS,EAAE,aAAa,EACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,KAAK,CAAC,CAAC;CACnB;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAU/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,iBAAiB,CAAC,EAAE,UAAU,EAC9B,IAAI,CAAC,EAAE,YAAY,GAClB,MAAM,EAAE,CAiEV"}
+{"version":3,"file":"transport-common.d.ts","sourceRoot":"","sources":["../../src/runtime/transport-common.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAC9E,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,KAAK,GAAG,OAAO,EACpB,SAAS,EAAE,aAAa,EACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,KAAK,CAAC,CAAC;CACnB;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAU/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,iBAAiB,CAAC,EAAE,UAAU,EAC9B,IAAI,CAAC,EAAE,YAAY,GAClB,MAAM,EAAE,CA0EV"}

package/dist/runtime/transport-common.js

@@ -46,6 +46,14 @@ export function buildOperationArgv(operation, params, options, runtimeTimeoutMs,
         const value = normalizedParams[spec.name];
         if (value == null)
             continue;
+        if (operation.operationId === 'doc.tables.setShading' && spec.name === 'color') {
+            // This operation accepts structured color payloads, so sending the raw
+            // value through --color-json preserves both named colors and richer
+            // object shapes. Treating it like a normal scalar flag would stringify
+            // objects as "[object Object]" and silently corrupt the CLI request.
+            argv.push('--color-json', JSON.stringify(value));
+            continue;
+        }
         const flag = `--${spec.flag ?? spec.name}`;
         switch (spec.kind) {
             case 'doc':

package/dist/tools.cjs

@@ -31,6 +31,7 @@ async function chooseTools(input) {
     const preset = presets.getPreset(presetId);
     const { tools, cacheStrategy } = await preset.getTools(input.provider, {
         cache: input.cache === true,
+        excludeActions: input.excludeActions,
     });
     return {
         tools,
@@ -73,29 +74,60 @@ async function listTools(provider, preset) {
  * `getPreset('id').dispatch(...)` directly.
  */
 async function dispatchSuperDocTool(documentHandle, toolName, args = {}, invokeOptions) {
-    return presets.getPreset(presets.DEFAULT_PRESET).dispatch(documentHandle, toolName, args, invokeOptions);
+    const presetId = invokeOptions?.preset ?? presets.DEFAULT_PRESET;
+    const { preset: _p, ...rest } = invokeOptions ?? {};
+    return presets.getPreset(presetId).dispatch(documentHandle, toolName, args, rest);
 }
 // ---------------------------------------------------------------------------
-// System prompts (preset-scoped; default to legacy)
+// System prompts (preset-scoped; default to DEFAULT_PRESET)
 // ---------------------------------------------------------------------------
 /**
- * Read the packaged SDK system prompt (default preset: legacy).
+ * Resolve a preset-id arg that may be a bare string OR a `{preset?: string}`
+ * options object. Object form is tolerated for callers (e.g. older eval
+ * harnesses) that pass `{...}` instead of a string; any unknown keys on the
+ * object are silently dropped and the preset falls through to DEFAULT_PRESET.
+ */
+function resolvePromptPresetArg(preset) {
+    if (typeof preset === 'string')
+        return preset;
+    if (preset != null && typeof preset === 'object' && typeof preset.preset === 'string') {
+        return preset.preset;
+    }
+    return presets.DEFAULT_PRESET;
+}
+/**
+ * One-call agent surface: tools, system prompt, and a pre-bound dispatcher
+ * that are coherent BY CONSTRUCTION — the same preset and `excludeActions`
+ * apply to all three, so an action can never linger in the prompt after
+ * being excluded from the tool array (or vice versa).
  *
- * Includes a persona preamble ("You are a document editing assistant…")
- * suitable for embedded LLM usage (OpenAI, Anthropic, Vercel APIs). For MCP
- * server instructions, use {@link getMcpPrompt} instead.
+ * The legacy preset ignores exclusion options everywhere (it has no action
+ * surface); passing `excludeActions` with `preset: 'legacy'` is a no-op,
+ * matching the standalone functions.
  */
-async function getSystemPrompt(preset) {
-    return presets.getPreset(preset ?? presets.DEFAULT_PRESET).getSystemPrompt();
+async function createAgentToolkit(input) {
+    const presetId = input.preset ?? presets.DEFAULT_PRESET;
+    const excludeActions = input.excludeActions ? [...input.excludeActions] : undefined;
+    const { tools, meta } = await chooseTools({ ...input, preset: presetId, excludeActions });
+    const systemPrompt = await getSystemPrompt(presetId, excludeActions ? { excludeActions } : undefined);
+    const dispatch = (documentHandle, toolName, args = {}, invokeOptions) => dispatchSuperDocTool(documentHandle, toolName, args, {
+        ...invokeOptions,
+        preset: presetId,
+        ...(excludeActions ? { excludeActions } : {}),
+    });
+    return { tools, meta, systemPrompt, dispatch };
+}
+async function getSystemPrompt(preset, options) {
+    return presets.getPreset(resolvePromptPresetArg(preset)).getSystemPrompt(options);
 }
 /**
- * Read the packaged MCP system prompt for intent tools (default preset: legacy).
+ * Read the MCP system prompt for the given preset (default: {@link DEFAULT_PRESET}).
  *
  * Omits the persona preamble and includes session lifecycle instructions
  * (open/save/close) suitable for MCP server `instructions`.
  */
 async function getMcpPrompt(preset) {
-    return presets.getPreset(preset ?? presets.DEFAULT_PRESET).getMcpPrompt();
+    return presets.getPreset(resolvePromptPresetArg(preset)).getMcpPrompt();
 }
 /**
  * Get the system prompt formatted for a specific LLM provider, with optional
@@ -122,7 +154,7 @@ async function getMcpPrompt(preset) {
  * ```
  */
 async function getSystemPromptForProvider(input) {
-    const text = await getSystemPrompt(input.preset);
+    const text = await getSystemPrompt(input.preset, input.excludeActions ? { excludeActions: input.excludeActions } : undefined);
     const cacheRequested = input.cache === true;
     if (input.provider === 'anthropic') {
         const block = { type: 'text', text };
@@ -145,7 +177,10 @@ async function getSystemPromptForProvider(input) {
 exports.DEFAULT_PRESET = presets.DEFAULT_PRESET;
 exports.getPreset = presets.getPreset;
 exports.listPresets = presets.listPresets;
+exports.registerPreset = presets.registerPreset;
+exports.unregisterPreset = presets.unregisterPreset;
 exports.chooseTools = chooseTools;
+exports.createAgentToolkit = createAgentToolkit;
 exports.dispatchSuperDocTool = dispatchSuperDocTool;
 exports.getMcpPrompt = getMcpPrompt;
 exports.getSystemPrompt = getSystemPrompt;

package/dist/tools.d.ts

@@ -9,9 +9,9 @@
  */
 import type { BoundDocApi } from './generated/client.js';
 import type { InvokeOptions } from './runtime/process.js';
-import { DEFAULT_PRESET, getPreset, listPresets, type CacheStrategy, type ToolCatalog, type ToolCatalogEntry, type ToolCatalogOperation, type ToolProvider } from './presets.js';
-export { DEFAULT_PRESET, getPreset, listPresets };
-export type { CacheStrategy, ToolCatalog, ToolCatalogEntry, ToolCatalogOperation, ToolProvider };
+import { DEFAULT_PRESET, getPreset, listPresets, registerPreset, unregisterPreset, type CacheStrategy, type GetSystemPromptOptions, type ToolCatalog, type ToolCatalogEntry, type ToolCatalogOperation, type ToolProvider } from './presets.js';
+export { DEFAULT_PRESET, getPreset, listPresets, registerPreset, unregisterPreset };
+export type { CacheStrategy, GetSystemPromptOptions, ToolCatalog, ToolCatalogEntry, ToolCatalogOperation, ToolProvider, };
 export type ToolChooserInput = {
     provider: ToolProvider;
     /**
@@ -35,6 +35,13 @@ export type ToolChooserInput = {
      *   underlying model; reported as `'unsupported'`.
      */
     cache?: boolean;
+    /**
+     * Action names to REMOVE from the advertised action surface. Supported by
+     * the `core` preset (the `superdoc_perform_action` enum, description, and
+     * argument properties shrink together); presets without an action surface
+     * ignore it. Unknown names throw.
+     */
+    excludeActions?: readonly string[];
 };
 /**
  * Select tools for a specific provider from a preset.
@@ -79,22 +86,60 @@ export declare function listTools(provider: ToolProvider, preset?: string): Prom
  * For preset-aware dispatch — e.g. when comparing two presets — call
  * `getPreset('id').dispatch(...)` directly.
  */
-export declare function dispatchSuperDocTool(documentHandle: BoundDocApi, toolName: string, args?: Record<string, unknown>, invokeOptions?: InvokeOptions): Promise<unknown>;
+export declare function dispatchSuperDocTool(documentHandle: BoundDocApi, toolName: string, args?: Record<string, unknown>, invokeOptions?: InvokeOptions & {
+    preset?: string;
+    /** Refuse dispatch of these actions (defense-in-depth for exclusion configs). */
+    excludeActions?: readonly string[];
+}): Promise<unknown>;
 /**
- * Read the packaged SDK system prompt (default preset: legacy).
+ * Read the SDK system prompt for the given preset (default: {@link DEFAULT_PRESET}).
  *
  * Includes a persona preamble ("You are a document editing assistant…")
  * suitable for embedded LLM usage (OpenAI, Anthropic, Vercel APIs). For MCP
  * server instructions, use {@link getMcpPrompt} instead.
  */
-export declare function getSystemPrompt(preset?: string): Promise<string>;
+export type CreateAgentToolkitInput = ToolChooserInput;
+export type AgentToolkit = {
+    /** Provider-shaped tool definitions (see {@link chooseTools}). */
+    tools: unknown[];
+    meta: {
+        provider: ToolProvider;
+        preset: string;
+        toolCount: number;
+        cacheStrategy: CacheStrategy;
+    };
+    /** The preset's system prompt with the SAME exclusions applied. */
+    systemPrompt: string;
+    /**
+     * {@link dispatchSuperDocTool} pre-bound to this toolkit's preset and
+     * exclusions — an excluded action is refused here even if the model
+     * guesses its name.
+     */
+    dispatch: (documentHandle: BoundDocApi, toolName: string, args?: Record<string, unknown>, invokeOptions?: InvokeOptions) => Promise<unknown>;
+};
+/**
+ * One-call agent surface: tools, system prompt, and a pre-bound dispatcher
+ * that are coherent BY CONSTRUCTION — the same preset and `excludeActions`
+ * apply to all three, so an action can never linger in the prompt after
+ * being excluded from the tool array (or vice versa).
+ *
+ * The legacy preset ignores exclusion options everywhere (it has no action
+ * surface); passing `excludeActions` with `preset: 'legacy'` is a no-op,
+ * matching the standalone functions.
+ */
+export declare function createAgentToolkit(input: CreateAgentToolkitInput): Promise<AgentToolkit>;
+export declare function getSystemPrompt(preset?: string | {
+    preset?: string;
+}, options?: GetSystemPromptOptions): Promise<string>;
 /**
- * Read the packaged MCP system prompt for intent tools (default preset: legacy).
+ * Read the MCP system prompt for the given preset (default: {@link DEFAULT_PRESET}).
  *
  * Omits the persona preamble and includes session lifecycle instructions
  * (open/save/close) suitable for MCP server `instructions`.
  */
-export declare function getMcpPrompt(preset?: string): Promise<string>;
+export declare function getMcpPrompt(preset?: string | {
+    preset?: string;
+}): Promise<string>;
 /**
  * Anthropic content block representation of the system prompt with optional
  * `cache_control` for prompt caching.
@@ -143,5 +188,7 @@ export declare function getSystemPromptForProvider(input: {
     provider: ToolProvider;
     preset?: string;
     cache?: boolean;
+    /** Same exclusions as chooseTools — keeps the provider-shaped prompt and the tool surface narrowed together. */
+    excludeActions?: readonly string[];
 }): Promise<SystemPromptForProviderResult>;
 //# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EACL,cAAc,EACd,SAAS,EACT,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;AAClD,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,YAAY,EAAE,CAAC;AAMjG,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,YAAY,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC;IAClE,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,IAAI,EAAE;QACJ,QAAQ,EAAE,YAAY,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,aAAa,CAAC;KAC9B,CAAC;CACH,CAAC,CAeD;AAMD,mEAAmE;AACnE,wBAAsB,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAE1E;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAG3F;AAMD;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,cAAc,EAAE,WAAW,EAC3B,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAClC,aAAa,CAAC,EAAE,aAAa,GAC5B,OAAO,CAAC,OAAO,CAAC,CAElB;AAMD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEtE;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnE;AAMD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,KAAK,CAAC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC;CACvC,CAAC,CAAC;AAEH,MAAM,MAAM,6BAA6B,GACrC;IAAE,QAAQ,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAC;IAAC,aAAa,EAAE,aAAa,CAAA;CAAE,GACvF;IAAE,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,aAAa,CAAA;CAAE,CAAC;AAEjG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,0BAA0B,CAAC,KAAK,EAAE;IACtD,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,6BAA6B,CAAC,CAqBzC"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -7,8 +7,8 @@
  * "core" tools, prompt-caching variant, lazy-load experiment), register a new
  * descriptor in `presets.ts` — no changes here required.
  */
-import { DEFAULT_PRESET, getPreset, listPresets, } from './presets.js';
-export { DEFAULT_PRESET, getPreset, listPresets };
+import { DEFAULT_PRESET, getPreset, listPresets, registerPreset, unregisterPreset, } from './presets.js';
+export { DEFAULT_PRESET, getPreset, listPresets, registerPreset, unregisterPreset };
 /**
  * Select tools for a specific provider from a preset.
  *
@@ -29,6 +29,7 @@ export async function chooseTools(input) {
     const preset = getPreset(presetId);
     const { tools, cacheStrategy } = await preset.getTools(input.provider, {
         cache: input.cache === true,
+        excludeActions: input.excludeActions,
     });
     return {
         tools,
@@ -71,29 +72,60 @@ export async function listTools(provider, preset) {
  * `getPreset('id').dispatch(...)` directly.
  */
 export async function dispatchSuperDocTool(documentHandle, toolName, args = {}, invokeOptions) {
-    return getPreset(DEFAULT_PRESET).dispatch(documentHandle, toolName, args, invokeOptions);
+    const presetId = invokeOptions?.preset ?? DEFAULT_PRESET;
+    const { preset: _p, ...rest } = invokeOptions ?? {};
+    return getPreset(presetId).dispatch(documentHandle, toolName, args, rest);
 }
 // ---------------------------------------------------------------------------
-// System prompts (preset-scoped; default to legacy)
+// System prompts (preset-scoped; default to DEFAULT_PRESET)
 // ---------------------------------------------------------------------------
 /**
- * Read the packaged SDK system prompt (default preset: legacy).
+ * Resolve a preset-id arg that may be a bare string OR a `{preset?: string}`
+ * options object. Object form is tolerated for callers (e.g. older eval
+ * harnesses) that pass `{...}` instead of a string; any unknown keys on the
+ * object are silently dropped and the preset falls through to DEFAULT_PRESET.
+ */
+function resolvePromptPresetArg(preset) {
+    if (typeof preset === 'string')
+        return preset;
+    if (preset != null && typeof preset === 'object' && typeof preset.preset === 'string') {
+        return preset.preset;
+    }
+    return DEFAULT_PRESET;
+}
+/**
+ * One-call agent surface: tools, system prompt, and a pre-bound dispatcher
+ * that are coherent BY CONSTRUCTION — the same preset and `excludeActions`
+ * apply to all three, so an action can never linger in the prompt after
+ * being excluded from the tool array (or vice versa).
  *
- * Includes a persona preamble ("You are a document editing assistant…")
- * suitable for embedded LLM usage (OpenAI, Anthropic, Vercel APIs). For MCP
- * server instructions, use {@link getMcpPrompt} instead.
+ * The legacy preset ignores exclusion options everywhere (it has no action
+ * surface); passing `excludeActions` with `preset: 'legacy'` is a no-op,
+ * matching the standalone functions.
  */
-export async function getSystemPrompt(preset) {
-    return getPreset(preset ?? DEFAULT_PRESET).getSystemPrompt();
+export async function createAgentToolkit(input) {
+    const presetId = input.preset ?? DEFAULT_PRESET;
+    const excludeActions = input.excludeActions ? [...input.excludeActions] : undefined;
+    const { tools, meta } = await chooseTools({ ...input, preset: presetId, excludeActions });
+    const systemPrompt = await getSystemPrompt(presetId, excludeActions ? { excludeActions } : undefined);
+    const dispatch = (documentHandle, toolName, args = {}, invokeOptions) => dispatchSuperDocTool(documentHandle, toolName, args, {
+        ...invokeOptions,
+        preset: presetId,
+        ...(excludeActions ? { excludeActions } : {}),
+    });
+    return { tools, meta, systemPrompt, dispatch };
+}
+export async function getSystemPrompt(preset, options) {
+    return getPreset(resolvePromptPresetArg(preset)).getSystemPrompt(options);
 }
 /**
- * Read the packaged MCP system prompt for intent tools (default preset: legacy).
+ * Read the MCP system prompt for the given preset (default: {@link DEFAULT_PRESET}).
  *
  * Omits the persona preamble and includes session lifecycle instructions
  * (open/save/close) suitable for MCP server `instructions`.
  */
 export async function getMcpPrompt(preset) {
-    return getPreset(preset ?? DEFAULT_PRESET).getMcpPrompt();
+    return getPreset(resolvePromptPresetArg(preset)).getMcpPrompt();
 }
 /**
  * Get the system prompt formatted for a specific LLM provider, with optional
@@ -120,7 +152,7 @@ export async function getMcpPrompt(preset) {
  * ```
  */
 export async function getSystemPromptForProvider(input) {
-    const text = await getSystemPrompt(input.preset);
+    const text = await getSystemPrompt(input.preset, input.excludeActions ? { excludeActions: input.excludeActions } : undefined);
     const cacheRequested = input.cache === true;
     if (input.provider === 'anthropic') {
         const block = { type: 'text', text };