@superdoc/sdk 2.12.0-next.1 → 2.12.0-next.11

package/README.md

@@ -96,3 +96,18 @@ automatically replay the write.
 ## License
 
 AGPL-3.0. Commercial licenses are available from [SuperDoc](https://www.superdoc.dev).
+
+## Inspecting textbox sections
+
+`superdoc_inspect` includes discovered text-bearing textbox stories in `textboxes` when
+block inspection is enabled. Each entry contains its explicit `story` locator,
+its story-local `total`, and normalized `blocks` with text, identities, and list
+markers. The top-level `blocks` array and its ordinals continue to refer to the
+body; textbox block ordinals belong to their containing story.
+
+The block offset, limit, text cap, and block filters also apply within each
+textbox. Count-only inspections and inspections excluding the blocks domain do
+not collect textbox text. Check `diagnostics` for incomplete story discovery or
+reads. To edit a discovered heading, use `query.match` with its story locator
+and pass the returned reference to `replace`; a textbox ordinal is not a body
+action selector.

package/dist/actions/define.cjs

@@ -556,7 +556,12 @@ function mergeIntoAgentAction(tools, actions) {
             }
         }
         const nextActionProp = { ...actionProp, enum: enumValues };
-        const nextSchema = { ...schema, properties: { ...properties, action: nextActionProp } };
+        const hasOpenCustomSchema = actions.some((action) => action.inputSchema.additionalProperties !== false);
+        const nextSchema = {
+            ...schema,
+            additionalProperties: hasOpenCustomSchema ? true : schema.additionalProperties,
+            properties: { ...properties, action: nextActionProp },
+        };
         const baseDescription = typeof schemaContainer.description === 'string' ? schemaContainer.description : '';
         const nextDescription = baseDescription + customActionsDescription(actions);
         const nextContainer = { ...schemaContainer, description: nextDescription, [schemaKey]: nextSchema };

package/dist/actions/define.js

@@ -553,7 +553,12 @@ function mergeIntoAgentAction(tools, actions) {
             }
         }
         const nextActionProp = { ...actionProp, enum: enumValues };
-        const nextSchema = { ...schema, properties: { ...properties, action: nextActionProp } };
+        const hasOpenCustomSchema = actions.some((action) => action.inputSchema.additionalProperties !== false);
+        const nextSchema = {
+            ...schema,
+            additionalProperties: hasOpenCustomSchema ? true : schema.additionalProperties,
+            properties: { ...properties, action: nextActionProp },
+        };
         const baseDescription = typeof schemaContainer.description === 'string' ? schemaContainer.description : '';
         const nextDescription = baseDescription + customActionsDescription(actions);
         const nextContainer = { ...schemaContainer, description: nextDescription, [schemaKey]: nextSchema };

package/dist/agent/actions.cjs

