@superdoc/sdk 2.26.0 → 2.27.0-next.9

package/dist/index.cjs

@@ -152,6 +152,9 @@ class SuperDocClient {
     async connect() {
         await this.runtime.connect();
     }
+    subscribe(options = {}) {
+        return this.runtime.subscribe(options);
+    }
     /**
      * Open a document and return a bound document handle.
      *

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { type BoundDocApi, type DocCloseBoundParams, type DocCloseResult, type DocFormatApplyBoundParams, type DocFormatApplyResult, type DocOpenParams as GeneratedDocOpenParams, type DocOpenResult, type DocSaveBoundParams, type DocSaveResult } from './generated/client.js';
 import { SuperDocRuntime, type SuperDocClientOptions, type DocOpenOptions, type InvokeOptions, type OperationSpec, type ReplaceFileOptions, type ReplaceFileResult, type ReplaceFileSource, type RuntimeInvoker } from './runtime/process.js';
+import type { HostNotifications, SubscribeOptions } from './runtime/notifications.js';
 /**
  * Wraps a raw runtime and injects a fixed sessionId into every invoke call.
  * Implements RuntimeInvoker so generated code can use it directly.
@@ -73,6 +74,7 @@ export declare class SuperDocClient {
     private readonly pendingSessionIds;
     constructor(options?: SuperDocClientOptions);
     connect(): Promise<void>;
+    subscribe(options?: SubscribeOptions): HostNotifications;
     /**
      * Open a document and return a bound document handle.
      *
@@ -104,6 +106,7 @@ export type { AgentToolkit, CreateAgentToolkitInput } from './tools.js';
 export { defineAction } from './actions/define.js';
 export type { ActionSpec, ActionStep, DefineActionInput, JSONSchemaObject } from './actions/define.js';
 export { SuperDocCliError } from './runtime/errors.js';
+export type { HostNotification, HostNotifications, SubscribeOptions } from './runtime/notifications.js';
 export { runTrackedComparisonReview } from './tracked-review-route.js';
 export type { TrackedReviewSession, TrackedComparisonReviewInput } from './tracked-review-route.js';
 export type { CollaborationAuth, DocOpenOptions, InvokeOptions, OperationSpec, OperationParamSpec, RuntimeInvoker, SuperDocClientOptions, } from './runtime/process.js';

package/dist/index.js

@@ -140,6 +140,9 @@ export class SuperDocClient {
     async connect() {
         await this.runtime.connect();
     }
+    subscribe(options = {}) {
+        return this.runtime.subscribe(options);
+    }
     /**
      * Open a document and return a bound document handle.
      *

package/dist/presets/full.cjs

@@ -66,6 +66,7 @@ Where things live (ids for superdoc_api_call):
 - Page layout: doc.sections.list → sectionId, then doc.sections.setPageMargins / setPageSetup / setColumns / setPageNumbering / setTitlePage / setPageBorders; doc.create.sectionBreak.
 - Header / footer text: doc.sections.list → doc.headerFooters.list → (if the slot has no explicit part) doc.headerFooters.parts.create {kind} → doc.headerFooters.refs.set {target:{kind:"headerFooterSlot", section:{kind:"section", sectionId}, headerFooterKind, variant}, refId}. A new part already holds ONE empty paragraph: write into it (doc.blocks.list {in:<story>} for its blockId, then doc.insert {value, type:"text", in:<story>, blockId, offset:0}); do not add a second paragraph. Header/footer doc.insert and doc.replace refuse block targets: use target:{kind:"selection", start:{kind:"text", blockId, offset}, end:{kind:"text", blockId, offset}} plus in:<story>. Story = {kind:"story", storyType:"headerFooterSlot", section:{kind:"section", sectionId}, headerFooterKind, variant}. Page number: doc.fields.insert {mode:"raw", instruction:"PAGE", at:{kind:"text", story:<same story>, segments:[{blockId, range:{start:N, end:N}}]}} after the text "Page " (N = its length); "Page N of M" adds " of " and a NUMPAGES field. Alignment: doc.format.paragraph.setAlignment with the story on the target. Odd/even variants need doc.sections.setOddEvenHeadersFooters {enabled:true} first, then one part per variant.
 - Section breaks: doc.create.sectionBreak {at:{kind:"after", target:{kind:"block", nodeType, nodeId:<last paragraph of the closing section>}}, representation:"attachToPreviousParagraph", breakType:"nextPage"} closes the section on that paragraph, as Word does; {at:{kind:"before", target:<first paragraph of the new section>}} is the same boundary; {kind:"documentEnd"} appends a new final section. Then doc.sections.list for the new sectionId and doc.sections.setPageNumbering {start:1} to restart numbering. Add one only when the task needs a new section; never delete the paragraph hosting a break to remove it.
+- Table designs: doc.styles.getTheme reads the document palette; doc.tables.listPresets {source:"word"} returns IDs and appearance (follow nextOffset). Choose by header treatment, bandedRows.effect and fill/themeColor, and borders.layout. Accent slots are document-dependent; resolve every role through colorSchemeMapping (text/background aliases use t1/t2/bg1/bg2 keys) and apply hex tint/shade. Missing style properties inherit; direct cell formatting overrides them. doc.tables.applyPreset {nodeId, preset:<returned id>, styleOptions:{headerRow:true, bandedRows:true, bandedColumns:false}} applies a design while preserving direct formatting; choose other flags to match the task. Border-only banding does not create alternating fills. Check requested constraints and preconditions before mutating.
 - Tables: doc.tables.setBorders / applyBorderPreset / setShading (table or cell background) / setCellProperties / setColumnWidth / setRowHeight / mergeCells / splitCell / sort / setStyle / setLayout; cell text formatting via doc.format.apply on the cell paragraph (new cells must match their siblings' run formatting — read a sibling with superdoc_inspect includeTableCellRuns:true). A NEW table (create_table, markdown) gets 1pt black borders: when the document already has tables, copy their convention (width, border colour and weight: superdoc_inspect / doc.tables.get a sibling) with doc.tables.setLayout and setBorders. A border weight the request leaves open is Word's 0.5pt. Table background = setShading on the table node, not shade_cells per cell.
 - Formatting: doc.format.apply {target|ref, inline:{bold, italic, underline, color, fontSize, fontFamily, highlight}}; paragraph: doc.format.paragraph.setAlignment / setIndentation / setSpacing / setBorder / setShading / setKeepOptions / setTabStop / setNumbering. Units: colours are bare hex ("0000FF"), fontSize and letterSpacing in points, paragraph indentation and spacing in twips (20 = 1pt, 1440 = 1 inch), setBorder size in eighths of a point (1pt = 8) and space in points (Word's default is 1), table widths in twips where the schema says dxa. Box border: ONE batch of four setBorder {target, side:top|bottom|left|right, style:"single", size, color}; no paragraph setBorders exists.
 - Whole-body font/size: ONE doc.format.apply with target {kind:"selection", start:{kind:"text", blockId:<first paragraph>, offset:0}, end:{kind:"text", blockId:<last paragraph>, offset:<length>}}, not set_font_family or per-paragraph calls; headers, footers and notes are separate story calls.
@@ -102,6 +103,7 @@ const QUICK_REFERENCE_IDS = [
     'doc.format.paragraph.setIndentation',
     'doc.format.paragraph.setSpacing',
     'doc.format.paragraph.setKeepOptions',
+    'doc.styles.getTheme',
     'doc.styles.getCatalog',
     'doc.styles.create',
     'doc.comments.list',
@@ -112,6 +114,8 @@ const QUICK_REFERENCE_IDS = [
     'doc.trackChanges.list',
     'doc.trackChanges.get',
     'doc.trackChanges.decide',
+    'doc.tables.listPresets',
+    'doc.tables.applyPreset',
     'doc.tables.get',
     'doc.tables.getProperties',
     'doc.tables.getCells',

package/dist/presets/full.js

@@ -63,6 +63,7 @@ Where things live (ids for superdoc_api_call):
 - Page layout: doc.sections.list → sectionId, then doc.sections.setPageMargins / setPageSetup / setColumns / setPageNumbering / setTitlePage / setPageBorders; doc.create.sectionBreak.
 - Header / footer text: doc.sections.list → doc.headerFooters.list → (if the slot has no explicit part) doc.headerFooters.parts.create {kind} → doc.headerFooters.refs.set {target:{kind:"headerFooterSlot", section:{kind:"section", sectionId}, headerFooterKind, variant}, refId}. A new part already holds ONE empty paragraph: write into it (doc.blocks.list {in:<story>} for its blockId, then doc.insert {value, type:"text", in:<story>, blockId, offset:0}); do not add a second paragraph. Header/footer doc.insert and doc.replace refuse block targets: use target:{kind:"selection", start:{kind:"text", blockId, offset}, end:{kind:"text", blockId, offset}} plus in:<story>. Story = {kind:"story", storyType:"headerFooterSlot", section:{kind:"section", sectionId}, headerFooterKind, variant}. Page number: doc.fields.insert {mode:"raw", instruction:"PAGE", at:{kind:"text", story:<same story>, segments:[{blockId, range:{start:N, end:N}}]}} after the text "Page " (N = its length); "Page N of M" adds " of " and a NUMPAGES field. Alignment: doc.format.paragraph.setAlignment with the story on the target. Odd/even variants need doc.sections.setOddEvenHeadersFooters {enabled:true} first, then one part per variant.
 - Section breaks: doc.create.sectionBreak {at:{kind:"after", target:{kind:"block", nodeType, nodeId:<last paragraph of the closing section>}}, representation:"attachToPreviousParagraph", breakType:"nextPage"} closes the section on that paragraph, as Word does; {at:{kind:"before", target:<first paragraph of the new section>}} is the same boundary; {kind:"documentEnd"} appends a new final section. Then doc.sections.list for the new sectionId and doc.sections.setPageNumbering {start:1} to restart numbering. Add one only when the task needs a new section; never delete the paragraph hosting a break to remove it.
+- Table designs: doc.styles.getTheme reads the document palette; doc.tables.listPresets {source:"word"} returns IDs and appearance (follow nextOffset). Choose by header treatment, bandedRows.effect and fill/themeColor, and borders.layout. Accent slots are document-dependent; resolve every role through colorSchemeMapping (text/background aliases use t1/t2/bg1/bg2 keys) and apply hex tint/shade. Missing style properties inherit; direct cell formatting overrides them. doc.tables.applyPreset {nodeId, preset:<returned id>, styleOptions:{headerRow:true, bandedRows:true, bandedColumns:false}} applies a design while preserving direct formatting; choose other flags to match the task. Border-only banding does not create alternating fills. Check requested constraints and preconditions before mutating.
 - Tables: doc.tables.setBorders / applyBorderPreset / setShading (table or cell background) / setCellProperties / setColumnWidth / setRowHeight / mergeCells / splitCell / sort / setStyle / setLayout; cell text formatting via doc.format.apply on the cell paragraph (new cells must match their siblings' run formatting — read a sibling with superdoc_inspect includeTableCellRuns:true). A NEW table (create_table, markdown) gets 1pt black borders: when the document already has tables, copy their convention (width, border colour and weight: superdoc_inspect / doc.tables.get a sibling) with doc.tables.setLayout and setBorders. A border weight the request leaves open is Word's 0.5pt. Table background = setShading on the table node, not shade_cells per cell.
 - Formatting: doc.format.apply {target|ref, inline:{bold, italic, underline, color, fontSize, fontFamily, highlight}}; paragraph: doc.format.paragraph.setAlignment / setIndentation / setSpacing / setBorder / setShading / setKeepOptions / setTabStop / setNumbering. Units: colours are bare hex ("0000FF"), fontSize and letterSpacing in points, paragraph indentation and spacing in twips (20 = 1pt, 1440 = 1 inch), setBorder size in eighths of a point (1pt = 8) and space in points (Word's default is 1), table widths in twips where the schema says dxa. Box border: ONE batch of four setBorder {target, side:top|bottom|left|right, style:"single", size, color}; no paragraph setBorders exists.
 - Whole-body font/size: ONE doc.format.apply with target {kind:"selection", start:{kind:"text", blockId:<first paragraph>, offset:0}, end:{kind:"text", blockId:<last paragraph>, offset:<length>}}, not set_font_family or per-paragraph calls; headers, footers and notes are separate story calls.
@@ -99,6 +100,7 @@ const QUICK_REFERENCE_IDS = [
     'doc.format.paragraph.setIndentation',
     'doc.format.paragraph.setSpacing',
     'doc.format.paragraph.setKeepOptions',
+    'doc.styles.getTheme',
     'doc.styles.getCatalog',
     'doc.styles.create',
     'doc.comments.list',
@@ -109,6 +111,8 @@ const QUICK_REFERENCE_IDS = [
     'doc.trackChanges.list',
     'doc.trackChanges.get',
     'doc.trackChanges.decide',
+    'doc.tables.listPresets',
+    'doc.tables.applyPreset',
     'doc.tables.get',
     'doc.tables.getProperties',
     'doc.tables.getCells',

package/dist/prompts/full-addendum.md

@@ -13,6 +13,7 @@ Recipes (ids for superdoc_api_call unless a helper is named):
 - Footnote / endnote: superdoc_perform_action {action:"insert_footnote", anchorText:"Confidential Information", occurrence:1, content:"…", noteType:"footnote"}. The mark lands right after the phrase. Raw form: doc.footnotes.insert {type, content, at:{kind:"text", segments:[{blockId, range:{start,end}}]}}.
 - Picture: superdoc_perform_action {action:"insert_image", src:"eval-logo.png", position:"after", anchorText:"…", caption:"Figure 1 — …"} (file path, URL, or data URI; omit position/anchorText for document end). Centre it afterwards with format_paragraph on the image's paragraph and the caption if asked. Fine-tuning: doc.images.setSize / setWrapType / setPosition / setAltText.
 - Shade a header row / column / table: superdoc_perform_action {action:"shade_cells", tableOrdinal:1, rowIndex:0, color:"D9D9D9"}. Borders: doc.tables.setBorders / applyBorderPreset; cell props: doc.tables.setCellProperties (cell target only); widths/heights: setColumnWidth / setRowHeight / distributeRows / distributeColumns; merge/split: mergeCells / splitCell; sort; setStyle / applyStyle / setLayout.
+- Built-in Word table style (Grid Table 4 – Accent 1, List Table 3, Plain Table 2, …): doc.tables.listPresets {source:"word", query:"Grid Table 4"} returns preset IDs (follow nextOffset for more), then doc.tables.applyPreset {nodeId, preset:<returned id>, styleOptions:{headerRow, bandedRows, firstColumn, …}}. Read doc.styles.getTheme to resolve appearance color refs against this document, including colorSchemeMapping for all roles and hex tint/shade; never assume an accent slot is green. Select header fill, shading banding (not border-only bands), and border layout from appearance. Missing properties inherit and direct formatting overrides style cues. Use the "-accent-N" preset for theme colours, never accentColor. Direct edit only. doc.tables.getStyles lists styles already in the document; applyStyle references one of those IDs.
 - New table cells that must match neighbours: after insert_table_row / setCellText, read a sibling cell's run properties (superdoc_inspect with table runs) and apply them with doc.format.apply {target:{kind:"selection", start:{kind:"text", blockId:<cell paragraph>, offset:0}, end:{kind:"text", blockId, offset:<text length>}}, inline:{fontSize, fontFamily, bold, …}}. A new cell with default formatting next to 10pt siblings is a bug.
 - Page layout: doc.sections.list first (sectionId), then doc.sections.setPageMargins / setPageSetup (size, orientation) / setColumns / setPageNumbering / setTitlePage / setOddEvenHeadersFooters / setPageBorders / setBreakType; doc.create.sectionBreak for a new section.
 - Header / footer text: (1) doc.sections.list → sectionId; (2) doc.headerFooters.list → which slots exist and whether the slot is explicit; (3) if the slot has no explicit part: doc.headerFooters.parts.create {kind:"header"|"footer"} → refId, then doc.headerFooters.refs.set {target:{kind:"headerFooterSlot", section:{kind:"section", sectionId}, headerFooterKind, variant:"default"|"first"|"even"}, refId}; (4) write text with doc.create.paragraph {text, in:{kind:"story", storyType:"headerFooterSlot", section:{kind:"section", sectionId}, headerFooterKind, variant}, at:{kind:"documentEnd"}}; (5) page number: doc.fields.insert {mode:"raw", instruction:"PAGE", at:{kind:"text", story:<that same story>, segments:[{blockId:<the paragraph you created>, range:{start:N, end:N}}]}} where N is the offset inside that paragraph. Repeat for variant "first"/"even" when the document uses different first/even pages (headerFooters.list tells you).

package/dist/runtime/host.cjs

@@ -4,6 +4,7 @@ var node_child_process = require('node:child_process');
 var transportCommon = require('./transport-common.cjs');
 var errors = require('./errors.cjs');
 var stateDirectory = require('./state-directory.cjs');
+var notifications = require('./notifications.cjs');
 var documentEvidence = require('./document-evidence.cjs');
 var contract = require('../generated/contract.cjs');
 var sdkPolicy = require('./sdk-policy.cjs');
@@ -11,6 +12,7 @@ var sdkPolicy = require('./sdk-policy.cjs');
 const HOST_PROTOCOL_VERSION = sdkPolicy.SDK_POLICY.protocolVersion;
 const CLI_HOST_REQUIRED_FEATURES = sdkPolicy.SDK_POLICY.cliRequiredFeatures;
 const COLLABORATION_AUTH_PER_OPEN_FEATURE = sdkPolicy.SDK_POLICY.features.collaborationAuthPerOpen;
+const IDENTITY_CLAIM_PER_OPEN_FEATURE = sdkPolicy.SDK_POLICY.features.identityClaimPerOpen;
 const HOST_REQUEST_TIMEOUT_FEATURE = sdkPolicy.SDK_POLICY.features.requestTimeout;
 const CHANGE_MODES = ['direct', 'tracked'];
 const FORWARD_HOST_STDERR = typeof process !== 'undefined' && typeof process.env?.SUPERDOC_DEBUG_TEXT_REWRITE === 'string'
@@ -125,6 +127,7 @@ class HostTransport {
     activeCalls = new Set();
     hostFeatures = new Set();
     cliLocalSessions = new Set();
+    notifications = new notifications.HostNotificationHub();
     constructor(options) {
         this.stateDirectory = new stateDirectory.SdkStateDirectory(options.stateDir);
         this.hostBin = options.hostBin;
@@ -146,6 +149,9 @@ class HostTransport {
     async connect() {
         await this.runWhileActive(() => this.ensureConnected());
     }
+    subscribe(options = {}) {
+        return this.notifications.subscribe(options);
+    }
     supportsDocumentFacts(sessionId) {
         return this.usesCliDocumentFacts(sessionId);
     }
@@ -171,14 +177,18 @@ class HostTransport {
     async dispose() {
         if (this.disposePromise)
             return this.disposePromise;
-        if (this.terminalDisposalError)
+        if (this.terminalDisposalError) {
+            this.notifications.close();
             throw this.terminalDisposalError;
+        }
         if (!this.child &&
             !this.connecting &&
             this.activeCalls.size === 0 &&
             !this.stateDirectory.ownsRoot &&
-            this.stoppedChildren.size === 0)
+            this.stoppedChildren.size === 0) {
+            this.notifications.close();
             return;
+        }
         this.stopping = true;
         const disposal = this.disposeAfterActiveCalls();
         this.disposePromise = disposal;
@@ -192,6 +202,14 @@ class HostTransport {
         }
     }
     async disposeAfterActiveCalls() {
+        try {
+            await this.shutdownAfterActiveCalls();
+        }
+        finally {
+            this.notifications.close();
+        }
+    }
+    async shutdownAfterActiveCalls() {
         await Promise.allSettled(Array.from(this.activeCalls));
         if (this.terminalDisposalError)
             throw this.terminalDisposalError;
@@ -244,6 +262,12 @@ class HostTransport {
                 });
             }
         }
+        const identityClaim = options.identityClaim === undefined ? undefined : transportCommon.normalizeIdentityClaim(options.identityClaim);
+        if (identityClaim !== undefined && operation.operationId !== 'doc.open') {
+            throw new errors.SuperDocCliError('identityClaim is supported only for doc.open requests.', {
+                code: 'INVALID_ARGUMENT',
+            });
+        }
         await this.ensureConnected();
         if (collaborationAuth !== undefined && !this.hostFeatures.has(COLLABORATION_AUTH_PER_OPEN_FEATURE)) {
             throw new errors.SuperDocCliError('The connected CLI host does not support per-open collaboration authentication.', {
@@ -251,6 +275,12 @@ class HostTransport {
                 details: { feature: COLLABORATION_AUTH_PER_OPEN_FEATURE },
             });
         }
+        if (identityClaim !== undefined && !this.hostFeatures.has(IDENTITY_CLAIM_PER_OPEN_FEATURE)) {
+            throw new errors.SuperDocCliError('The connected CLI host does not support a per-open identity claim.', {
+                code: 'CAPABILITY_UNSUPPORTED',
+                details: { feature: IDENTITY_CLAIM_PER_OPEN_FEATURE },
+            });
+        }
         const sessionId = typeof params.sessionId === 'string' ? params.sessionId : undefined;
         const supportsRequestTimeoutMetadata = this.hostFeatures.has(HOST_REQUEST_TIMEOUT_FEATURE);
         const cliHostRequestTimeoutMs = this.requestTimeoutMs ?? HOST_DEFAULT_REQUEST_TIMEOUT_MS;
@@ -288,6 +318,7 @@ class HostTransport {
                 }),
             ...(includeRevision ? { includeRevision: true } : {}),
             ...(collaborationAuth === undefined ? {} : { collaborationAuth }),
+            ...(identityClaim === undefined ? {} : { identityClaim }),
         }, watchdogTimeout, {
             requestTimeoutMs: supportsRequestTimeoutMetadata ? options.timeoutMs : undefined,
         });
@@ -511,8 +542,8 @@ class HostTransport {
         if (record.jsonrpc !== '2.0') {
             return;
         }
-        // Notification (no id) — reserved for future eventing
         if ('method' in record && !('id' in record)) {
+            this.notifications.publish(record);
             return;
         }
         const idRaw = record.id;
@@ -616,6 +647,7 @@ class HostTransport {
     }
     handleDisconnect(error) {
         this.cleanupProcess(error);
+        this.notifications.disconnect(error);
     }
     cleanupProcess(error) {
         this.hostFeatures.clear();
@@ -644,6 +676,7 @@ class HostTransport {
 
 exports.COLLABORATION_AUTH_PER_OPEN_FEATURE = COLLABORATION_AUTH_PER_OPEN_FEATURE;
 exports.HostTransport = HostTransport;
+exports.IDENTITY_CLAIM_PER_OPEN_FEATURE = IDENTITY_CLAIM_PER_OPEN_FEATURE;
 exports.buildHostSpawnArgs = buildHostSpawnArgs;
 exports.mapCliInvocationResult = mapCliInvocationResult;
 exports.mapDocumentReplaceFileResult = mapDocumentReplaceFileResult;

package/dist/runtime/host.d.ts

@@ -1,5 +1,7 @@
 import { type OperationSpec, type SuperDocClientOptions, type TransportInvokeOptions } from './transport-common.js';
+import { type HostNotifications, type SubscribeOptions } from './notifications.js';
 export declare const COLLABORATION_AUTH_PER_OPEN_FEATURE: string;
+export declare const IDENTITY_CLAIM_PER_OPEN_FEATURE: string;
 export declare function mapCliInvocationResult(operation: OperationSpec, value: unknown): unknown;
 export declare function mapDocumentReplaceFileResult(response: unknown, sessionId: string): Record<string, unknown>;
 /**
@@ -53,15 +55,18 @@ export declare class HostTransport {
     private readonly activeCalls;
     private readonly hostFeatures;
     private readonly cliLocalSessions;
+    private readonly notifications;
     constructor(options: {
         hostBin: string;
     } & SuperDocClientOptions);
     connect(): Promise<void>;
+    subscribe(options?: SubscribeOptions): HostNotifications;
     supportsDocumentFacts(sessionId: string): boolean;
     usesCliDocumentFacts(sessionId: string): boolean;
     readDocumentRevision(sessionId: string): Promise<string | undefined>;
     dispose(): Promise<void>;
     private disposeAfterActiveCalls;
+    private shutdownAfterActiveCalls;
     invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: TransportInvokeOptions): Promise<TData>;
     replaceFile(sessionId: string, path: string, options?: TransportInvokeOptions): Promise<Record<string, unknown>>;
     private invokeWhileActive;

package/dist/runtime/host.js

@@ -1,13 +1,15 @@
 import { spawn } from 'node:child_process';
-import { buildOperationArgv, captureMutationPlanAuthor, buildStructuredReadInput, normalizeCollaborationAuth, resolveInvocation, } from './transport-common.js';
+import { buildOperationArgv, captureMutationPlanAuthor, buildStructuredReadInput, normalizeCollaborationAuth, normalizeIdentityClaim, resolveInvocation, } from './transport-common.js';
 import { SuperDocCliError } from './errors.js';
 import { SdkStateDirectory } from './state-directory.js';
+import { HostNotificationHub } from './notifications.js';
 import { registerMutationRevision } from './document-evidence.js';
 import { CONTRACT } from '../generated/contract.js';
 import { SDK_POLICY } from './sdk-policy.js';
 const HOST_PROTOCOL_VERSION = SDK_POLICY.protocolVersion;
 const CLI_HOST_REQUIRED_FEATURES = SDK_POLICY.cliRequiredFeatures;
 export const COLLABORATION_AUTH_PER_OPEN_FEATURE = SDK_POLICY.features.collaborationAuthPerOpen;
+export const IDENTITY_CLAIM_PER_OPEN_FEATURE = SDK_POLICY.features.identityClaimPerOpen;
 const HOST_REQUEST_TIMEOUT_FEATURE = SDK_POLICY.features.requestTimeout;
 const CHANGE_MODES = ['direct', 'tracked'];
 const FORWARD_HOST_STDERR = typeof process !== 'undefined' && typeof process.env?.SUPERDOC_DEBUG_TEXT_REWRITE === 'string'
@@ -122,6 +124,7 @@ export class HostTransport {
     activeCalls = new Set();
     hostFeatures = new Set();
     cliLocalSessions = new Set();
+    notifications = new HostNotificationHub();
     constructor(options) {
         this.stateDirectory = new SdkStateDirectory(options.stateDir);
         this.hostBin = options.hostBin;
@@ -143,6 +146,9 @@ export class HostTransport {
     async connect() {
         await this.runWhileActive(() => this.ensureConnected());
     }
+    subscribe(options = {}) {
+        return this.notifications.subscribe(options);
+    }
     supportsDocumentFacts(sessionId) {
         return this.usesCliDocumentFacts(sessionId);
     }
@@ -168,14 +174,18 @@ export class HostTransport {
     async dispose() {
         if (this.disposePromise)
             return this.disposePromise;
-        if (this.terminalDisposalError)
+        if (this.terminalDisposalError) {
+            this.notifications.close();
             throw this.terminalDisposalError;
+        }
         if (!this.child &&
             !this.connecting &&
             this.activeCalls.size === 0 &&
             !this.stateDirectory.ownsRoot &&
-            this.stoppedChildren.size === 0)
+            this.stoppedChildren.size === 0) {
+            this.notifications.close();
             return;
+        }
         this.stopping = true;
         const disposal = this.disposeAfterActiveCalls();
         this.disposePromise = disposal;
@@ -189,6 +199,14 @@ export class HostTransport {
         }
     }
     async disposeAfterActiveCalls() {
+        try {
+            await this.shutdownAfterActiveCalls();
+        }
+        finally {
+            this.notifications.close();
+        }
+    }
+    async shutdownAfterActiveCalls() {
         await Promise.allSettled(Array.from(this.activeCalls));
         if (this.terminalDisposalError)
             throw this.terminalDisposalError;
@@ -241,6 +259,12 @@ export class HostTransport {
                 });
             }
         }
+        const identityClaim = options.identityClaim === undefined ? undefined : normalizeIdentityClaim(options.identityClaim);
+        if (identityClaim !== undefined && operation.operationId !== 'doc.open') {
+            throw new SuperDocCliError('identityClaim is supported only for doc.open requests.', {
+                code: 'INVALID_ARGUMENT',
+            });
+        }
         await this.ensureConnected();
         if (collaborationAuth !== undefined && !this.hostFeatures.has(COLLABORATION_AUTH_PER_OPEN_FEATURE)) {
             throw new SuperDocCliError('The connected CLI host does not support per-open collaboration authentication.', {
@@ -248,6 +272,12 @@ export class HostTransport {
                 details: { feature: COLLABORATION_AUTH_PER_OPEN_FEATURE },
             });
         }
+        if (identityClaim !== undefined && !this.hostFeatures.has(IDENTITY_CLAIM_PER_OPEN_FEATURE)) {
+            throw new SuperDocCliError('The connected CLI host does not support a per-open identity claim.', {
+                code: 'CAPABILITY_UNSUPPORTED',
+                details: { feature: IDENTITY_CLAIM_PER_OPEN_FEATURE },
+            });
+        }
         const sessionId = typeof params.sessionId === 'string' ? params.sessionId : undefined;
         const supportsRequestTimeoutMetadata = this.hostFeatures.has(HOST_REQUEST_TIMEOUT_FEATURE);
         const cliHostRequestTimeoutMs = this.requestTimeoutMs ?? HOST_DEFAULT_REQUEST_TIMEOUT_MS;
@@ -285,6 +315,7 @@ export class HostTransport {
                 }),
             ...(includeRevision ? { includeRevision: true } : {}),
             ...(collaborationAuth === undefined ? {} : { collaborationAuth }),
+            ...(identityClaim === undefined ? {} : { identityClaim }),
         }, watchdogTimeout, {
             requestTimeoutMs: supportsRequestTimeoutMetadata ? options.timeoutMs : undefined,
         });
@@ -508,8 +539,8 @@ export class HostTransport {
         if (record.jsonrpc !== '2.0') {
             return;
         }
-        // Notification (no id) — reserved for future eventing
         if ('method' in record && !('id' in record)) {
+            this.notifications.publish(record);
             return;
         }
         const idRaw = record.id;
@@ -613,6 +644,7 @@ export class HostTransport {
     }
     handleDisconnect(error) {
         this.cleanupProcess(error);
+        this.notifications.disconnect(error);
     }
     cleanupProcess(error) {
         this.hostFeatures.clear();

package/dist/runtime/notifications.cjs

@@ -0,0 +1,124 @@
+'use strict';
+
+var errors = require('./errors.cjs');
+
+const NOTIFICATIONS_LAGGED = 'NOTIFICATIONS_LAGGED';
+const DEFAULT_NOTIFICATION_CAPACITY = 64;
+const LAGGED_MESSAGE = 'resynchronize document state before using notification-derived caches';
+const RESYNC_HINT = 'Call changes.list with the cursor of the last change record you processed.';
+class HostNotifications {
+    capacity;
+    detach;
+    queue = [];
+    waiters = [];
+    skipped = 0;
+    failure = null;
+    closed = false;
+    constructor(capacity, detach) {
+        this.capacity = capacity;
+        this.detach = detach;
+    }
+    next() {
+        if (this.skipped > 0) {
+            const skipped = this.skipped;
+            this.skipped = 0;
+            return Promise.reject(new errors.SuperDocCliError(LAGGED_MESSAGE, {
+                code: NOTIFICATIONS_LAGGED,
+                details: { skipped, resync: RESYNC_HINT },
+            }));
+        }
+        const notification = this.queue.shift();
+        if (notification)
+            return Promise.resolve({ done: false, value: notification });
+        if (this.failure) {
+            const failure = this.failure;
+            this.failure = null;
+            return Promise.reject(failure);
+        }
+        if (this.closed)
+            return Promise.resolve({ done: true, value: undefined });
+        return new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
+    }
+    return() {
+        this.close();
+        return Promise.resolve({ done: true, value: undefined });
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.queue.length = 0;
+        this.skipped = 0;
+        this.failure = null;
+        this.detach(this);
+        for (const waiter of this.waiters.splice(0))
+            waiter.resolve({ done: true, value: undefined });
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    get isClosed() {
+        return this.closed;
+    }
+    deliver(notification) {
+        if (this.closed)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.resolve({ done: false, value: notification });
+            return;
+        }
+        if (this.queue.length >= this.capacity) {
+            this.queue.shift();
+            this.skipped += 1;
+        }
+        this.queue.push(notification);
+    }
+    fail(error) {
+        if (this.closed)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.reject(error);
+            return;
+        }
+        this.failure = error;
+    }
+}
+class HostNotificationHub {
+    subscriptions = new Set();
+    subscribe(options = {}) {
+        const capacity = options.capacity ?? DEFAULT_NOTIFICATION_CAPACITY;
+        if (!Number.isSafeInteger(capacity) || capacity < 1) {
+            throw new errors.SuperDocCliError('Notification capacity must be a positive integer.', {
+                code: 'INVALID_ARGUMENT',
+                details: { capacity },
+            });
+        }
+        const subscription = new HostNotifications(capacity, (closed) => this.subscriptions.delete(closed));
+        this.subscriptions.add(subscription);
+        return subscription;
+    }
+    publish(frame) {
+        if (this.subscriptions.size === 0 || typeof frame.method !== 'string')
+            return;
+        const notification = frame.params === undefined
+            ? { jsonrpc: '2.0', method: frame.method }
+            : { jsonrpc: '2.0', method: frame.method, params: frame.params };
+        for (const subscription of this.subscriptions)
+            subscription.deliver(notification);
+    }
+    disconnect(error) {
+        for (const subscription of this.subscriptions)
+            subscription.fail(error);
+    }
+    close() {
+        for (const subscription of [...this.subscriptions])
+            subscription.close();
+    }
+}
+
+exports.DEFAULT_NOTIFICATION_CAPACITY = DEFAULT_NOTIFICATION_CAPACITY;
+exports.HostNotificationHub = HostNotificationHub;
+exports.HostNotifications = HostNotifications;
+exports.NOTIFICATIONS_LAGGED = NOTIFICATIONS_LAGGED;

package/dist/runtime/notifications.d.ts

@@ -0,0 +1,35 @@
+import { SuperDocCliError } from './errors.js';
+export declare const NOTIFICATIONS_LAGGED = "NOTIFICATIONS_LAGGED";
+export declare const DEFAULT_NOTIFICATION_CAPACITY = 64;
+export interface HostNotification {
+    readonly jsonrpc: '2.0';
+    readonly method: string;
+    readonly params?: unknown;
+}
+export interface SubscribeOptions {
+    readonly capacity?: number;
+}
+export declare class HostNotifications implements AsyncIterableIterator<HostNotification> {
+    private readonly capacity;
+    private readonly detach;
+    private readonly queue;
+    private readonly waiters;
+    private skipped;
+    private failure;
+    private closed;
+    constructor(capacity: number, detach: (subscription: HostNotifications) => void);
+    next(): Promise<IteratorResult<HostNotification, undefined>>;
+    return(): Promise<IteratorResult<HostNotification, undefined>>;
+    close(): void;
+    [Symbol.asyncIterator](): this;
+    get isClosed(): boolean;
+    deliver(notification: HostNotification): void;
+    fail(error: SuperDocCliError): void;
+}
+export declare class HostNotificationHub {
+    private readonly subscriptions;
+    subscribe(options?: SubscribeOptions): HostNotifications;
+    publish(frame: Record<string, unknown>): void;
+    disconnect(error: SuperDocCliError): void;
+    close(): void;
+}