@superdoc/sdk 2.10.0-next.6 → 2.10.0-next.8

package/dist/agent/actions.js

@@ -1,3 +1,4 @@
+import { ExecutionContext, evaluateFactChecks } from './execution-context.js';
 import { SuperDocCliError } from '../runtime/errors.js';
 import { runSuperdocListTransformWorkflow } from '../action-primitives/tools/list-transform.js';
 import { runSuperdocStructureInsertWorkflow } from '../action-primitives/tools/structure-insert.js';
@@ -167,18 +168,18 @@ export const ACTION_GROUPS = [
  * action at compile time.
  */
 export const ACTION_ARGS = {
-    insert_paragraphs: ['text', 'texts', 'headingLevel', 'placement', 'changeMode'],
+    insert_paragraphs: ['text', 'texts', 'headingLevel', 'placement', 'changeMode', 'evidence'],
     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'],
+    create_table: ['rows', 'columns', 'cellTexts', 'placement', 'changeMode', 'evidence'],
     comment_paragraphs: ['commentText', 'scope', 'excludeBlockQuotes'],
     add_comments: ['commentText', 'selector', 'selectors'],
     resolve_comments: ['anchorText', 'reopen'],
     reply_to_comment: ['commentText', 'anchorText', 'commentId'],
-    rewrite_block: ['text', 'selector', 'changeMode'],
+    rewrite_block: ['text', 'selector', 'changeMode', 'evidence'],
     accept_tracked_changes: ['author', 'changeType'],
     reject_tracked_changes: ['author', 'changeType'],
     normalize_body_font_size: ['fontSize', 'changeMode'],
@@ -213,7 +214,7 @@ export const ACTION_ARGS = {
         'changeMode',
     ],
     apply_style: ['selector', 'styleId', 'headingLevel', 'likeText'],
-    format_paragraph: ['selector', 'alignment', 'changeMode'],
+    format_paragraph: ['selector', 'alignment', 'changeMode', 'evidence'],
     move_text: ['text', 'afterText', 'changeMode'],
     style_table: ['tableOrdinal', 'accentColor'],
     move_table: ['tableOrdinal', 'placement'],
@@ -316,10 +317,6 @@ function findSnapshotTextByNodeId(snapshot, nodeId) {
     }
     return null;
 }
-function lastBlock(snapshot) {
-    const block = snapshot.blocks[snapshot.blocks.length - 1];
-    return block ? { nodeId: block.nodeId, nodeType: block.nodeType } : null;
-}
 function createdBlockTarget(result) {
     const rec = asRecord(result);
     const paragraph = asRecord(rec?.paragraph);
@@ -857,7 +854,7 @@ forceDirectFill = false) {
         });
     }
     const extracted = asRecord(await extractFn({}));
