@superdoc/sdk 2.0.0-next.100 → 2.1.0

package/README.md

@@ -1,22 +1,22 @@
-# @superdoc/sdk
+# @superdoc-dev/sdk
 
 Programmatic SDK for deterministic DOCX operations through SuperDoc's Document API.
 
 ## Install
 
 ```bash
-npm install @superdoc/sdk
+npm install @superdoc-dev/sdk
 ```
 
 The package automatically installs a native CLI binary for your platform via optionalDependencies. Supported platforms:
 
 | Platform | Package |
 |----------|---------|
-| macOS (Apple Silicon) | `@superdoc/sdk-darwin-arm64` |
-| macOS (Intel) | `@superdoc/sdk-darwin-x64` |
-| Linux (x64) | `@superdoc/sdk-linux-x64` |
-| Linux (ARM64) | `@superdoc/sdk-linux-arm64` |
-| Windows (x64) | `@superdoc/sdk-windows-x64` |
+| macOS (Apple Silicon) | `@superdoc-dev/sdk-darwin-arm64` |
+| macOS (Intel) | `@superdoc-dev/sdk-darwin-x64` |
+| Linux (x64) | `@superdoc-dev/sdk-linux-x64` |
+| Linux (ARM64) | `@superdoc-dev/sdk-linux-arm64` |
+| Windows (x64) | `@superdoc-dev/sdk-windows-x64` |
 
 ## Quick Start
 
@@ -24,14 +24,14 @@ Both ESM and CommonJS are supported.
 
 ```ts
 // ESM
-import { createSuperDocClient } from '@superdoc/sdk';
+import { createSuperDocClient } from '@superdoc-dev/sdk';
 
 // CJS
-const { createSuperDocClient } = require('@superdoc/sdk');
+const { createSuperDocClient } = require('@superdoc-dev/sdk');
 ```
 
 ```ts
-import { createSuperDocClient } from '@superdoc/sdk';
+import { createSuperDocClient } from '@superdoc-dev/sdk';
 
 const client = createSuperDocClient();
 await client.connect();
@@ -74,7 +74,7 @@ The password is forwarded only for the initial open and is not persisted. If the
 ### Client
 
 ```ts
-import { SuperDocClient, createSuperDocClient } from '@superdoc/sdk';
+import { SuperDocClient, createSuperDocClient } from '@superdoc-dev/sdk';
 
 const client = createSuperDocClient(options?);
 await client.connect();    // start the host process