@@ -72,8 +72,8 @@ const ACTION_HINTS = {
     add_comments: 'commentText, selector (one block) OR selectors[] to comment MANY blocks in ONE call (same text) — use selectors[] for "comment every heading/section/clause"; NEVER emit multiple add_comments calls, batch the targets into selectors[]',
     resolve_comments: 'anchorText? (resolve only comments anchored on text containing this; omit to resolve ALL open comments), reopen? (true = reopen resolved comments instead) — THE way to resolve (or reopen) comments. Use for "resolve the comment(s)" / "mark comments resolved".',
     reply_to_comment: 'commentText (the reply body), anchorText (text the target comment is anchored on / mentions) OR commentId — THE way to REPLY to an existing comment thread. Use for "reply to the comment about X" / "respond to Reviewer\'s comment". Adds a threaded reply, not a new top-level comment.',
-    accept_tracked_changes: 'author?, changeType?: insert|delete|replacement|format — e.g. changeType:"format" accepts ONLY formatting revisions (bold/italic/color), leaving text edits pending',
-    reject_tracked_changes: 'author?, changeType?: insert|delete|replacement|format',
+    accept_tracked_changes: 'id? (string or string[]) OR author?/changeType?: insert|delete|replacement|format — a string[] decides that exact set atomically; e.g. changeType:"format" accepts ONLY formatting revisions (bold/italic/color), leaving text edits pending',
+    reject_tracked_changes: 'id? (string or string[]) OR author?/changeType?: insert|delete|replacement|format — a string[] decides that exact set atomically',
     normalize_body_font_size: 'fontSize, changeMode?',
     set_font_family: 'fontFamily (e.g. "Arial"), selector? (one block) OR targetText/targetTexts[] (occurrences) — omit both to set the WHOLE body font, caseSensitive?, changeMode? — THE way to change the typeface. Use for "change the font to X" / "set the heading font to Y".',
     format_text: "bold?/italic?/underline?/strike? booleans, highlight? color name, color?, fontSize?, applied to EVERY occurrence of targetText (or targetTexts[] for several phrases in one call, or a selector'd block), caseSensitive?, changeMode? — THE way to bold/italicize/underline/highlight text, tracked-safe",
@@ -183,8 +183,8 @@ const ACTION_ARGS = {
     resolve_comments: ['anchorText', 'reopen'],
     reply_to_comment: ['commentText', 'anchorText', 'commentId'],
     rewrite_block: ['text', 'selector', 'changeMode', 'evidence'],
-    accept_tracked_changes: ['author', 'changeType'],
-    reject_tracked_changes: ['author', 'changeType'],
+    accept_tracked_changes: ['id', 'author', 'changeType'],
+    reject_tracked_changes: ['id', 'author', 'changeType'],
     normalize_body_font_size: ['fontSize', 'changeMode'],
     set_font_family: ['fontFamily', 'selector', 'targetText', 'targetTexts', 'caseSensitive', 'changeMode'],
     apply_letter_spacing: ['selector', 'letterSpacing', 'changeMode'],
@@ -2872,17 +2872,28 @@ function normalizeTableColor(raw) {
     return normalized ? `#${normalized}` : null;
 }
 async function runAcceptTrackedChanges(doc, args) {
-    return runTrackedChangeDecision(doc, 'accept_tracked_changes', 'accept', args.author, args.changeType);
+    return runTrackedChangeDecision(doc, 'accept_tracked_changes', 'accept', Array.isArray(args.id) ? args.id : typeof args.id === 'string' ? [args.id] : undefined, args.author, args.changeType);
 }
 async function runRejectTrackedChanges(doc, args) {
-    return runTrackedChangeDecision(doc, 'reject_tracked_changes', 'reject', args.author, args.changeType);
+    return runTrackedChangeDecision(doc, 'reject_tracked_changes', 'reject', Array.isArray(args.id) ? args.id : typeof args.id === 'string' ? [args.id] : undefined, args.author, args.changeType);
 }
-async function runTrackedChangeDecision(doc, intentLabel, decision, author, changeType) {
+async function runTrackedChangeDecision(doc, intentLabel, decision, exactIds, author, changeType) {
     const pre = await docSnapshot.buildDocumentSnapshot(doc);
     try {
-        const listFn = maybeMethod(doc, ['trackChanges', 'list']);
         const decideFn = maybeMethod(doc, ['trackChanges', 'decide']);
-        if (!listFn || !decideFn) {
+        if (!decideFn) {
+            throw new errors.SuperDocCliError('doc.trackChanges.list / decide are not available on the document handle.', {
+                code: 'TOOL_DISPATCH_NOT_FOUND',
+            });
+        }
+        // AIDEV-NOTE: Exact `id` must go to decide({ kind: 'id'|'ids' }) once.
+        // Listing then filtering treats a stale id as an ok no-op, which looks
+        // like success and invites a follow-up with no selector (accept/reject all).
+        if (exactIds && exactIds.length > 0) {
+            return decideExactTrackedChanges(doc, intentLabel, decision, decideFn, exactIds, pre);
+        }
+        const listFn = maybeMethod(doc, ['trackChanges', 'list']);
+        if (!listFn) {
             throw new errors.SuperDocCliError('doc.trackChanges.list / decide are not available on the document handle.', {
                 code: 'TOOL_DISPATCH_NOT_FOUND',
             });
@@ -2963,6 +2974,53 @@ async function runTrackedChangeDecision(doc, intentLabel, decision, author, chan
         return failedReceipt(intentLabel, err, pre);
     }
 }
+function trackedChangeDecideFailure(result) {
+    const rec = asRecord(result);
+    if (!rec || rec.success !== false)
+        return null;
+    const failure = asRecord(rec.failure);
+    return {
+        code: asString(failure?.code, 'ACTION_FAILED') || 'ACTION_FAILED',
+        message: asString(failure?.message, 'tracked-change decision failed') || 'tracked-change decision failed',
+    };
+}
+async function decideExactTrackedChanges(doc, intentLabel, decision, decideFn, exactIds, pre) {
+    const target = exactIds.length === 1 ? { kind: 'id', id: exactIds[0] } : { kind: 'ids', ids: [...exactIds] };
+    const result = await decideFn({ decision, target });
+    const failure = trackedChangeDecideFailure(result);
+    const selectedTargets = exactIds.map((id) => ({
+        selector: { kind: 'entity', entityType: 'trackedChange', entityId: id },
+        matched: failure ? [] : [id],
+    }));
+    if (failure) {
+        return {
+            status: 'failed',
+            intent: intentLabel,
+            preSnapshot: { revision: pre.revision, counts: pre.counts },
+            selectedTargets,
+            executedOperations: [{ operationId: 'doc.trackChanges.decide', result }],
+            verification: [],
+            errors: [
+                {
+                    code: failure.code,
+                    message: failure.message,
+                    recovery: { kind: 'reinspect' },
+                },
+            ],
+        };
+    }
+    const post = await docSnapshot.buildDocumentSnapshot(doc);
+    const verification = evaluateChecks(pre, post, [{ kind: 'revision-changed' }]);
+    return {
+        status: verification.every((v) => v.passed) ? 'ok' : 'failed',
+        intent: intentLabel,
+        preSnapshot: { revision: pre.revision, counts: pre.counts },
+        postSnapshot: { revision: post.revision, counts: post.counts },
+        selectedTargets,
+        executedOperations: [{ operationId: 'doc.trackChanges.decide', result }],
+        verification,
+    };
+}
 async function listAllTrackedChanges(listFn) {
     const PAGE = 250;
     let offset = 0;
@@ -6660,13 +6718,11 @@ async function dispatchSuperdocPerformAction(doc, args) {
         }
         case 'accept_tracked_changes':
             return runAcceptTrackedChanges(doc, {
-                author: asString(args.author),
-                changeType: parseTrackedChangeKind(args.changeType),
+                ...parseTrackedChangeDecisionArgs(action, args),
             });
         case 'reject_tracked_changes':
             return runRejectTrackedChanges(doc, {
-                author: asString(args.author),
-                changeType: parseTrackedChangeKind(args.changeType),
+                ...parseTrackedChangeDecisionArgs(action, args),
             });
         case 'normalize_body_font_size': {
             const fontSize = asNumber(args.fontSize);
@@ -7036,6 +7092,62 @@ async function dispatchSuperdocPerformAction(doc, args) {
         }
     }
 }
+function parseTrackedChangeDecisionArgs(action, args) {
+    const hasId = args.id !== undefined;
+    const hasAuthor = args.author !== undefined;
+    const hasChangeType = args.changeType !== undefined;
+    const id = hasId ? parseExactTrackedChangeIdList(args.id) : undefined;
+    const author = asString(args.author)?.trim();
+    const changeType = parseTrackedChangeKind(args.changeType);
+    if (hasId && !id) {
+        throw new errors.SuperDocCliError(`${action} requires "id" to be a non-empty string or array of non-empty strings`, {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (hasAuthor && !author) {
+        throw new errors.SuperDocCliError(`${action} requires "author" to be a non-empty string when provided`, {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (hasChangeType && !changeType) {
+        throw new errors.SuperDocCliError(`${action} requires "changeType" to be insert, delete, replacement, or format when provided`, {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (id && (hasAuthor || hasChangeType)) {
+        throw new errors.SuperDocCliError(`${action} cannot combine "id" with "author" or "changeType"`, {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (id)
+        return { id };
+    return {
+        ...(author ? { author } : {}),
+        ...(changeType ? { changeType } : {}),
+    };
+}
+function parseExactTrackedChangeIdList(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? [trimmed] : undefined;
+    }
+    if (!Array.isArray(value))
+        return undefined;
+    const ids = [];
+    const seen = new Set();
+    for (const entry of value) {
+        if (typeof entry !== 'string')
+            return undefined;
+        const trimmed = entry.trim();
+        if (trimmed.length === 0)
+            return undefined;
+        if (seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        ids.push(trimmed);
+    }
+    return ids.length > 0 ? ids : undefined;
+}
 async function superdocPerformAction(doc, args) {
     try {
         return await dispatchSuperdocPerformAction(doc, args);

package/dist/agent/actions.d.ts

@@ -224,17 +224,23 @@ export type RewriteBlockArgs = {
     changeMode?: AgentChangeMode;
 };
 export type TrackedChangeKind = 'insert' | 'delete' | 'replacement' | 'format';
-export type AcceptTrackedChangesArgs = {
-    action: 'accept_tracked_changes';
+type TrackedChangeDecisionSelector = {
+    /** One change, or an atomic set. */
+    id: string | readonly string[];
+    author?: never;
+    changeType?: never;
+} | {
+    id?: never;
     author?: string;
     /** Restrict the decision to one kind of change, e.g. 'format' = formatting-only revisions. */
     changeType?: TrackedChangeKind;
 };
+export type AcceptTrackedChangesArgs = {
+    action: 'accept_tracked_changes';
+} & TrackedChangeDecisionSelector;
 export type RejectTrackedChangesArgs = {
     action: 'reject_tracked_changes';
-    author?: string;
-    changeType?: TrackedChangeKind;
-};
+} & TrackedChangeDecisionSelector;
 export type NormalizeBodyFontSizeArgs = {
     action: 'normalize_body_font_size';
     fontSize: number;
@@ -479,3 +485,4 @@ export type AddHyperlinkArgs = {
 };
 export declare function superdocPerformAction(doc: BoundDocApi, args: unknown): Promise<AgentReceipt>;
 export declare const ACTION_NAMES_LIST: readonly ActionName[];
+export {};

package/dist/agent/actions.js

@@ -69,8 +69,8 @@ export const ACTION_HINTS = {
     add_comments: 'commentText, selector (one block) OR selectors[] to comment MANY blocks in ONE call (same text) — use selectors[] for "comment every heading/section/clause"; NEVER emit multiple add_comments calls, batch the targets into selectors[]',
     resolve_comments: 'anchorText? (resolve only comments anchored on text containing this; omit to resolve ALL open comments), reopen? (true = reopen resolved comments instead) — THE way to resolve (or reopen) comments. Use for "resolve the comment(s)" / "mark comments resolved".',
     reply_to_comment: 'commentText (the reply body), anchorText (text the target comment is anchored on / mentions) OR commentId — THE way to REPLY to an existing comment thread. Use for "reply to the comment about X" / "respond to Reviewer\'s comment". Adds a threaded reply, not a new top-level comment.',
-    accept_tracked_changes: 'author?, changeType?: insert|delete|replacement|format — e.g. changeType:"format" accepts ONLY formatting revisions (bold/italic/color), leaving text edits pending',
-    reject_tracked_changes: 'author?, changeType?: insert|delete|replacement|format',
+    accept_tracked_changes: 'id? (string or string[]) OR author?/changeType?: insert|delete|replacement|format — a string[] decides that exact set atomically; e.g. changeType:"format" accepts ONLY formatting revisions (bold/italic/color), leaving text edits pending',
+    reject_tracked_changes: 'id? (string or string[]) OR author?/changeType?: insert|delete|replacement|format — a string[] decides that exact set atomically',
     normalize_body_font_size: 'fontSize, changeMode?',
     set_font_family: 'fontFamily (e.g. "Arial"), selector? (one block) OR targetText/targetTexts[] (occurrences) — omit both to set the WHOLE body font, caseSensitive?, changeMode? — THE way to change the typeface. Use for "change the font to X" / "set the heading font to Y".',
     format_text: "bold?/italic?/underline?/strike? booleans, highlight? color name, color?, fontSize?, applied to EVERY occurrence of targetText (or targetTexts[] for several phrases in one call, or a selector'd block), caseSensitive?, changeMode? — THE way to bold/italicize/underline/highlight text, tracked-safe",
@@ -180,8 +180,8 @@ export const ACTION_ARGS = {
     resolve_comments: ['anchorText', 'reopen'],
     reply_to_comment: ['commentText', 'anchorText', 'commentId'],
     rewrite_block: ['text', 'selector', 'changeMode', 'evidence'],
-    accept_tracked_changes: ['author', 'changeType'],
-    reject_tracked_changes: ['author', 'changeType'],
+    accept_tracked_changes: ['id', 'author', 'changeType'],
+    reject_tracked_changes: ['id', 'author', 'changeType'],
     normalize_body_font_size: ['fontSize', 'changeMode'],
     set_font_family: ['fontFamily', 'selector', 'targetText', 'targetTexts', 'caseSensitive', 'changeMode'],
     apply_letter_spacing: ['selector', 'letterSpacing', 'changeMode'],
@@ -2869,17 +2869,28 @@ function normalizeTableColor(raw) {
     return normalized ? `#${normalized}` : null;
 }
 async function runAcceptTrackedChanges(doc, args) {
-    return runTrackedChangeDecision(doc, 'accept_tracked_changes', 'accept', args.author, args.changeType);
+    return runTrackedChangeDecision(doc, 'accept_tracked_changes', 'accept', Array.isArray(args.id) ? args.id : typeof args.id === 'string' ? [args.id] : undefined, args.author, args.changeType);
 }
 async function runRejectTrackedChanges(doc, args) {
-    return runTrackedChangeDecision(doc, 'reject_tracked_changes', 'reject', args.author, args.changeType);
+    return runTrackedChangeDecision(doc, 'reject_tracked_changes', 'reject', Array.isArray(args.id) ? args.id : typeof args.id === 'string' ? [args.id] : undefined, args.author, args.changeType);
 }
-async function runTrackedChangeDecision(doc, intentLabel, decision, author, changeType) {
+async function runTrackedChangeDecision(doc, intentLabel, decision, exactIds, author, changeType) {
     const pre = await buildDocumentSnapshot(doc);
     try {
-        const listFn = maybeMethod(doc, ['trackChanges', 'list']);
         const decideFn = maybeMethod(doc, ['trackChanges', 'decide']);
-        if (!listFn || !decideFn) {
+        if (!decideFn) {
+            throw new SuperDocCliError('doc.trackChanges.list / decide are not available on the document handle.', {
+                code: 'TOOL_DISPATCH_NOT_FOUND',
+            });
+        }
+        // AIDEV-NOTE: Exact `id` must go to decide({ kind: 'id'|'ids' }) once.
+        // Listing then filtering treats a stale id as an ok no-op, which looks
+        // like success and invites a follow-up with no selector (accept/reject all).
+        if (exactIds && exactIds.length > 0) {
+            return decideExactTrackedChanges(doc, intentLabel, decision, decideFn, exactIds, pre);
+        }
+        const listFn = maybeMethod(doc, ['trackChanges', 'list']);
+        if (!listFn) {
             throw new SuperDocCliError('doc.trackChanges.list / decide are not available on the document handle.', {
                 code: 'TOOL_DISPATCH_NOT_FOUND',
             });
@@ -2960,6 +2971,53 @@ async function runTrackedChangeDecision(doc, intentLabel, decision, author, chan
         return failedReceipt(intentLabel, err, pre);
     }
 }
+function trackedChangeDecideFailure(result) {
+    const rec = asRecord(result);
+    if (!rec || rec.success !== false)
+        return null;
+    const failure = asRecord(rec.failure);
+    return {
+        code: asString(failure?.code, 'ACTION_FAILED') || 'ACTION_FAILED',
+        message: asString(failure?.message, 'tracked-change decision failed') || 'tracked-change decision failed',
+    };
+}
+async function decideExactTrackedChanges(doc, intentLabel, decision, decideFn, exactIds, pre) {
+    const target = exactIds.length === 1 ? { kind: 'id', id: exactIds[0] } : { kind: 'ids', ids: [...exactIds] };
+    const result = await decideFn({ decision, target });
+    const failure = trackedChangeDecideFailure(result);
+    const selectedTargets = exactIds.map((id) => ({
+        selector: { kind: 'entity', entityType: 'trackedChange', entityId: id },
+        matched: failure ? [] : [id],
+    }));
+    if (failure) {
+        return {
+            status: 'failed',
+            intent: intentLabel,
+            preSnapshot: { revision: pre.revision, counts: pre.counts },
+            selectedTargets,
+            executedOperations: [{ operationId: 'doc.trackChanges.decide', result }],
+            verification: [],
+            errors: [
+                {
+                    code: failure.code,
+                    message: failure.message,
+                    recovery: { kind: 'reinspect' },
+                },
+            ],
+        };
+    }
+    const post = await buildDocumentSnapshot(doc);
+    const verification = evaluateChecks(pre, post, [{ kind: 'revision-changed' }]);
+    return {
+        status: verification.every((v) => v.passed) ? 'ok' : 'failed',
+        intent: intentLabel,
+        preSnapshot: { revision: pre.revision, counts: pre.counts },
+        postSnapshot: { revision: post.revision, counts: post.counts },
+        selectedTargets,
+        executedOperations: [{ operationId: 'doc.trackChanges.decide', result }],
+        verification,
+    };
+}
 async function listAllTrackedChanges(listFn) {
     const PAGE = 250;
     let offset = 0;
@@ -6658,14 +6716,12 @@ async function dispatchSuperdocPerformAction(doc, args) {
         case 'accept_tracked_changes':
             return runAcceptTrackedChanges(doc, {
                 action,
-                author: asString(args.author),
-                changeType: parseTrackedChangeKind(args.changeType),
+                ...parseTrackedChangeDecisionArgs(action, args),
             });
         case 'reject_tracked_changes':
             return runRejectTrackedChanges(doc, {
                 action,
-                author: asString(args.author),
-                changeType: parseTrackedChangeKind(args.changeType),
+                ...parseTrackedChangeDecisionArgs(action, args),
             });
         case 'normalize_body_font_size': {
             const fontSize = asNumber(args.fontSize);
@@ -7035,6 +7091,62 @@ async function dispatchSuperdocPerformAction(doc, args) {
         }
     }
 }
+function parseTrackedChangeDecisionArgs(action, args) {
+    const hasId = args.id !== undefined;
+    const hasAuthor = args.author !== undefined;
+    const hasChangeType = args.changeType !== undefined;
+    const id = hasId ? parseExactTrackedChangeIdList(args.id) : undefined;
+    const author = asString(args.author)?.trim();
+    const changeType = parseTrackedChangeKind(args.changeType);
+    if (hasId && !id) {
+        throw new SuperDocCliError(`${action} requires "id" to be a non-empty string or array of non-empty strings`, {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (hasAuthor && !author) {
+        throw new SuperDocCliError(`${action} requires "author" to be a non-empty string when provided`, {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (hasChangeType && !changeType) {
+        throw new SuperDocCliError(`${action} requires "changeType" to be insert, delete, replacement, or format when provided`, {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (id && (hasAuthor || hasChangeType)) {
+        throw new SuperDocCliError(`${action} cannot combine "id" with "author" or "changeType"`, {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (id)
+        return { id };
+    return {
+        ...(author ? { author } : {}),
+        ...(changeType ? { changeType } : {}),
+    };
+}
+function parseExactTrackedChangeIdList(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? [trimmed] : undefined;
+    }
+    if (!Array.isArray(value))
+        return undefined;
+    const ids = [];
+    const seen = new Set();
+    for (const entry of value) {
+        if (typeof entry !== 'string')
+            return undefined;
+        const trimmed = entry.trim();
+        if (trimmed.length === 0)
+            return undefined;
+        if (seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        ids.push(trimmed);
+    }
+    return ids.length > 0 ? ids : undefined;
+}
 export async function superdocPerformAction(doc, args) {
     try {
         return await dispatchSuperdocPerformAction(doc, args);

package/dist/agent/catalog.cjs

@@ -158,6 +158,12 @@ const ACTION_ARG_SCHEMA = {
     commentText: { type: 'string' },
     scope: { type: 'string', enum: ['all', 'body'] },
     excludeBlockQuotes: { type: 'boolean' },
+    id: {
+        oneOf: [
+            { type: 'string', minLength: 1 },
+            { type: 'array', minItems: 1, items: { type: 'string', minLength: 1 } },
+        ],
+    },
     author: { type: 'string' },
     changeType: { type: 'string', enum: ['insert', 'delete', 'replacement', 'format'] },
     fontSize: { type: 'number' },
@@ -316,7 +322,7 @@ function buildPerformActionDefinition(includedActions) {
         description: buildActionDescription(included.size === actions.ACTION_NAMES_LIST.length ? undefined : included),
         inputSchema: {
             type: 'object',
-            additionalProperties: true,
+            additionalProperties: false,
             required: ['action'],
             properties: {
                 action: {

package/dist/agent/catalog.js

@@ -155,6 +155,12 @@ export const ACTION_ARG_SCHEMA = {
     commentText: { type: 'string' },
     scope: { type: 'string', enum: ['all', 'body'] },
     excludeBlockQuotes: { type: 'boolean' },
+    id: {
+        oneOf: [
+            { type: 'string', minLength: 1 },
+            { type: 'array', minItems: 1, items: { type: 'string', minLength: 1 } },
+        ],
+    },
     author: { type: 'string' },
     changeType: { type: 'string', enum: ['insert', 'delete', 'replacement', 'format'] },
     fontSize: { type: 'number' },
@@ -313,7 +319,7 @@ export function buildPerformActionDefinition(includedActions) {
         description: buildActionDescription(included.size === ACTION_NAMES_LIST.length ? undefined : included),
         inputSchema: {
             type: 'object',
-            additionalProperties: true,
+            additionalProperties: false,
             required: ['action'],
             properties: {
                 action: {

package/dist/agent/doc-snapshot.cjs

@@ -141,6 +141,33 @@ function populateTableCellsFromExtract(tables, extractRaw, tableOrdinalBase = 0)
         table.cells = [...cellMap.values()].sort((left, right) => left.rowIndex - right.rowIndex || left.columnIndex - right.columnIndex);
     }
 }
+function normalizeSnapshotBlock(value, fallbackOrdinal, blockTextLimit) {
+    const rec = asRecord(value) ?? {};
+    const fullText = asString(rec.text);
+    const text = truncateBlockText(fullText, blockTextLimit);
+    const textPreview = typeof rec.textPreview === 'string' ? truncateBlockText(rec.textPreview, blockTextLimit) : null;
+    const block = {
+        // doc-api block.ordinal is 0-based; the model-facing convention is
+        // 1-based (matches paragraphOrdinal/tableOrdinal and ordinal selectors).
+        ordinal: asNumber(rec.ordinal, fallbackOrdinal) + 1,
+        nodeId: asString(rec.nodeId),
+        nodeType: asString(rec.nodeType, 'paragraph'),
+        text,
+        textPreview,
+        styleId: typeof rec.styleId === 'string' ? rec.styleId : null,
+        headingLevel: typeof rec.headingLevel === 'number' ? rec.headingLevel : undefined,
+        ...(asRecord(rec.numbering)
+            ? {
+                numbering: {
+                    marker: asString(asRecord(rec.numbering).marker) || null,
+                    path: Array.isArray(asRecord(rec.numbering).path) ? asRecord(rec.numbering).path : null,
+                    kind: asString(asRecord(rec.numbering).kind) || null,
+                },
+            }
+            : {}),
+    };
+    return block;
+}
 /**
  * Build a deterministic snapshot of a document. The snapshot uses only
  * read-mode operations from the generated contract — it never mutates state,
@@ -259,30 +286,8 @@ async function buildDocumentSnapshot(doc, options = {}) {
     const rawBlocks = Array.isArray(blocksRec?.blocks) ? blocksRec.blocks : [];
     const fullBlockText = new Map();
     const normalizedBlocks = rawBlocks.map((b, index) => {
-        const rec = asRecord(b) ?? {};
-        const fullText = asString(rec.text);
-        const text = truncateBlockText(fullText, blockTextLimit);
-        const textPreview = typeof rec.textPreview === 'string' ? truncateBlockText(rec.textPreview, blockTextLimit) : null;
-        const block = {
-            // doc-api block.ordinal is 0-based; the model-facing convention is
-            // 1-based (matches paragraphOrdinal/tableOrdinal and ordinal selectors).
-            ordinal: asNumber(rec.ordinal, blockOffset + index) + 1,
-            nodeId: asString(rec.nodeId),
-            nodeType: asString(rec.nodeType, 'paragraph'),
-            text,
-            textPreview,
-            styleId: typeof rec.styleId === 'string' ? rec.styleId : null,
-            headingLevel: typeof rec.headingLevel === 'number' ? rec.headingLevel : undefined,
-            ...(asRecord(rec.numbering)
-                ? {
-                    numbering: {
-                        marker: asString(asRecord(rec.numbering).marker) || null,
-                        path: Array.isArray(asRecord(rec.numbering).path) ? asRecord(rec.numbering).path : null,
-                        kind: asString(asRecord(rec.numbering).kind) || null,
-                    },
-                }
-                : {}),
-        };
+        const fullText = asString(asRecord(b)?.text);
+        const block = normalizeSnapshotBlock(b, blockOffset + index, blockTextLimit);
         fullBlockText.set(block, fullText);
         return block;
     });
@@ -1003,4 +1008,5 @@ exports.MutationSnapshotError = MutationSnapshotError;
 exports.buildDocumentSnapshot = buildDocumentSnapshot;
 exports.buildMutationSnapshot = buildMutationSnapshot;
 exports.matchRunsForBlock = matchRunsForBlock;
+exports.normalizeSnapshotBlock = normalizeSnapshotBlock;
 exports.resolveSnapshotSelector = resolveSnapshotSelector;

package/dist/agent/doc-snapshot.d.ts

@@ -306,6 +306,7 @@ type SnapshotOptions = {
     /** Max blocks to enrich with runs when includeBlockRuns is set (default 30). */
     blockRunsLimit?: number;
 };
+export declare function normalizeSnapshotBlock(value: unknown, fallbackOrdinal: number, blockTextLimit: number | null): SnapshotBlock;
 /**
  * Build a deterministic snapshot of a document. The snapshot uses only
  * read-mode operations from the generated contract — it never mutates state,

package/dist/agent/doc-snapshot.js

@@ -139,6 +139,33 @@ function populateTableCellsFromExtract(tables, extractRaw, tableOrdinalBase = 0)
         table.cells = [...cellMap.values()].sort((left, right) => left.rowIndex - right.rowIndex || left.columnIndex - right.columnIndex);
     }
 }
+export function normalizeSnapshotBlock(value, fallbackOrdinal, blockTextLimit) {
+    const rec = asRecord(value) ?? {};
+    const fullText = asString(rec.text);
+    const text = truncateBlockText(fullText, blockTextLimit);
+    const textPreview = typeof rec.textPreview === 'string' ? truncateBlockText(rec.textPreview, blockTextLimit) : null;
+    const block = {
+        // doc-api block.ordinal is 0-based; the model-facing convention is
+        // 1-based (matches paragraphOrdinal/tableOrdinal and ordinal selectors).
+        ordinal: asNumber(rec.ordinal, fallbackOrdinal) + 1,
+        nodeId: asString(rec.nodeId),
+        nodeType: asString(rec.nodeType, 'paragraph'),
+        text,
+        textPreview,
+        styleId: typeof rec.styleId === 'string' ? rec.styleId : null,
+        headingLevel: typeof rec.headingLevel === 'number' ? rec.headingLevel : undefined,
+        ...(asRecord(rec.numbering)
+            ? {
+                numbering: {
+                    marker: asString(asRecord(rec.numbering).marker) || null,
+                    path: Array.isArray(asRecord(rec.numbering).path) ? asRecord(rec.numbering).path : null,
+                    kind: asString(asRecord(rec.numbering).kind) || null,
+                },
+            }
+            : {}),
+    };
+    return block;
+}
 /**
  * Build a deterministic snapshot of a document. The snapshot uses only
  * read-mode operations from the generated contract — it never mutates state,
@@ -257,30 +284,8 @@ export async function buildDocumentSnapshot(doc, options = {}) {
     const rawBlocks = Array.isArray(blocksRec?.blocks) ? blocksRec.blocks : [];
     const fullBlockText = new Map();
     const normalizedBlocks = rawBlocks.map((b, index) => {
-        const rec = asRecord(b) ?? {};
-        const fullText = asString(rec.text);
-        const text = truncateBlockText(fullText, blockTextLimit);
-        const textPreview = typeof rec.textPreview === 'string' ? truncateBlockText(rec.textPreview, blockTextLimit) : null;
-        const block = {
-            // doc-api block.ordinal is 0-based; the model-facing convention is
-            // 1-based (matches paragraphOrdinal/tableOrdinal and ordinal selectors).
-            ordinal: asNumber(rec.ordinal, blockOffset + index) + 1,
-            nodeId: asString(rec.nodeId),
-            nodeType: asString(rec.nodeType, 'paragraph'),
-            text,
-            textPreview,
-            styleId: typeof rec.styleId === 'string' ? rec.styleId : null,
-            headingLevel: typeof rec.headingLevel === 'number' ? rec.headingLevel : undefined,
-            ...(asRecord(rec.numbering)
-                ? {
-                    numbering: {
-                        marker: asString(asRecord(rec.numbering).marker) || null,
-                        path: Array.isArray(asRecord(rec.numbering).path) ? asRecord(rec.numbering).path : null,
-                        kind: asString(asRecord(rec.numbering).kind) || null,
-                    },
-                }
-                : {}),
-        };
+        const fullText = asString(asRecord(b)?.text);
+        const block = normalizeSnapshotBlock(b, blockOffset + index, blockTextLimit);
         fullBlockText.set(block, fullText);
         return block;
     });