-    const blocks = (Array.isArray(extracted?.blocks) ? extracted?.blocks : [])
+    const blocks = (Array.isArray(extracted?.blocks) ? extracted.blocks : [])
         .map((block) => asRecord(block))
         .filter((block) => block != null)
         .flatMap((block) => {
@@ -1046,95 +1043,68 @@ async function styleTableCells(doc, cells, changeMode) {
     await applyItemStyling(doc, nodeIds, specs, changeMode);
     return styled.length;
 }
-async function runInsertParagraphs(doc, args) {
-    const pre = args.placement?.at === 'before' || args.placement?.at === 'after'
-        ? await buildMutationSnapshot(doc, { includeDomains: ['blocks'] })
-        : await buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
+async function runInsertParagraphs(doc, args, formatArgs) {
+    const context = new ExecutionContext(doc, { evidence: args.evidence, selectors: placementSelectors(args.placement) });
     try {
-        // `texts` is the canonical input; a single `text` is normalized to one item
-        // upstream in the dispatcher, but tolerate it here too.
-        const texts = args.texts ?? (args.text ? [args.text] : []);
-        const placement = resolvePlacement(args.placement, pre);
-        const executedOperations = [];
-        // Blank-line spacing between drafted paragraphs is only desirable when
-        // creating a NEW document (a blank doc has ~one empty block). Inserting into
-        // an existing doc must NOT scatter blank paragraphs through it.
-        const isNewDocument = (pre.counts?.blocks ?? 0) <= 1;
-        // For the first item: respect the requested placement and headingLevel.
-        // For subsequent items: append after the previously inserted block by
-        // using `documentEnd` (the SDK keeps blocks contiguous) so order is
-        // preserved.
+        const pre = await context.start();
+        const placement = await resolveFactPlacement(args.placement, pre);
+        const isNewDocument = (await pre.count()) <= 1;
+        const anchor = placement.kind === 'before' || placement.kind === 'after'
+            ? await pre.block(placement.target.nodeId)
+            : await pre.target({
+                kind: 'placement',
+                at: placement.kind === 'documentStart' ? 'document_start' : 'document_end',
+            });
+        const preRows = pre.complete ? await listBlockRows(doc) : anchor ? [anchor] : [];
         let currentPlacement = placement;
-        let headingFirst = false;
-        if (typeof args.headingLevel === 'number' && args.headingLevel >= 1 && args.headingLevel <= 6) {
-            headingFirst = true;
-        }
-        // Advance the insertion point to sit right after the block just created
-        // (prefer the receipt's created id; fall back to the document's last block).
-        const advanceAfter = async (result) => {
-            const created = createdBlockTarget(result);
-            if (created) {
-                return { kind: 'after', target: { kind: 'block', nodeType: created.nodeType, nodeId: created.nodeId } };
+        const nodeIds = [];
+        const specs = [];
+        const advance = async (result) => {
+            const target = createdBlockTarget(result);
+            if (target) {
+                currentPlacement = {
+                    kind: 'after',
+                    target: { kind: 'block', nodeType: target.nodeType, nodeId: target.nodeId },
+                };
+                return target.nodeId;
             }
-            const mid = await buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
-            const last = lastBlock(mid);
-            return last
-                ? { kind: 'after', target: { kind: 'block', nodeType: last.nodeType, nodeId: last.nodeId } }
-                : { kind: 'documentEnd' };
+            const current = await context.finishRevision();
+            const last = await current.target({ kind: 'placement', at: 'document_end' });
+            if (!last)
+                throw new Error('Created paragraph identity is unavailable.');
+            currentPlacement = { kind: 'after', target: { kind: 'block', nodeType: last.nodeType, nodeId: last.nodeId } };
+            return last.nodeId;
         };
-        const styledNodeIds = [];
-        const styledSpecs = [];
-        for (let i = 0; i < texts.length; i += 1) {
-            const text = texts[i];
-            const isFirst = i === 0;
-            const result = isFirst && headingFirst
-                ? await executeCreateHeading(doc, text, args.headingLevel, currentPlacement, args.changeMode)
-                : await executeCreateParagraph(doc, text, currentPlacement, args.changeMode);
-            executedOperations.push({
-                operationId: isFirst && headingFirst ? 'doc.create.heading' : 'doc.create.paragraph',
-                result,
-            });
-            // Remember the created block for the post-insert styling pass when this
-            // paragraph carries a runs/marks spec.
-            const spec = args.textSpecs?.[i];
-            if (spec && ((spec.runs && spec.runs.length > 0) || spec.marks != null)) {
-                const created = createdBlockTarget(result);
-                if (created?.nodeId) {
-                    styledNodeIds.push(created.nodeId);
-                    styledSpecs.push({ ...spec, text });
-                }
-            }
-            currentPlacement = await advanceAfter(result);
-            // New-document drafts get a blank paragraph after each item for spacing;
-            // inserts into an existing document do not (would scatter blank lines).
-            if (isNewDocument) {
-                const spacer = await executeCreateParagraph(doc, '', currentPlacement, args.changeMode);
-                executedOperations.push({ operationId: 'doc.create.paragraph', result: spacer, rationale: 'spacing' });
-                currentPlacement = await advanceAfter(spacer);
+        const texts = args.texts ?? (args.text ? [args.text] : []);
+        for (let i = 0; i < texts.length; i++) {
+            const result = i === 0 && args.headingLevel
+                ? await executeCreateHeading(context.document, texts[i], args.headingLevel, currentPlacement, args.changeMode)
+                : await executeCreateParagraph(context.document, texts[i], currentPlacement, args.changeMode);
+            const id = await advance(result);
+            nodeIds.push(id);
+            specs.push({ ...args.textSpecs?.[i], text: texts[i] });
+            if (isNewDocument)
+                await advance(await executeCreateParagraph(context.document, '', currentPlacement, args.changeMode));
+        }
+        if (specs.some((spec) => spec.runs?.length || spec.marks))
+            await applyItemStyling(context.document, nodeIds, specs, args.changeMode);
+        let post = await context.finishRevision();
+        let formatted;
+        if (formatArgs) {
+            let localRows;
+            if (!pre.complete) {
+                const created = await post.page({ nodeIds, limit: Math.max(nodeIds.length, 1) });
+                localRows = [...(anchor ? [anchor] : []), ...created].sort((a, b) => a.ordinal - b.ordinal);
             }
+            const count = context.executedOperations.length;
+            formatted = await matchInsertedBlockFormatting(context.document, preRows, context.receipt('insert_paragraphs', []), formatArgs, localRows);
+            if (context.executedOperations.length !== count)
+                post = await context.finishRevision();
         }
-        if (styledNodeIds.length > 0) {
-            const styling = await applyItemStyling(doc, styledNodeIds, styledSpecs, args.changeMode);
-            executedOperations.push({
-                operationId: 'doc.format.apply',
-                result: styling,
-                rationale: `Styled ${styledNodeIds.length} inserted paragraph(s)`,
-            });
-        }
-        const postIdentity = await readDocumentIdentity(doc);
-        const verification = [revisionVerification(pre.revision, postIdentity.revision, true)];
-        return {
-            status: verification.every((v) => v.passed) ? 'ok' : 'failed',
-            intent: 'insert_paragraphs',
-            preSnapshot: { revision: pre.revision, counts: pre.counts },
-            postSnapshot: postIdentity,
-            selectedTargets: [],
-            executedOperations,
-            verification,
-        };
+        return context.receipt('insert_paragraphs', await evaluateFactChecks(pre, post, [{ kind: 'revision-changed' }]), formatted?.contextualFormatting ? { contextualFormatting: formatted.contextualFormatting } : {});
     }
-    catch (err) {
-        return failedReceipt('insert_paragraphs', err, pre);
+    catch (error) {
+        return context.failure('insert_paragraphs', error);
     }
 }
 async function runInsertHeading(doc, args) {
@@ -2251,52 +2221,75 @@ async function runSplitList(doc, args) {
         return failedReceipt('split_list', err, pre);
     }
 }
+async function resolveFactPlacement(placement, facts) {
+    if (!placement || placement.at === 'document_end')
+        return { kind: 'documentEnd' };
+    if (placement.at === 'document_start')
+        return { kind: 'documentStart' };
+    const target = await facts.target(placement.selector);
+    if (!target)
+        throw new SuperDocCliError('placement selector did not resolve to a unique body block', {
+            code: 'INVALID_ARGUMENT',
+        });
+    return { kind: placement.at, target: { kind: 'block', nodeType: target.nodeType, nodeId: target.nodeId } };
+}
+function placementSelectors(placement) {
+    return placement?.at === 'before' || placement?.at === 'after' ? [placement.selector] : [];
+}
 async function runCreateTable(doc, args) {
-    const pre = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
+    const checks = [
+        { kind: 'revision-changed' },
+        { kind: 'block-count-delta', nodeType: 'table', delta: 1 },
+    ];
+    const context = new ExecutionContext(doc, {
+        evidence: args.evidence,
+        selectors: placementSelectors(args.placement),
+        checks,
+    });
     try {
-        if (!Number.isInteger(args.rows) || args.rows < 1 || !Number.isInteger(args.columns) || args.columns < 1) {
-            return failedReceipt('create_table', new Error('rows and columns must be positive integers'), pre);
-        }
-        const placement = resolvePlacement(args.placement, pre);
-        const insertedTableOrdinal = estimateInsertedTableOrdinal(pre, placement);
-        const result = await executeCreateTable(doc, args, placement);
-        const executedOperations = [
-            { operationId: 'doc.create.table', result },
-        ];
-        const createdTableNodeId = asString(asRecord(asRecord(result)?.table)?.nodeId);
-        if (createdTableNodeId && args.cellTexts) {
-            const appliedCells = await applyTableCellTexts(doc, createdTableNodeId, insertedTableOrdinal, flattenCellTexts(args.cellTexts), args.changeMode);
-            if (appliedCells.length > 0) {
-                executedOperations.push({
-                    operationId: 'doc.mutations.apply',
-                    rationale: `Populated ${appliedCells.length} table cells.`,
-                });
+        if (!Number.isInteger(args.rows) || args.rows < 1 || !Number.isInteger(args.columns) || args.columns < 1)
+            throw new Error('rows and columns must be positive integers');
+        const pre = await context.start();
+        const placement = await resolveFactPlacement(args.placement, pre);
+        const result = await executeCreateTable(context.document, args, placement);
+        const tableNodeId = asString(asRecord(asRecord(result)?.table)?.nodeId);
+        if (args.cellTexts && tableNodeId) {
+            const cells = flattenCellTexts(args.cellTexts).filter((cell) => cell.text.trim());
+            if (pre.complete) {
+                const applied = await applyTableCellTexts(context.document, tableNodeId, estimateInsertedTableOrdinal(pre.complete, placement), cells, args.changeMode);
+                await styleTableCells(context.document, applied, args.changeMode);
             }
-            const styledCount = await styleTableCells(doc, appliedCells, args.changeMode);
-            if (styledCount > 0) {
-                executedOperations.push({
-                    operationId: 'doc.format.apply',
-                    rationale: `Styled ${styledCount} table cell(s).`,
-                });
+            else {
+                for (const cell of cells)
+                    await context.document.tables.setCellText({
+                        target: { kind: 'block', nodeType: 'table', nodeId: tableNodeId },
+                        rowIndex: cell.rowIndex,
+                        columnIndex: cell.columnIndex,
+                        text: cell.text,
+                        changeMode: args.changeMode,
+                    });
+                const styled = cells.filter((cell) => cell.runs?.length || cell.marks);
+                if (styled.length) {
+                    const identities = await doc.tables.getCells({ nodeId: tableNodeId });
+                    const resolved = styled.map((cell) => {
+                        const identity = identities.cells.find((item) => item.rowIndex === cell.rowIndex &&
+                            item.columnIndex <= cell.columnIndex &&
+                            item.columnIndex + item.colspan > cell.columnIndex);
+                        if (!identity?.firstParagraphNodeId)
+                            throw new Error('Required cell paragraph identity is unavailable.');
+                        return { ...cell, nodeId: identity.firstParagraphNodeId };
+                    });
+                    const styling = await applyItemStyling(context.document, resolved.map((cell) => cell.nodeId), resolved, args.changeMode);
+                    if (styling.skipped)
+                        throw new Error(`Requested cell styling failed: ${styling.skipped}`);
+                }
             }
         }
-        const post = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
-        const verification = evaluateChecks(pre, post, [
-            { kind: 'revision-changed' },
-            { kind: 'block-count-delta', nodeType: 'table', delta: 1 },
-        ]);
-        return {
-            status: verification.every((v) => v.passed) ? 'ok' : 'failed',
-            intent: 'create_table',
-            preSnapshot: { revision: pre.revision, counts: pre.counts },
-            postSnapshot: { revision: post.revision, counts: post.counts },
-            selectedTargets: [],
-            executedOperations,
-            verification,
-        };
+        const post = await context.finish();
+        return context.receipt('create_table', await evaluateFactChecks(pre, post, checks));
     }
-    catch (err) {
-        return failedReceipt('create_table', err, pre);
+    catch (error) {
+        return context.failure('create_table', error);
     }
 }
 async function runCommentParagraphs(doc, args) {
@@ -2579,67 +2572,39 @@ async function runReplyToComment(doc, args) {
     }
 }
 async function runRewriteBlock(doc, args) {
-    const pre = await buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
+    const context = new ExecutionContext(doc, { evidence: args.evidence, selectors: [args.selector] });
     try {
-        const target = selectorToBlockTarget(args.selector, pre);
-        if (!target) {
-            return failedReceipt('rewrite_block', new Error('selector did not resolve to a body block'), pre);
-        }
-        const normalizedText = normalizeTitleLikeRewriteText(target.text, args.text);
-        // The engine rewrites the whole block as ONE uniform run — losing an
-        // intra-paragraph pattern (bold "(n)" lead-in), or smearing the first
-        // run's marks across the entire text. Capture the current run layout so
-        // it can be re-applied over the unchanged prefix/suffix afterward.
-        const preRuns = await captureBlockRuns(doc, target.nodeId, target.text);
-        const steps = [
+        const pre = await context.start();
+        const target = await pre.target(args.selector);
+        if (!target)
+            throw new Error('selector did not resolve to a body block');
+        context.selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
+        const text = normalizeTitleLikeRewriteText(target.text, args.text);
+        const runs = await captureBlockRuns(doc, target.nodeId, target.text);
+        await executeMutations(context.document, [
             {
                 id: 'rewrite-block-1',
                 op: 'text.rewrite',
                 where: { by: 'block', nodeType: target.nodeType, nodeId: target.nodeId },
-                args: {
-                    replacement: { text: normalizedText },
-                    style: preserveRewriteStyle(),
-                },
+                args: { replacement: { text }, style: preserveRewriteStyle() },
             },
-        ];
-        const result = await executeMutations(doc, steps, args.changeMode, pre.revision);
-        const preservation = await preserveRunPatternAfterRewrite(doc, target.nodeId, target.text, preRuns, normalizedText);
-        const post = await buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
-        const rewrittenBlock = findSnapshotTextByNodeId(post, target.nodeId);
+        ], args.changeMode, pre.revision);
+        await preserveRunPatternAfterRewrite(context.document, target.nodeId, target.text, runs, text);
+        const post = await context.finish();
+        const rewritten = await post.block(target.nodeId);
         const verification = [
             revisionVerification(pre.revision, post.revision, true),
             {
-                check: { kind: 'block-text-contains', nodeId: target.nodeId, text: normalizedText },
-                passed: !!rewrittenBlock && verifyRewrittenBlockText(rewrittenBlock.text, normalizedText, args.changeMode),
+                check: { kind: 'block-text-contains', nodeId: target.nodeId, text },
+                passed: !!rewritten && verifyRewrittenBlockText(rewritten.text, text, args.changeMode),
             },
         ];
-        const changed = pre.revision !== post.revision;
-        const rewritten = !!rewrittenBlock && verifyRewrittenBlockText(rewrittenBlock.text, args.text, args.changeMode);
-        return {
-            status: changed && rewritten ? 'ok' : 'failed',
-            intent: 'rewrite_block',
-            preSnapshot: { revision: pre.revision, counts: pre.counts },
-            postSnapshot: { revision: post.revision, counts: post.counts },
-            selectedTargets: [{ selector: args.selector, matched: [target.nodeId] }],
-            executedOperations: [
-                { operationId: 'doc.mutations.apply', result },
-                ...(preservation ? [{ operationId: 'doc.format.apply', result: preservation }] : []),
-            ],
-            verification,
-            errors: changed && rewritten
-                ? undefined
-                : [
-                    {
-                        code: 'ACTION_FAILED',
-                        message: changed
-                            ? 'rewrite_block did not produce the requested rewritten text for the selected block'
-                            : 'rewrite_block produced no change for the selected block; keep the same target and provide a changed rewrite',
-                    },
-                ],
-        };
+        return context.receipt('rewrite_block', verification, verification.every((check) => check.passed)
+            ? {}
+            : { errors: [{ code: 'ACTION_FAILED', message: 'rewrite_block did not produce the requested changed text' }] });
     }
-    catch (err) {
-        return failedReceipt('rewrite_block', err, pre);
+    catch (error) {
+        return context.failure('rewrite_block', error);
     }
 }
 const RUN_BOOL_MARKS = ['bold', 'italic', 'underline', 'strike'];
@@ -3290,43 +3255,30 @@ async function runApplyStyle(doc, args) {
  * escape to superdoc_execute_code and apply the alignment untracked (no pPrChange).
  */
 async function runFormatParagraph(doc, args) {
-    const pre = await buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
+    const context = new ExecutionContext(doc, { evidence: args.evidence, selectors: [args.selector] });
     try {
-        const target = selectorToBlockTarget(args.selector, pre);
-        if (!target) {
-            return failedReceipt('format_paragraph', new Error('selector did not resolve to a unique body block'), pre);
-        }
         const alignment = typeof args.alignment === 'string' ? args.alignment.trim().toLowerCase() : '';
-        const normalizedAlignment = alignment === 'both' ? 'justify' : alignment;
-        if (!['left', 'center', 'right', 'justify'].includes(normalizedAlignment)) {
-            return failedReceipt('format_paragraph', new Error('format_paragraph requires alignment: left | center | right | justify'), pre);
-        }
-        const steps = [
+        const normalized = alignment === 'both' ? 'justify' : alignment;
+        if (!['left', 'center', 'right', 'justify'].includes(normalized))
+            throw new Error('format_paragraph requires alignment: left | center | right | justify');
+        const pre = await context.start();
+        const target = await pre.target(args.selector);
+        if (!target)
+            throw new Error('selector did not resolve to a unique body block');
+        context.selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
+        await executeMutations(context.document, [
             {
                 id: 'format-paragraph-1',
                 op: 'format.apply',
                 where: { by: 'block', nodeType: target.nodeType, nodeId: target.nodeId },
-                args: { alignment: normalizedAlignment, scope: 'block' },
+                args: { alignment: normalized, scope: 'block' },
             },
-        ];
-        const result = await executeMutations(doc, steps, args.changeMode, pre.revision);
-        const post = await buildDocumentSnapshot(doc);
-        const verification = evaluateChecks(pre, post, [{ kind: 'revision-changed' }]);
-        return {
-            status: verification.every((v) => v.passed) ? 'ok' : 'failed',
-            intent: `format_paragraph: ${normalizedAlignment}`,
-            preSnapshot: { revision: pre.revision, counts: pre.counts },
-            postSnapshot: { revision: post.revision, counts: post.counts },
-            selectedTargets: [{ selector: args.selector, matched: [target.nodeId] }],
-            applied: { alignment: normalizedAlignment },
-            executedOperations: [
-                { operationId: 'doc.mutations.apply', result: compactOpResult(result), rationale: `align ${target.nodeId}` },
-            ],
-            verification,
-        };
+        ], args.changeMode, pre.revision);
+        const post = await context.finish();
+        return context.receipt(`format_paragraph: ${normalized}`, await evaluateFactChecks(pre, post, [{ kind: 'revision-changed' }]), { applied: { alignment: normalized } });
     }
-    catch (err) {
-        return failedReceipt('format_paragraph', err, pre);
+    catch (error) {
+        return context.failure('format_paragraph', error);
     }
 }
 /**
@@ -5982,8 +5934,9 @@ async function matchOneBlock(doc, postBlocks, preIds, created, createdIndex, anc
             const formatApplyFn = maybeMethod(doc, ['format', 'apply']);
             if (formatApplyFn) {
                 const textLength = (created.textPreview ?? '').length;
-                const post = await buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
-                const full = post.blocks.find((b) => b.nodeId === created.nodeId)?.text ?? '';
+                const full = createdText ||
+                    (await doc.blocks.list({ nodeIds: [created.nodeId], limit: 1, includeText: true })).blocks.find((block) => block.nodeId === created.nodeId)?.text ||
+                    '';
                 await formatApplyFn({
                     blockId: created.nodeId,
                     start: 0,
@@ -6180,11 +6133,11 @@ async function matchBlockRunPattern(doc, reference, created, createdText) {
     }
     return Object.keys(applied).length > 0 ? { matchedSibling: reference.nodeId, ...applied } : null;
 }
-async function matchInsertedBlockFormatting(doc, preBlocks, receipt, args) {
+async function matchInsertedBlockFormatting(doc, preBlocks, receipt, args, availableRows) {
     if (receipt.status !== 'ok')
         return receipt;
     try {
-        const postBlocks = await listBlockRows(doc);
+        const postBlocks = availableRows ?? (await listBlockRows(doc));
         const preIds = new Set(preBlocks.map((b) => b.nodeId));
         const createdRows = postBlocks
             .map((b, i) => ({ row: b, index: i }))
@@ -6475,9 +6428,9 @@ async function dispatchSuperdocPerformAction(doc, args) {
                 });
             }
             const headingLevel = asNumber(args.headingLevel);
-            const preRows = await listBlockRows(doc);
-            const receipt = await runInsertParagraphs(doc, {
+            return runInsertParagraphs(doc, {
                 action,
+                evidence: args.evidence,
                 texts,
                 textSpecs,
                 placement: parsePlacement(args.placement),
@@ -6485,8 +6438,7 @@ async function dispatchSuperdocPerformAction(doc, args) {
                 headingLevel: headingLevel != null && Number.isInteger(headingLevel) && headingLevel >= 1 && headingLevel <= 6
                     ? headingLevel
                     : undefined,
-            });
-            return matchInsertedBlockFormatting(doc, preRows, receipt, args);
+            }, args);
         }
         case 'insert_heading': {
             const text = asString(args.text);
@@ -6610,6 +6562,7 @@ async function dispatchSuperdocPerformAction(doc, args) {
             }
             return runCreateTable(doc, {
                 action,
+                evidence: args.evidence,
                 rows,
                 columns,
                 cellTexts: parseCellTexts(args.cellTexts),
@@ -6633,16 +6586,41 @@ async function dispatchSuperdocPerformAction(doc, args) {
         }
         case 'add_comments': {
             const commentText = asString(args.commentText);
-            const selector = parseSelector(args.selector);
-            const selectors = Array.isArray(args.selectors)
-                ? args.selectors.map((s) => parseSelector(s)).filter((s) => Boolean(s))
-                : undefined;
-            if (!commentText || (!selector && !(selectors && selectors.length))) {
+            if (!commentText) {
                 throw new SuperDocCliError('add_comments requires "commentText" and a "selector" or non-empty "selectors" array', {
                     code: 'INVALID_ARGUMENT',
                 });
             }
-            return runAddComments(doc, { action, commentText, selector: selector ?? undefined, selectors });
+            const hasSelector = args.selector != null;
+            const hasSelectors = args.selectors != null;
+            if (hasSelector && hasSelectors) {
+                throw new SuperDocCliError('add_comments requires either "selector" or "selectors", not both', {
+                    code: 'INVALID_ARGUMENT',
+                });
+            }
+            if (hasSelectors) {
+                if (!Array.isArray(args.selectors) || args.selectors.length === 0) {
+                    throw new SuperDocCliError('add_comments requires "selectors" to be a non-empty array', {
+                        code: 'INVALID_ARGUMENT',
+                    });
+                }
+                // Parse the complete batch before mutation. Filtering an invalid entry
+                // would make the receipt report success for only part of the request.
+                const selectors = [];
+                for (const [index, raw] of args.selectors.entries()) {
+                    const parsed = parseSelector(raw);
+                    if (!parsed) {
+                        throw new SuperDocCliError(`add_comments selectors[${index}] is not a valid selector; no comments were added`, { code: 'INVALID_ARGUMENT' });
+                    }
+                    selectors.push(parsed);
+                }
+                return runAddComments(doc, { action, commentText, selectors });
+            }
+            const selector = parseSelector(args.selector);
+            if (!selector) {
+                throw new SuperDocCliError('add_comments requires "selector" to be valid or "selectors" to be a non-empty array', { code: 'INVALID_ARGUMENT' });
+            }
+            return runAddComments(doc, { action, commentText, selector });
         }
         case 'resolve_comments':
             return runResolveComments(doc, {
@@ -6671,6 +6649,7 @@ async function dispatchSuperdocPerformAction(doc, args) {
             }
             return runRewriteBlock(doc, {
                 action,
+                evidence: args.evidence,
                 text,
                 selector,
                 changeMode: parseChangeMode(args.changeMode),
@@ -6924,6 +6903,7 @@ async function dispatchSuperdocPerformAction(doc, args) {
             }
             return runFormatParagraph(doc, {
                 action,
+                evidence: args.evidence,
                 selector,
                 alignment: asString(args.alignment) ?? '',
                 changeMode: parseChangeMode(args.changeMode),

package/dist/agent/catalog.cjs

@@ -146,6 +146,11 @@ const ACTION_ARG_SCHEMA = {
     },
     finds: { type: 'array', items: { type: 'string' } },
     caseSensitive: { type: 'boolean' },
+    evidence: {
+        type: 'string',
+        enum: ['required', 'full'],
+        description: 'Required evidence by default; full includes complete count summaries.',
+    },
     changeMode: { type: 'string', enum: ['direct', 'tracked'] },
     placement: { type: 'object', additionalProperties: true, properties: {} },
     selector: SELECTOR_SCHEMA,
@@ -390,6 +395,11 @@ const AGENT_TOOL_DEFINITIONS = [
             additionalProperties: false,
             required: ['plan'],
             properties: {
+                evidence: {
+                    type: 'string',
+                    enum: ['required', 'full'],
+                    description: 'Required evidence by default; full includes complete count summaries.',
+                },
                 plan: {
                     type: 'object',
                     additionalProperties: false,
@@ -428,6 +438,11 @@ const AGENT_TOOL_DEFINITIONS = [
             additionalProperties: false,
             required: ['checks'],
             properties: {
+                evidence: {
+                    type: 'string',
+                    enum: ['required', 'full'],
+                    description: 'Required evidence by default; full includes complete count summaries.',
+                },
                 checks: {
                     type: 'array',
                     minItems: 1,