@superdoc/sdk 2.26.0 → 2.27.0-next.19

package/README.md

@@ -1,6 +1,12 @@
 # @superdoc/sdk
 
-Node.js SDK for reading and editing DOCX files with SuperDoc.
+Node.js SDK for reading and editing DOCX files with SuperDoc, without a
+browser. Query, edit, comment, and review tracked changes from your server,
+or give an LLM SuperDoc tools with the agent toolkit. Edits write back to
+OOXML, so the output opens in Word. For an interactive editor, use
+[`superdoc`](https://www.npmjs.com/package/superdoc).
+
+[Documentation](https://docs.superdoc.dev/agents/automation/node-sdk) · [GitHub](https://github.com/superdoc/docx-editor)
 
 ## Install
 
@@ -8,23 +14,37 @@ Node.js SDK for reading and editing DOCX files with SuperDoc.
 npm install @superdoc/sdk
 ```
 
+The SDK embeds the SuperDoc runtime for your platform. You do not need a
+separate CLI installation.
+
 ## Quick start
 
 ```js
 import { SuperDocClient } from '@superdoc/sdk';
 
-const client = new SuperDocClient();
-await client.connect();
+const client = new SuperDocClient({ user: { name: 'Contract bot', email: 'bot@example.com' } });
 
-const document = await client.open({ doc: './contract.docx' });
-const markdown = await document.getMarkdown();
+try {
+  await client.connect();
+  const doc = await client.open({ doc: './contract.docx' });
 
-console.log(markdown);
+  try {
+    const receipt = await doc.trackChanges.decide({ decision: 'accept', target: { kind: 'all' } });
+    if (!receipt.success) throw new Error('Accepting tracked changes failed.');
 
-await document.close();
-await client.dispose();
+    await doc.save({ out: './contract.accepted.docx', force: true });
+  } finally {
+    await doc.close({ discard: true });
+  }
+} finally {
+  await client.dispose();
+}
 ```
 
+Save to a new path so the source stays unchanged. `force: true` lets the save
+replace an earlier output. `close({ discard: true })` then closes the session
+without writing over the source.
+
 ## Client lifetime
 
 One client owns one SuperDoc host process. `connect()` starts it once; every
@@ -37,6 +57,131 @@ room sync on every call. To cut round trips further, batch related edits with
 `document.mutations.apply()` or arbitrary operations with
 `document.plan.execute()`.
 
+### Batch timeouts and recovery
+
+Use `mutations.apply({ atomic: true, steps, changeMode: 'tracked' })` for related
+structured rewrites instead of a separate search and edit request for every
+replacement. Resolve targets from the current document and inspect the batch
+receipt. Choose batch sizes from your workload's measurements; there is no
+recommended fixed cap.
+
+`requestTimeoutMs` sets the host's default request budget. A per-call
+`{ timeoutMs }` overrides it on hosts that support request timeout metadata.
+The SDK watchdog waits longer than that budget so the host can return a
+structured `TIMEOUT`. A timeout is a response deadline, not mutation rollback.
+
+When the host's response deadline expires, `TIMEOUT` details describe execution and retry safety:
+
+- `executionState: 'not-started'`, `retrySafe: true`: the request expired in
+  the host queue and will not run. Retrying cannot duplicate that request's edits.
+- `executionState: 'unknown'`, `retrySafe: false`: invocation started and may
+  still finish. Do not replay the batch. Read the same document's text and tracked
+  changes with a sufficient budget; the host serializes those reads after the
+  timed-out invocation settles. Compare the actual result with the intended
+  changes, then build a fresh plan only for work that remains.
+- `executionState: 'unknown'`, `retrySafe: true`: a recognized change-list long
+  poll already started a read. Retrying this read-only poll cannot duplicate edits,
+  even when its final re-query expires in the queue.
+
+Treat absent recovery details as an unknown outcome, including errors from
+older hosts or an operation's own timeout handling.
+`HOST_TIMEOUT` is the separate SDK watchdog error: the host did not respond and
+the SDK disconnects it. It does not prove that edits were rolled back. Preserve
+the session state and inspect the recoverable working document before creating
+another session or retrying edits. A permanently stalled invocation can also
+block later reads; another timeout is not evidence that nothing applied.
+
+## Common tasks
+
+### Read the document
+
+```js
+const markdown = await doc.getMarkdown();
+const text = await doc.getText({});
+```
+
+### Find and replace text as a tracked change
+
+`query.match` returns a complete target. Pass it to the mutation instead of
+building one yourself:
+
+```js
+const match = await doc.query.match({
+  select: { type: 'text', pattern: 'termination' },
+  require: 'first',
+});
+const item = match.items[0];
+if (!item || item.matchKind !== 'text') throw new Error('Text not found.');
+
+const operation = await doc.replace({
+  target: item.target,
+  text: 'cancellation',
+  changeMode: 'tracked',
+});
+const receipt = 'receipt' in operation ? operation.receipt : operation;
+if (!receipt.success) throw new Error('Creating the tracked change failed.');
+```
+
+### Give an LLM SuperDoc tools
+
+`createAgentToolkit` returns tool definitions, a matching system prompt, and a
+`dispatch` function, so the three cannot disagree:
+
+```js
+import { createAgentToolkit } from '@superdoc/sdk';
+
+const { tools, systemPrompt, dispatch } = await createAgentToolkit({
+  provider: 'openai', // 'openai' | 'anthropic' | 'vercel' | 'generic'
+  preset: 'core',
+  enforceChangeMode: 'tracked',
+});
+
+// For each tool call in an OpenAI Chat Completions reply:
+const result = await dispatch(doc, call.function.name, JSON.parse(call.function.arguments));
+```
+
+OpenAI sends tool arguments as a JSON string, so parse them before calling
+`dispatch`. Anthropic and Vercel pass an object already.
+
+`enforceChangeMode: 'tracked'` hides actions that cannot record a tracked
+change and records every other edit as tracked. See
+[build an agent](https://docs.superdoc.dev/agents/build/build-an-agent) for the
+full loop.
+
+## Common mistakes
+
+| Wrong | Right |
+| --- | --- |
+| Creating a client per operation | Create one per service and keep document handles open |
+| Passing OpenAI's JSON-string arguments to `dispatch` | `JSON.parse` them first. `dispatch` takes an object |
+| Omitting `preset` in `createAgentToolkit` | Pass `preset: 'core'`. Omitting it selects the older `legacy` tools |
+| Omitting `user` | Name the workflow so tracked changes show who proposed them |
+| Reusing a `query.match` target after an edit | Query again. Targets are bound to the revision that produced them |
+| Building targets from OOXML IDs such as `w14:paraId` | Use the address or target the API returns |
+| Saving over the source while testing | Save to a new path with `out` |
+| Retrying a failed receipt automatically | Inspect `executedOperations` first. Part of the edit may have committed |
+| Importing `superdoc` in Node.js | Use this package. `superdoc` is the browser editor |
+
+## Related packages
+
+- [`superdoc`](https://www.npmjs.com/package/superdoc): browser DOCX editor for reviewing the SDK's output.
+- [`@superdoc/mcp`](https://www.npmjs.com/package/@superdoc/mcp): the same tools for an existing MCP client, without writing an agent loop.
+- [`@superdoc/cli`](https://www.npmjs.com/package/@superdoc/cli): the same operations from a terminal or script.
+- [`superdoc-sdk`](https://pypi.org/project/superdoc-sdk/) on PyPI and [`superdoc-sdk`](https://crates.io/crates/superdoc-sdk) on crates.io: Python and Rust SDKs.
+
+## Documentation
+
+- [Node.js SDK guide](https://docs.superdoc.dev/agents/automation/node-sdk)
+- [Build an agent](https://docs.superdoc.dev/agents/build/build-an-agent)
+- [Document API mental model](https://docs.superdoc.dev/document-api/mental-model)
+- [Document comparison](https://docs.superdoc.dev/document-api/document-comparison)
+- [Agent safety](https://docs.superdoc.dev/agents/operate/safety)
+- [`llms.txt`](https://docs.superdoc.dev/llms.txt): machine-readable index of the documentation for coding agents.
+
+## Advanced
+
+### State directory
+
 For read-only hosts and containers, configure a writable state directory:
 
 ```js
@@ -73,6 +218,8 @@ the SDK parent can leave temporary state behind; the operating system or host
 operator must reclaim it. A new client gets a separate private root and does
 not sweep another client's state.
 
+### Authenticated collaboration rooms
+
 For token-authenticated Hocuspocus or y-websocket rooms, pass the credential as
 an option on that document's open request:
 
@@ -94,9 +241,41 @@ The credential applies only to that open request. It is not part of the
 collaboration profile or command-line arguments. Per-open token authentication
 is not supported for Liveblocks.
 
-See the [Node.js SDK guide](https://docs.superdoc.dev/agents/automation/node-sdk) for a complete workflow.
+### Attributed change records
 
-## Discover footer paragraphs
+Give each session a stable actor id with `userId`. Pass an application-signed
+claim, if you have one, as the `identityClaim` open option; like the
+collaboration token, it is sent only with that open request and is never
+written to arguments or state. SuperDoc records the claim but does not verify
+it.
+
+```js
+const document = await client.open(
+  { doc: './contract.docx', userId: 'user-42', collaboration },
+  { collaborationAuth: { type: 'token', token: userToken }, identityClaim: signedClaim },
+);
+```
+
+Every local and remote edit produces a change record. Read them with
+`document.changes.list({ after, waitMs })`; `waitMs` waits on the host without
+blocking other requests. To be told about new records, subscribe to host
+notifications:
+
+```js
+const notifications = client.subscribe();
+for await (const notification of notifications) {
+  if (notification.method === 'event.change') handle(notification.params.records);
+}
+```
+
+Each subscription holds up to `capacity` notifications (default 64). If you
+fall behind, the next read rejects with `NOTIFICATIONS_LAGGED`; resynchronize
+with `changes.list({ after })` from the last cursor you processed, then keep
+iterating. A host disconnect rejects one read with `HOST_DISCONNECTED`.
+`notifications.close()` unsubscribes and `client.dispose()` ends every
+subscription.
+
+### Discover footer paragraphs
 
 `blocks.list({ in: story })` lists top-level blocks. To discover paragraphs
 inside footer tables, including tables wrapped in block content controls, use
@@ -132,7 +311,47 @@ if (matches.total === 1) {
 }
 ```
 
-## Tracked comparison with direct style definitions
+### 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.
+
+### Rejectable comparison styles
+
+For standalone V2 comparisons, use the tracked style policy when reviewers need to
+reject proposed styling as well as text:
+
+```js
+const diff = await older.diff.compare({ targetSnapshot, styleChangeMode: 'tracked' });
+const result = await older.diff.apply({ diff, changeMode: 'tracked', styleChangeMode: 'tracked' });
+await older.save({ out: 'comparison.docx' });
+```
+
+The saved file contains separate proposed style definitions and tracked references
+that Word can accept or reject. Rejection restores the original text and effective
+styling. Unused definitions may remain after a decision, and proposed styles retain
+their distinct names. Inspect `result.styleChanges` and `result.diagnostics`.
+
+This policy supports non-default paragraph and character styles in the main body,
+including inherited styles and outline-based TOCs. TOCs that select an affected style
+by identity (`\o`) or name (`\t`) are refused. Defaults, table styles, affected styles in other stories,
+combined table topology changes, pre-existing revisions, and definitions that activate already-used unresolved style
+references are refused. Numbering
+and settings retain their restrictions. Versioned suggest-only review sessions have
+a separate policy and refuse this option. Read eligibility before applying and
+handle apply-time refusals without saving a result.
+
+### Tracked comparison with direct style definitions
 
 For standalone V2 comparisons, `styleChangeMode: 'direct'` lets you explicitly
 carry the target style definitions while applying body edits as tracked changes:
@@ -147,12 +366,12 @@ await older.save({ out: 'comparison.docx' });
 Set the policy on both calls: compare reports eligibility for that policy;
 apply requires its own explicit consent. Style definitions are applied directly
 and remain if the body revisions are rejected in Word. A style-only comparison
-creates no body revisions. Without this option, changed style definitions still
+creates no body revisions. Without an explicit style policy, changed definitions still
 block tracked apply. Unsupported numbering, settings, and other package changes
 retain their existing restrictions. Suggest-only versioned review sessions
 refuse this direct-style option.
 
-## Tracked comparison with exact-file review
+### Tracked comparison with exact-file review
 
 The SDK's `diff.capture` and `diff.compare` describe a snapshot comparison. A
 blocked tracked `diff.apply` cannot turn that snapshot into a complete review
@@ -216,7 +435,7 @@ endpoints; other supported changes become one whole-document proposal. A stale
 base or invalid DOCX returns a refusal without a partial apply. The host owns
 authorization, durable storage, reviewer presentation, and decisions.
 
-## Agent execution evidence
+### Agent execution evidence
 
 The core preset's `agent_apply`, `agent_verify`, and supported named actions
 collect the facts their targets and checks need. CLI-backed sessions
@@ -262,19 +481,7 @@ automatically replay the write.
 
 ## License
 
-AGPL-3.0. Commercial licenses are available from [SuperDoc](https://www.superdoc.dev).
-
-## Inspecting textbox sections
+AGPL-3.0. [Commercial licenses](https://www.superdoc.dev/#pricing) are
+available for proprietary deployments.
 
-`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.
+The retained legacy comparison adapter refuses tracked style policy with `CAPABILITY_UNSUPPORTED`; use the current typed engine through the standalone SDK.

package/dist/agent/actions.cjs

@@ -5398,6 +5398,9 @@ function matchRunStyle(run) {
         ...(color ? { color } : {}),
     };
 }
+function sameMatchRunStyle(a, b) {
+    return ['bold', 'italic', 'underline', 'fontSize', 'fontFamily', 'color'].every((key) => a[key] === b[key]);
+}
 /**
  * A sampled style as a `format.apply` `inline` payload.
  *
@@ -5466,36 +5469,71 @@ async function listItemRunPattern(doc, text, blockId) {
             if (asString(rec?.blockId) !== blockId)
                 continue;
             const runTextOf = (r) => asString(asRecord(r)?.text, '') ?? '';
-            const runs = (Array.isArray(rec?.runs) ? rec.runs : []).filter((r) => runTextOf(r).length > 0);
-            if (runs.length === 0)
+            const sourceRuns = (Array.isArray(rec?.runs) ? rec.runs : []).filter((run) => runTextOf(run));
+            if (sourceRuns.length === 0)
                 continue;
-            const typedLead = typedPrefixLabelOf(runs, runTextOf);
-            if (typedLead)
-                return typedLead;
             const blockText = asString(rec?.text, '') ?? '';
-            // A quoted defined term keeps its opening quote in a run of its own —
-            // `"` + **Deliverables** + `" means …` — so the label is the SECOND run
-            // and the quotes stay unemphasised.
-            const opener = runTextOf(runs[0]).trim();
-            const quote = LEAD_IN_QUOTES.find((q) => opener === q);
-            const labelIndex = quote && runs.length > 2 ? 1 : 0;
-            const label = runs[labelIndex];
-            const labelText = runTextOf(label);
-            const leadStyle = matchRunStyle(label);
-            if (runs.length === 1)
-                return runPatternOf(leadStyle);
-            // The body is the run the label INTRODUCES, not the longest run in the
-            // block: a later emphasised phrase is part of the prose, and sampling it
-            // would stamp its emphasis across the whole new block.
-            const bodyStyle = matchRunStyle(runs[labelIndex + 1]);
-            const differs = ['bold', 'italic', 'underline', 'fontSize', 'fontFamily', 'color'].some((k) => leadStyle[k] !== bodyStyle[k]);
-            const shape = leadInShapeOf(blockText, labelText, labelIndex > 0 ? quote : undefined);
-            const isLabel = differs && shape != null && labelText.length > 0 && labelText.length <= LEAD_IN_MAX_CHARS;
-            return runPatternOf(bodyStyle, isLabel && shape ? { style: leadStyle, shape } : undefined);
+            const rawPattern = runPatternFromRuns(sourceRuns, blockText, runTextOf);
+            if (rawPattern.lead)
+                return rawPattern;
+            const runs = [];
+            for (const run of sourceRuns) {
+                const current = asRecord(run);
+                const text = runTextOf(current);
+                if (!current || !text)
+                    continue;
+                const previous = runs.at(-1);
+                const previousRange = asRecord(previous?.range);
+                const currentRange = asRecord(current.range);
+                const contiguous = previousRange || currentRange
+                    ? typeof previousRange?.start === 'number' &&
+                        typeof previousRange.end === 'number' &&
+                        typeof currentRange?.start === 'number' &&
+                        typeof currentRange?.end === 'number' &&
+                        previousRange.end === currentRange.start
+                    : true;
+                const previousStyle = matchRunStyle(previous);
+                const currentStyle = matchRunStyle(current);
+                const equalStyle = sameMatchRunStyle(previousStyle, currentStyle);
+                if (previous && contiguous && equalStyle) {
+                    previous.text = runTextOf(previous) + text;
+                    if (previousRange && currentRange)
+                        previous.range = { ...previousRange, end: currentRange.end };
+                }
+                else {
+                    runs.push({ ...current });
+                }
+            }
+            const normalizedPattern = runPatternFromRuns(runs, blockText, runTextOf);
+            return normalizedPattern.lead ? normalizedPattern : rawPattern;
         }
     }
     return null;
 }
+function runPatternFromRuns(runs, blockText, runTextOf) {
+    const typedLead = typedPrefixLabelOf(runs, runTextOf);
+    if (typedLead)
+        return typedLead;
+    // A quoted defined term keeps its opening quote in a run of its own —
+    // `"` + **Deliverables** + `" means …` — so the label is the SECOND run
+    // and the quotes stay unemphasised.
+    const opener = runTextOf(runs[0]).trim();
+    const quote = LEAD_IN_QUOTES.find((q) => opener === q);
+    const labelIndex = quote && runs.length > 2 ? 1 : 0;
+    const label = runs[labelIndex];
+    const labelText = runTextOf(label);
+    const leadStyle = matchRunStyle(label);
+    if (runs.length === 1)
+        return runPatternOf(leadStyle);
+    // The body is the run the label INTRODUCES, not the longest run in the
+    // block: a later emphasised phrase is part of the prose, and sampling it
+    // would stamp its emphasis across the whole new block.
+    const bodyStyle = matchRunStyle(runs[labelIndex + 1]);
+    const differs = !sameMatchRunStyle(leadStyle, bodyStyle);
+    const shape = leadInShapeOf(blockText, labelText, labelIndex > 0 ? quote : undefined);
+    const isLabel = differs && shape != null && labelText.length > 0 && labelText.length <= LEAD_IN_MAX_CHARS;
+    return runPatternOf(bodyStyle, isLabel && shape ? { style: leadStyle, shape } : undefined);
+}
 function typedPrefixLabelOf(runs, runTextOf) {
     const typed = typedMarkerPrefixOf(runs.map(runTextOf).join(''));
     if (!typed)

package/dist/agent/actions.js

@@ -5395,6 +5395,9 @@ function matchRunStyle(run) {
         ...(color ? { color } : {}),
     };
 }
+function sameMatchRunStyle(a, b) {
+    return ['bold', 'italic', 'underline', 'fontSize', 'fontFamily', 'color'].every((key) => a[key] === b[key]);
+}
 /**
  * A sampled style as a `format.apply` `inline` payload.
  *
@@ -5463,36 +5466,71 @@ async function listItemRunPattern(doc, text, blockId) {
             if (asString(rec?.blockId) !== blockId)
                 continue;
             const runTextOf = (r) => asString(asRecord(r)?.text, '') ?? '';
-            const runs = (Array.isArray(rec?.runs) ? rec.runs : []).filter((r) => runTextOf(r).length > 0);
-            if (runs.length === 0)
+            const sourceRuns = (Array.isArray(rec?.runs) ? rec.runs : []).filter((run) => runTextOf(run));
+            if (sourceRuns.length === 0)
                 continue;
-            const typedLead = typedPrefixLabelOf(runs, runTextOf);
-            if (typedLead)
-                return typedLead;
             const blockText = asString(rec?.text, '') ?? '';
-            // A quoted defined term keeps its opening quote in a run of its own —
-            // `"` + **Deliverables** + `" means …` — so the label is the SECOND run
-            // and the quotes stay unemphasised.
-            const opener = runTextOf(runs[0]).trim();
-            const quote = LEAD_IN_QUOTES.find((q) => opener === q);
-            const labelIndex = quote && runs.length > 2 ? 1 : 0;
-            const label = runs[labelIndex];
-            const labelText = runTextOf(label);
-            const leadStyle = matchRunStyle(label);
-            if (runs.length === 1)
-                return runPatternOf(leadStyle);
-            // The body is the run the label INTRODUCES, not the longest run in the
-            // block: a later emphasised phrase is part of the prose, and sampling it
-            // would stamp its emphasis across the whole new block.
-            const bodyStyle = matchRunStyle(runs[labelIndex + 1]);
-            const differs = ['bold', 'italic', 'underline', 'fontSize', 'fontFamily', 'color'].some((k) => leadStyle[k] !== bodyStyle[k]);
-            const shape = leadInShapeOf(blockText, labelText, labelIndex > 0 ? quote : undefined);
-            const isLabel = differs && shape != null && labelText.length > 0 && labelText.length <= LEAD_IN_MAX_CHARS;
-            return runPatternOf(bodyStyle, isLabel && shape ? { style: leadStyle, shape } : undefined);
+            const rawPattern = runPatternFromRuns(sourceRuns, blockText, runTextOf);
+            if (rawPattern.lead)
+                return rawPattern;
+            const runs = [];
+            for (const run of sourceRuns) {
+                const current = asRecord(run);
+                const text = runTextOf(current);
+                if (!current || !text)
+                    continue;
+                const previous = runs.at(-1);
+                const previousRange = asRecord(previous?.range);
+                const currentRange = asRecord(current.range);
+                const contiguous = previousRange || currentRange
+                    ? typeof previousRange?.start === 'number' &&
+                        typeof previousRange.end === 'number' &&
+                        typeof currentRange?.start === 'number' &&
+                        typeof currentRange?.end === 'number' &&
+                        previousRange.end === currentRange.start
+                    : true;
+                const previousStyle = matchRunStyle(previous);
+                const currentStyle = matchRunStyle(current);
+                const equalStyle = sameMatchRunStyle(previousStyle, currentStyle);
+                if (previous && contiguous && equalStyle) {
+                    previous.text = runTextOf(previous) + text;
+                    if (previousRange && currentRange)
+                        previous.range = { ...previousRange, end: currentRange.end };
+                }
+                else {
+                    runs.push({ ...current });
+                }
+            }
+            const normalizedPattern = runPatternFromRuns(runs, blockText, runTextOf);
+            return normalizedPattern.lead ? normalizedPattern : rawPattern;
         }
     }
     return null;
 }
+function runPatternFromRuns(runs, blockText, runTextOf) {
+    const typedLead = typedPrefixLabelOf(runs, runTextOf);
+    if (typedLead)
+        return typedLead;
+    // A quoted defined term keeps its opening quote in a run of its own —
+    // `"` + **Deliverables** + `" means …` — so the label is the SECOND run
+    // and the quotes stay unemphasised.
+    const opener = runTextOf(runs[0]).trim();
+    const quote = LEAD_IN_QUOTES.find((q) => opener === q);
+    const labelIndex = quote && runs.length > 2 ? 1 : 0;
+    const label = runs[labelIndex];
+    const labelText = runTextOf(label);
+    const leadStyle = matchRunStyle(label);
+    if (runs.length === 1)
+        return runPatternOf(leadStyle);
+    // The body is the run the label INTRODUCES, not the longest run in the
+    // block: a later emphasised phrase is part of the prose, and sampling it
+    // would stamp its emphasis across the whole new block.
+    const bodyStyle = matchRunStyle(runs[labelIndex + 1]);
+    const differs = !sameMatchRunStyle(leadStyle, bodyStyle);
+    const shape = leadInShapeOf(blockText, labelText, labelIndex > 0 ? quote : undefined);
+    const isLabel = differs && shape != null && labelText.length > 0 && labelText.length <= LEAD_IN_MAX_CHARS;
+    return runPatternOf(bodyStyle, isLabel && shape ? { style: leadStyle, shape } : undefined);
+}
 function typedPrefixLabelOf(runs, runTextOf) {
     const typed = typedMarkerPrefixOf(runs.map(runTextOf).join(''));
     if (!typed)

package/dist/agent/catalog.d.ts

@@ -388,10 +388,6 @@ export interface ResolveActionPolicyOptions {
     ignoreUnknownActions?: boolean;
 }
 export declare function resolveActionPolicy(options?: ListAgentToolsOptions, resolveOptions?: ResolveActionPolicyOptions): ResolvedActionPolicy;
-/** @deprecated Use {@link resolveActionPolicy}; kept for callers that only need the union. */
-export declare function validateExclusions(options?: ListAgentToolsOptions): {
-    excludedActions: Set<string>;
-};
 /**
  * Tools advertised to the LLM. Only PUBLIC_AGENT_TOOL_NAMES (currently
  * superdoc_inspect + superdoc_perform_action) are returned; the remaining

package/dist/agent/catalog.js

@@ -614,10 +614,6 @@ export function resolveActionPolicy(options, resolveOptions) {
         allowDirectActions,
     };
 }
-/** @deprecated Use {@link resolveActionPolicy}; kept for callers that only need the union. */
-export function validateExclusions(options) {
-    return { excludedActions: resolveActionPolicy(options).excludedActions };
-}
 /**
  * Tools advertised to the LLM. Only PUBLIC_AGENT_TOOL_NAMES (currently
  * superdoc_inspect + superdoc_perform_action) are returned; the remaining