@@ -118,7 +118,7 @@ import {
   chooseTools,
   dispatchSuperDocTool,
   getToolCatalog,
-} from '@superdoc/sdk';
+} from '@superdoc-dev/sdk';
 
 // Get the full grouped tool set for your AI provider
 const { tools, meta } = await chooseTools({

package/dist/agent/actions.cjs

@@ -11,6 +11,7 @@ const ACTION_NAMES = [
     'insert_heading',
     'replace_text',
     'delete_text',
+    'delete_blocks',
     'append_list',
     'create_table',
     'comment_paragraphs',
@@ -59,7 +60,8 @@ const ACTION_HINTS = {
     insert_paragraphs: 'texts[] (or text for a single paragraph), placement?, headingLevel? (first item as heading 1-6), changeMode?',
     insert_heading: 'text, level, placement?, changeMode?',
     replace_text: 'edits[{find,replace}], optional selector to scope replacements to one inspected block, caseSensitive?, changeMode?',
-    delete_text: 'finds[], optional selector to scope deletions to ONE inspected block (required to delete stray whitespace — an unscoped whitespace find matches document-wide), caseSensitive?, changeMode?',
+    delete_text: "finds[], optional selector to scope deletions to ONE inspected block (required to delete stray whitespace — an unscoped whitespace find matches document-wide), caseSensitive?, changeMode? — deletes TEXT ONLY, leaving the block (and a list item's bullet/number) in place. To remove a whole list item, paragraph or heading use delete_blocks",
+    delete_blocks: 'selectors[] (each resolving to ONE inspected block: list item, paragraph or heading), changeMode? — THE way to DELETE a whole LIST ITEM, paragraph or heading, bullet/number included. Use for "remove the first item under Article II" / "delete that clause". delete_text only strikes the text and leaves an empty numbered item behind. Deletes several blocks in ONE call; use delete_table for a whole table and delete_text to clear a table cell (a cell must keep a paragraph)',
     append_list: 'items[], kind?: ordered|bullet, headingText?, headingLevel?, placement? {at:"after"|"before",selector} builds the list at that block instead of document end',
     create_table: 'rows, columns, cellTexts?, placement?, changeMode? — changeMode:"tracked" makes the table insertion itself a tracked change',
     rewrite_block: 'selector, text, changeMode?',
@@ -106,6 +108,7 @@ const ACTION_GROUPS = [
             'insert_heading',
             'replace_text',
             'delete_text',
+            'delete_blocks',
             'append_list',
             'create_table',
             'rewrite_block',
@@ -167,6 +170,7 @@ const ACTION_ARGS = {
     insert_heading: ['text', 'level', 'placement', 'changeMode'],
     replace_text: ['edits', 'selector', 'caseSensitive', 'changeMode'],
     delete_text: ['finds', 'selector', 'caseSensitive', 'changeMode'],
+    delete_blocks: ['selectors', 'selector', 'changeMode'],
     append_list: ['items', 'kind', 'headingText', 'headingLevel', 'placement', 'changeMode'],
     create_table: ['rows', 'columns', 'cellTexts', 'placement', 'changeMode'],
     comment_paragraphs: ['commentText', 'scope', 'excludeBlockQuotes'],
@@ -1225,6 +1229,157 @@ async function runDeleteText(doc, args) {
         return failedReceipt('delete_text', err, pre);
     }
 }
+/** Block node types `doc.blocks.delete` removes as a whole paragraph-shaped block. */
+const DELETABLE_BLOCK_NODE_TYPES = new Set(['paragraph', 'heading', 'listItem']);
+/**
+ * delete_blocks — remove ENTIRE blocks (list items, paragraphs, headings) in
+ * ONE call. Wraps doc.blocks.delete, which removes the block NODE, its
+ * paragraph properties (`w:pPr`, including a list item's `w:numPr`) included.
+ *
+ * delete_text only strikes the RUNS. Routing "delete this list item"
+ * through it leaves the numbered paragraph behind, so accepting the tracked
+ * change yields an empty `1.` and the following items never renumber. Whole-
+ * block removal has to go through blocks.delete, and in tracked mode that
+ * records ONE structural revision whose acceptance removes the paragraph and
+ * whose rejection restores it intact.
+ */
+async function runDeleteBlocks(doc, args) {
+    const domains = new Set(['blocks', 'trackedChanges']);
+    for (const selector of args.selectors) {
+        for (const domain of snapshotDomainsForSelector(selector))
+            domains.add(domain);
+    }
+    const pre = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: [...domains] });
+    try {
+        if (args.selectors.length === 0) {
+            return failedReceipt('delete_blocks', new Error('selectors must be non-empty'), pre);
+        }
+        const deleteFn = maybeMethod(doc, ['blocks', 'delete']);
+        if (!deleteFn) {
+            throw new errors.SuperDocCliError('doc.blocks.delete is not available on the document handle.', {
+                code: 'TOOL_DISPATCH_NOT_FOUND',
+            });
+        }
+        // Resolve EVERY selector against the same pre-snapshot before deleting
+        // anything. nodeIds are stable paragraph ids, so a target resolved up front
+        // stays addressable after a sibling is removed — whereas an ordinal or
+        // text-search selector re-resolved mid-run would drift onto the wrong block.
+        const targets = [];
+        const unresolved = [];
+        const wrongShape = [];
+        const seen = new Set();
+        for (const selector of args.selectors) {
+            // A tableCell selector resolves to the FIRST PARAGRAPH inside the cell,
+            // so it would otherwise pass the paragraph-shape gate below. Removing it
+            // is not a whole-block delete: a `<w:tc>` must keep at least one
+            // paragraph, so deleting the only one leaves invalid OOXML, and in
+            // tracked mode the compiler can only strike the runs anyway. Refuse the
+            // shape rather than half-honour it.
+            if (selector.kind === 'tableCell') {
+                wrongShape.push({ selector, nodeType: 'tableCell' });
+                continue;
+            }
+            const target = selectorToBlockTarget(selector, pre);
+            if (!target) {
+                unresolved.push(selector);
+                continue;
+            }
+            if (!DELETABLE_BLOCK_NODE_TYPES.has(target.nodeType)) {
+                wrongShape.push({ selector, nodeType: target.nodeType });
+                continue;
+            }
+            if (seen.has(target.nodeId))
+                continue;
+            seen.add(target.nodeId);
+            targets.push({ selector, nodeId: target.nodeId, nodeType: target.nodeType });
+        }
+        const errors$1 = [];
+        for (const selector of unresolved) {
+            errors$1.push({
+                code: 'ACTION_FAILED',
+                message: `selector did not resolve to a unique body block: ${JSON.stringify(selector)}`,
+                recovery: { kind: 'reinspect' },
+            });
+        }
+        for (const entry of wrongShape) {
+            errors$1.push({
+                code: 'INVALID_ARGUMENT',
+                message: `delete_blocks removes paragraph-shaped blocks (list items, paragraphs, headings); ` +
+                    `${JSON.stringify(entry.selector)} resolved to a "${entry.nodeType}"` +
+                    (entry.nodeType === 'table'
+                        ? ' — use delete_table for a whole table.'
+                        : entry.nodeType === 'tableCell'
+                            ? ' — a cell must keep a paragraph; use delete_text to clear it, or delete_table_row/delete_table_column.'
+                            : '.'),
+                recovery: { kind: 'reinspect' },
+            });
+        }
+        if (targets.length === 0) {
+            return {
+                status: 'failed',
+                intent: 'delete_blocks',
+                preSnapshot: { revision: pre.revision, counts: pre.counts },
+                selectedTargets: [],
+                executedOperations: [],
+                verification: [],
+                errors: errors$1,
+            };
+        }
+        const changeMode = parseChangeMode(args.changeMode);
+        const executedOperations = [];
+        const deleted = [];
+        for (const target of targets) {
+            try {
+                const result = await deleteFn({ target: { kind: 'block', nodeType: target.nodeType, nodeId: target.nodeId } }, changeMode ? { changeMode } : undefined);
+                executedOperations.push({ operationId: 'doc.blocks.delete', result: compactOpResult(result) });
+                deleted.push({ nodeId: target.nodeId, nodeType: target.nodeType });
+            }
+            catch (err) {
+                errors$1.push({
+                    code: 'ACTION_FAILED',
+                    message: `blocks.delete failed for ${target.nodeType} ${target.nodeId}: ${err instanceof Error ? err.message : String(err)}`,
+                    recovery: { kind: 'reinspect' },
+                });
+            }
+        }
+        const post = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: [...domains] });
+        // Tracked deletions leave the block in place until the revision is decided,
+        // so the block count cannot move — count the structural revisions instead.
+        // Direct deletions must show one fewer block of each deleted node type.
+        const checks = changeMode === 'tracked'
+            ? [{ kind: 'tracked-change-count-delta', delta: deleted.length }]
+            : [...new Set(deleted.map((entry) => entry.nodeType))].map((nodeType) => ({
+                kind: 'block-count-delta',
+                nodeType,
+                delta: -deleted.filter((entry) => entry.nodeType === nodeType).length,
+            }));
+        const verification = evaluateChecks(pre, post, checks);
+        // Compare against the DEDUPED target list: two selectors naming the same
+        // block are one deletion, and counting the raw selectors would report a
+        // fully applied call as `partial` with no error to explain it. Selectors
+        // that never became a target (unresolved or wrong-shape) already recorded
+        // an error, so the `errors.length` term still catches a short request.
+        const allApplied = deleted.length === targets.length && errors$1.length === 0;
+        const verified = verification.every((v) => v.passed);
+        return {
+            status: !verified || deleted.length === 0 ? 'failed' : allApplied ? 'ok' : 'partial',
+            intent: `delete_blocks: ${deleted.length} block(s)`,
+            preSnapshot: { revision: pre.revision, counts: pre.counts },
+            postSnapshot: { revision: post.revision, counts: post.counts },
+            selectedTargets: targets.map((target) => ({ selector: target.selector, matched: [target.nodeId] })),
+            executedOperations,
+            verification,
+            deletedBlocks: deleted,
+            ...(errors$1.length ? { errors: errors$1 } : {}),
+            ...(errors$1.length
+                ? { nextStep: 'Re-inspect the document and retry the selectors that did not resolve to one block.' }
+                : {}),
+        };
+    }
+    catch (err) {
+        return failedReceipt('delete_blocks', err, pre);
+    }
+}
 async function runAppendList(doc, args) {
     const pre = await docSnapshot.buildDocumentSnapshot(doc);
     try {
@@ -4692,6 +4847,33 @@ async function superdocPerformAction(doc, args) {
                 changeMode: parseChangeMode(args.changeMode),
             });
         }
+        case 'delete_blocks': {
+            // Accept a single `selector` too: the model reaches for the singular form
+            // by analogy with delete_text/rewrite_block, and rejecting it would cost a
+            // turn for no reason.
+            const rawSelectors = Array.isArray(args.selectors)
+                ? args.selectors
+                : args.selectors != null
+                    ? [args.selectors]
+                    : args.selector != null
+                        ? [args.selector]
+                        : [];
+            if (rawSelectors.length === 0) {
+                throw new errors.SuperDocCliError('delete_blocks requires a non-empty "selectors" array, each entry resolving to one block (e.g. {kind:"nodeId",nodeId:"…"})', { code: 'INVALID_ARGUMENT' });
+            }
+            // EVERY entry has to parse. Dropping the unparseable ones would delete the
+            // rest and report success, so the model would never learn that part of its
+            // request went nowhere — the same false-success loop this action ends.
+            const selectors = [];
+            for (const [index, raw] of rawSelectors.entries()) {
+                const parsed = parseSelector(raw);
+                if (!parsed) {
+                    throw new errors.SuperDocCliError(`delete_blocks selectors[${index}] is not a valid selector (e.g. {kind:"nodeId",nodeId:"…"}); no blocks were deleted`, { code: 'INVALID_ARGUMENT' });
+                }
+                selectors.push(parsed);
+            }
+            return runDeleteBlocks(doc, { action, selectors, changeMode: parseChangeMode(args.changeMode) });
+        }
         case 'append_list': {
             const items = parseStringArray(args.items);
             if (!items || items.length === 0) {

package/dist/agent/actions.d.ts

@@ -20,7 +20,7 @@
 import type { BoundDocApi } from '../generated/client.js';
 import type { AgentReceipt } from './runtime.js';
 import type { AgentChangeMode, AgentSelector } from './ir.js';
-export type ActionName = 'insert_paragraphs' | 'insert_heading' | 'replace_text' | 'delete_text' | 'append_list' | 'create_table' | 'comment_paragraphs' | 'add_comments' | 'resolve_comments' | 'reply_to_comment' | 'rewrite_block' | 'accept_tracked_changes' | 'reject_tracked_changes' | 'normalize_body_font_size' | 'set_font_family' | 'apply_letter_spacing' | 'fill_placeholders' | 'move_range' | 'insert_toc' | 'insert_table_row' | 'insert_table_column' | 'delete_table_row' | 'delete_table_column' | 'split_table' | 'convert_list' | 'split_list' | 'undo_changes' | 'redo_changes' | 'attach_numbering' | 'add_list_items' | 'format_text' | 'apply_style' | 'format_paragraph' | 'move_text' | 'style_table' | 'move_table' | 'delete_table' | 'set_paragraph_spacing' | 'insert_page_break' | 'add_hyperlink';
+export type ActionName = 'insert_paragraphs' | 'insert_heading' | 'replace_text' | 'delete_text' | 'delete_blocks' | 'append_list' | 'create_table' | 'comment_paragraphs' | 'add_comments' | 'resolve_comments' | 'reply_to_comment' | 'rewrite_block' | 'accept_tracked_changes' | 'reject_tracked_changes' | 'normalize_body_font_size' | 'set_font_family' | 'apply_letter_spacing' | 'fill_placeholders' | 'move_range' | 'insert_toc' | 'insert_table_row' | 'insert_table_column' | 'delete_table_row' | 'delete_table_column' | 'split_table' | 'convert_list' | 'split_list' | 'undo_changes' | 'redo_changes' | 'attach_numbering' | 'add_list_items' | 'format_text' | 'apply_style' | 'format_paragraph' | 'move_text' | 'style_table' | 'move_table' | 'delete_table' | 'set_paragraph_spacing' | 'insert_page_break' | 'add_hyperlink';
 export type ActionPlacement = {
     at: 'document_end';
 } | {
@@ -32,7 +32,7 @@ export type ActionPlacement = {
     at: 'before';
     selector: AgentSelector;
 };
-export type ActionArgs = InsertParagraphsArgs | InsertHeadingArgs | ReplaceTextArgs | DeleteTextArgs | AppendListArgs | AddListItemsArgs | ConvertListArgs | AttachNumberingArgs | SplitListArgs | CreateTableArgs | CommentParagraphsArgs | AddCommentsArgs | ResolveCommentsArgs | ReplyToCommentArgs | RewriteBlockArgs | FormatTextArgs | FormatParagraphArgs | ApplyStyleArgs | MoveTextArgs | UndoChangesArgs | RedoChangesArgs | AcceptTrackedChangesArgs | RejectTrackedChangesArgs | NormalizeBodyFontSizeArgs | SetFontFamilyArgs | ApplyLetterSpacingArgs | FillPlaceholdersArgs | MoveRangeArgs | InsertTocArgs | StyleTableArgs | MoveTableArgs | DeleteTableArgs | SetParagraphSpacingArgs | InsertPageBreakArgs | AddHyperlinkArgs | InsertTableRowArgs | InsertTableColumnArgs | DeleteTableRowArgs | DeleteTableColumnArgs | SplitTableArgs;
+export type ActionArgs = InsertParagraphsArgs | InsertHeadingArgs | ReplaceTextArgs | DeleteTextArgs | DeleteBlocksArgs | AppendListArgs | AddListItemsArgs | ConvertListArgs | AttachNumberingArgs | SplitListArgs | CreateTableArgs | CommentParagraphsArgs | AddCommentsArgs | ResolveCommentsArgs | ReplyToCommentArgs | RewriteBlockArgs | FormatTextArgs | FormatParagraphArgs | ApplyStyleArgs | MoveTextArgs | UndoChangesArgs | RedoChangesArgs | AcceptTrackedChangesArgs | RejectTrackedChangesArgs | NormalizeBodyFontSizeArgs | SetFontFamilyArgs | ApplyLetterSpacingArgs | FillPlaceholdersArgs | MoveRangeArgs | InsertTocArgs | StyleTableArgs | MoveTableArgs | DeleteTableArgs | SetParagraphSpacingArgs | InsertPageBreakArgs | AddHyperlinkArgs | InsertTableRowArgs | InsertTableColumnArgs | DeleteTableRowArgs | DeleteTableColumnArgs | SplitTableArgs;
 export type InsertParagraphsArgs = {
     action: 'insert_paragraphs';
     texts?: readonly string[];
@@ -66,6 +66,12 @@ export type DeleteTextArgs = {
     caseSensitive?: boolean;
     changeMode?: AgentChangeMode;
 };
+export type DeleteBlocksArgs = {
+    action: 'delete_blocks';
+    /** One or more selectors, each resolving to exactly ONE body block. */
+    selectors: readonly AgentSelector[];
+    changeMode?: AgentChangeMode;
+};
 export type AppendListArgs = {
     action: 'append_list';
     items: readonly string[];

package/dist/agent/actions.js

@@ -8,6 +8,7 @@ const ACTION_NAMES = [
     'insert_heading',
     'replace_text',
     'delete_text',
+    'delete_blocks',
     'append_list',
     'create_table',
     'comment_paragraphs',
@@ -56,7 +57,8 @@ export const ACTION_HINTS = {
     insert_paragraphs: 'texts[] (or text for a single paragraph), placement?, headingLevel? (first item as heading 1-6), changeMode?',
     insert_heading: 'text, level, placement?, changeMode?',
     replace_text: 'edits[{find,replace}], optional selector to scope replacements to one inspected block, caseSensitive?, changeMode?',
-    delete_text: 'finds[], optional selector to scope deletions to ONE inspected block (required to delete stray whitespace — an unscoped whitespace find matches document-wide), caseSensitive?, changeMode?',
+    delete_text: "finds[], optional selector to scope deletions to ONE inspected block (required to delete stray whitespace — an unscoped whitespace find matches document-wide), caseSensitive?, changeMode? — deletes TEXT ONLY, leaving the block (and a list item's bullet/number) in place. To remove a whole list item, paragraph or heading use delete_blocks",
+    delete_blocks: 'selectors[] (each resolving to ONE inspected block: list item, paragraph or heading), changeMode? — THE way to DELETE a whole LIST ITEM, paragraph or heading, bullet/number included. Use for "remove the first item under Article II" / "delete that clause". delete_text only strikes the text and leaves an empty numbered item behind. Deletes several blocks in ONE call; use delete_table for a whole table and delete_text to clear a table cell (a cell must keep a paragraph)',
     append_list: 'items[], kind?: ordered|bullet, headingText?, headingLevel?, placement? {at:"after"|"before",selector} builds the list at that block instead of document end',
     create_table: 'rows, columns, cellTexts?, placement?, changeMode? — changeMode:"tracked" makes the table insertion itself a tracked change',
     rewrite_block: 'selector, text, changeMode?',
@@ -103,6 +105,7 @@ export const ACTION_GROUPS = [
             'insert_heading',
             'replace_text',
             'delete_text',
+            'delete_blocks',
             'append_list',
             'create_table',
             'rewrite_block',
@@ -164,6 +167,7 @@ export const ACTION_ARGS = {
     insert_heading: ['text', 'level', 'placement', 'changeMode'],
     replace_text: ['edits', 'selector', 'caseSensitive', 'changeMode'],
     delete_text: ['finds', 'selector', 'caseSensitive', 'changeMode'],
+    delete_blocks: ['selectors', 'selector', 'changeMode'],
     append_list: ['items', 'kind', 'headingText', 'headingLevel', 'placement', 'changeMode'],
     create_table: ['rows', 'columns', 'cellTexts', 'placement', 'changeMode'],
     comment_paragraphs: ['commentText', 'scope', 'excludeBlockQuotes'],
@@ -1222,6 +1226,157 @@ async function runDeleteText(doc, args) {
         return failedReceipt('delete_text', err, pre);
     }
 }
+/** Block node types `doc.blocks.delete` removes as a whole paragraph-shaped block. */
+const DELETABLE_BLOCK_NODE_TYPES = new Set(['paragraph', 'heading', 'listItem']);
+/**
+ * delete_blocks — remove ENTIRE blocks (list items, paragraphs, headings) in
+ * ONE call. Wraps doc.blocks.delete, which removes the block NODE, its
+ * paragraph properties (`w:pPr`, including a list item's `w:numPr`) included.
+ *
+ * delete_text only strikes the RUNS. Routing "delete this list item"
+ * through it leaves the numbered paragraph behind, so accepting the tracked
+ * change yields an empty `1.` and the following items never renumber. Whole-
+ * block removal has to go through blocks.delete, and in tracked mode that
+ * records ONE structural revision whose acceptance removes the paragraph and
+ * whose rejection restores it intact.
+ */
+async function runDeleteBlocks(doc, args) {
+    const domains = new Set(['blocks', 'trackedChanges']);
+    for (const selector of args.selectors) {
+        for (const domain of snapshotDomainsForSelector(selector))
+            domains.add(domain);
+    }
+    const pre = await buildDocumentSnapshot(doc, { includeDomains: [...domains] });
+    try {
+        if (args.selectors.length === 0) {
+            return failedReceipt('delete_blocks', new Error('selectors must be non-empty'), pre);
+        }
+        const deleteFn = maybeMethod(doc, ['blocks', 'delete']);
+        if (!deleteFn) {
+            throw new SuperDocCliError('doc.blocks.delete is not available on the document handle.', {
+                code: 'TOOL_DISPATCH_NOT_FOUND',
+            });
+        }
+        // Resolve EVERY selector against the same pre-snapshot before deleting
+        // anything. nodeIds are stable paragraph ids, so a target resolved up front
+        // stays addressable after a sibling is removed — whereas an ordinal or
+        // text-search selector re-resolved mid-run would drift onto the wrong block.
+        const targets = [];
+        const unresolved = [];
+        const wrongShape = [];
+        const seen = new Set();
+        for (const selector of args.selectors) {
+            // A tableCell selector resolves to the FIRST PARAGRAPH inside the cell,
+            // so it would otherwise pass the paragraph-shape gate below. Removing it
+            // is not a whole-block delete: a `<w:tc>` must keep at least one
+            // paragraph, so deleting the only one leaves invalid OOXML, and in
+            // tracked mode the compiler can only strike the runs anyway. Refuse the
+            // shape rather than half-honour it.
+            if (selector.kind === 'tableCell') {
+                wrongShape.push({ selector, nodeType: 'tableCell' });
+                continue;
+            }
+            const target = selectorToBlockTarget(selector, pre);
+            if (!target) {
+                unresolved.push(selector);
+                continue;
+            }
+            if (!DELETABLE_BLOCK_NODE_TYPES.has(target.nodeType)) {
+                wrongShape.push({ selector, nodeType: target.nodeType });
+                continue;
+            }
+            if (seen.has(target.nodeId))
+                continue;
+            seen.add(target.nodeId);
+            targets.push({ selector, nodeId: target.nodeId, nodeType: target.nodeType });
+        }
+        const errors = [];
+        for (const selector of unresolved) {
+            errors.push({
+                code: 'ACTION_FAILED',
+                message: `selector did not resolve to a unique body block: ${JSON.stringify(selector)}`,
+                recovery: { kind: 'reinspect' },
+            });
+        }
+        for (const entry of wrongShape) {
+            errors.push({
+                code: 'INVALID_ARGUMENT',
+                message: `delete_blocks removes paragraph-shaped blocks (list items, paragraphs, headings); ` +
+                    `${JSON.stringify(entry.selector)} resolved to a "${entry.nodeType}"` +
+                    (entry.nodeType === 'table'
+                        ? ' — use delete_table for a whole table.'
+                        : entry.nodeType === 'tableCell'
+                            ? ' — a cell must keep a paragraph; use delete_text to clear it, or delete_table_row/delete_table_column.'
+                            : '.'),
+                recovery: { kind: 'reinspect' },
+            });
+        }
+        if (targets.length === 0) {
+            return {
+                status: 'failed',
+                intent: 'delete_blocks',
+                preSnapshot: { revision: pre.revision, counts: pre.counts },
+                selectedTargets: [],
+                executedOperations: [],
+                verification: [],
+                errors,
+            };
+        }
+        const changeMode = parseChangeMode(args.changeMode);
+        const executedOperations = [];
+        const deleted = [];
+        for (const target of targets) {
+            try {
+                const result = await deleteFn({ target: { kind: 'block', nodeType: target.nodeType, nodeId: target.nodeId } }, changeMode ? { changeMode } : undefined);
+                executedOperations.push({ operationId: 'doc.blocks.delete', result: compactOpResult(result) });
+                deleted.push({ nodeId: target.nodeId, nodeType: target.nodeType });
+            }
+            catch (err) {
+                errors.push({
+                    code: 'ACTION_FAILED',
+                    message: `blocks.delete failed for ${target.nodeType} ${target.nodeId}: ${err instanceof Error ? err.message : String(err)}`,
+                    recovery: { kind: 'reinspect' },
+                });
+            }
+        }
+        const post = await buildDocumentSnapshot(doc, { includeDomains: [...domains] });
+        // Tracked deletions leave the block in place until the revision is decided,
+        // so the block count cannot move — count the structural revisions instead.
+        // Direct deletions must show one fewer block of each deleted node type.
+        const checks = changeMode === 'tracked'
+            ? [{ kind: 'tracked-change-count-delta', delta: deleted.length }]
+            : [...new Set(deleted.map((entry) => entry.nodeType))].map((nodeType) => ({
+                kind: 'block-count-delta',
+                nodeType,
+                delta: -deleted.filter((entry) => entry.nodeType === nodeType).length,
+            }));
+        const verification = evaluateChecks(pre, post, checks);
+        // Compare against the DEDUPED target list: two selectors naming the same
+        // block are one deletion, and counting the raw selectors would report a
+        // fully applied call as `partial` with no error to explain it. Selectors
+        // that never became a target (unresolved or wrong-shape) already recorded
+        // an error, so the `errors.length` term still catches a short request.
+        const allApplied = deleted.length === targets.length && errors.length === 0;
+        const verified = verification.every((v) => v.passed);
+        return {
+            status: !verified || deleted.length === 0 ? 'failed' : allApplied ? 'ok' : 'partial',
+            intent: `delete_blocks: ${deleted.length} block(s)`,
+            preSnapshot: { revision: pre.revision, counts: pre.counts },
+            postSnapshot: { revision: post.revision, counts: post.counts },
+            selectedTargets: targets.map((target) => ({ selector: target.selector, matched: [target.nodeId] })),
+            executedOperations,
+            verification,
+            deletedBlocks: deleted,
+            ...(errors.length ? { errors } : {}),
+            ...(errors.length
+                ? { nextStep: 'Re-inspect the document and retry the selectors that did not resolve to one block.' }
+                : {}),
+        };
+    }
+    catch (err) {
+        return failedReceipt('delete_blocks', err, pre);
+    }
+}
 async function runAppendList(doc, args) {
     const pre = await buildDocumentSnapshot(doc);
     try {
@@ -4689,6 +4844,33 @@ export async function superdocPerformAction(doc, args) {
                 changeMode: parseChangeMode(args.changeMode),
             });
         }
+        case 'delete_blocks': {
+            // Accept a single `selector` too: the model reaches for the singular form
+            // by analogy with delete_text/rewrite_block, and rejecting it would cost a
+            // turn for no reason.
+            const rawSelectors = Array.isArray(args.selectors)
+                ? args.selectors
+                : args.selectors != null
+                    ? [args.selectors]
+                    : args.selector != null
+                        ? [args.selector]
+                        : [];
+            if (rawSelectors.length === 0) {
+                throw new SuperDocCliError('delete_blocks requires a non-empty "selectors" array, each entry resolving to one block (e.g. {kind:"nodeId",nodeId:"…"})', { code: 'INVALID_ARGUMENT' });
+            }
+            // EVERY entry has to parse. Dropping the unparseable ones would delete the
+            // rest and report success, so the model would never learn that part of its
+            // request went nowhere — the same false-success loop this action ends.
+            const selectors = [];
+            for (const [index, raw] of rawSelectors.entries()) {
+                const parsed = parseSelector(raw);
+                if (!parsed) {
+                    throw new SuperDocCliError(`delete_blocks selectors[${index}] is not a valid selector (e.g. {kind:"nodeId",nodeId:"…"}); no blocks were deleted`, { code: 'INVALID_ARGUMENT' });
+                }
+                selectors.push(parsed);
+            }
+            return runDeleteBlocks(doc, { action, selectors, changeMode: parseChangeMode(args.changeMode) });
+        }
         case 'append_list': {
             const items = parseStringArray(args.items);
             if (!items || items.length === 0) {