@superdoc/sdk 2.8.0 → 2.9.0-next.1

package/README.md

@@ -25,6 +25,27 @@ await document.close();
 await client.dispose();
 ```
 
+For token-authenticated Hocuspocus or y-websocket rooms, pass the credential as
+an option on that document's open request:
+
+```js
+const document = await client.open(
+  {
+    doc: './contract.docx',
+    collaboration: {
+      providerType: 'hocuspocus',
+      url: 'wss://collaboration.example.com',
+      documentId: 'contract-123',
+    },
+  },
+  { collaborationAuth: { type: 'token', token: userToken } },
+);
+```
+
+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 or the standalone document host.
+
 See the [Node.js SDK guide](https://docs.superdoc.dev/agents/automation/node-sdk) for a complete workflow.
 
 ## License

package/dist/generated/contract.cjs

@@ -17,6 +17,7 @@ const CONTRACT = {
                     "protocolVersion": "1.0",
                     "features": [
                         "cli.invoke",
+                        "collaboration.auth.perOpen",
                         "document.open",
                         "document.open.defaultChangeMode",
                         "document.currentRevision",

package/dist/generated/contract.js

@@ -2901,6 +2901,7 @@ export const CONTRACT = {
         "transport": "stdio",
         "features": [
             "cli.invoke",
+            "collaboration.auth.perOpen",
             "document.open",
             "document.open.defaultChangeMode",
             "document.currentRevision",
@@ -2931,6 +2932,7 @@ export const CONTRACT = {
                     "protocolVersion": "1.0",
                     "features": [
                         "cli.invoke",
+                        "collaboration.auth.perOpen",
                         "document.open",
                         "document.open.defaultChangeMode",
                         "document.currentRevision",

package/dist/index.cjs

@@ -113,6 +113,7 @@ class SuperDocClient {
     rawApi;
     defaultDocumentRuntime;
     handles = new Map();
+    pendingSessionIds = new Set();
     constructor(options = {}) {
         this.defaultDocumentRuntime = options.runtime;
         this.runtime = new process.SuperDocRuntime(options);
@@ -133,18 +134,27 @@ class SuperDocClient {
             ? { ...params, runtime: this.defaultDocumentRuntime }
             : params;
         const explicitSessionId = openParams.sessionId;
-        if (typeof explicitSessionId === 'string' && this.handles.has(explicitSessionId)) {
-            throw new errors.SuperDocCliError(`Session id already open in this client: ${explicitSessionId}`, {
-                code: 'SESSION_ALREADY_OPEN',
-                details: { sessionId: explicitSessionId },
-            });
+        if (typeof explicitSessionId === 'string') {
+            if (this.handles.has(explicitSessionId) || this.pendingSessionIds.has(explicitSessionId)) {
+                throw new errors.SuperDocCliError(`Session id already open in this client: ${explicitSessionId}`, {
+                    code: 'SESSION_ALREADY_OPEN',
+                    details: { sessionId: explicitSessionId },
+                });
+            }
+            this.pendingSessionIds.add(explicitSessionId);
+        }
+        try {
+            const result = (await this.rawApi.open(openParams, options));
+            const contextId = result.contextId;
+            const boundRuntime = new BoundRuntime(this.runtime, contextId);
+            const handle = new SuperDocDocument(boundRuntime, contextId, result, this);
+            this.handles.set(contextId, handle);
+            return handle;
+        }
+        finally {
+            if (typeof explicitSessionId === 'string')
+                this.pendingSessionIds.delete(explicitSessionId);
         }
-        const result = (await this.rawApi.open(openParams, options));
-        const contextId = result.contextId;
-        const boundRuntime = new BoundRuntime(this.runtime, contextId);
-        const handle = new SuperDocDocument(boundRuntime, contextId, result, this);
-        this.handles.set(contextId, handle);
-        return handle;
     }
     async describe(_params = {}, _options) {
         return introspection.describeContract();

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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 InvokeOptions, type OperationSpec, type RuntimeInvoker } from './runtime/process.js';
+import { SuperDocRuntime, type SuperDocClientOptions, type DocOpenOptions, type InvokeOptions, type OperationSpec, type RuntimeInvoker } from './runtime/process.js';
 /**
  * Wraps a raw runtime and injects a fixed sessionId into every invoke call.
  * Implements RuntimeInvoker so generated code can use it directly.
@@ -64,6 +64,7 @@ export declare class SuperDocClient {
     private readonly rawApi;
     private readonly defaultDocumentRuntime;
     private readonly handles;
+    private readonly pendingSessionIds;
     constructor(options?: SuperDocClientOptions);
     connect(): Promise<void>;
     /**
@@ -73,7 +74,7 @@ export declare class SuperDocClient {
      * automatically. The same file can be opened multiple times with
      * different session ids (useful for diff workflows).
      */
-    open(params: DocOpenParams, options?: InvokeOptions): Promise<SuperDocDocument>;
+    open(params: DocOpenParams, options?: DocOpenOptions): Promise<SuperDocDocument>;
     describe(_params?: Record<string, unknown>, _options?: InvokeOptions): Promise<unknown>;
     describeCommand(params: DocDescribeCommandParams, _options?: InvokeOptions): Promise<unknown>;
     dispose(): Promise<void>;
@@ -93,5 +94,5 @@ export type { GetSystemPromptOptions, GetToolsOptions, GetToolsResult, PresetDes
 export { createAgentToolkit } from './tools.js';
 export type { AgentToolkit, CreateAgentToolkitInput } from './tools.js';
 export { SuperDocCliError } from './runtime/errors.js';
-export type { InvokeOptions, OperationSpec, OperationParamSpec, RuntimeInvoker, SuperDocClientOptions, } from './runtime/process.js';
+export type { CollaborationAuth, DocOpenOptions, InvokeOptions, OperationSpec, OperationParamSpec, RuntimeInvoker, SuperDocClientOptions, } from './runtime/process.js';
 export type { DocOpenResult } from './generated/client.js';

package/dist/index.js

@@ -105,6 +105,7 @@ export class SuperDocClient {
     rawApi;
     defaultDocumentRuntime;
     handles = new Map();
+    pendingSessionIds = new Set();
     constructor(options = {}) {
         this.defaultDocumentRuntime = options.runtime;
         this.runtime = new SuperDocRuntime(options);
@@ -125,18 +126,27 @@ export class SuperDocClient {
             ? { ...params, runtime: this.defaultDocumentRuntime }
             : params;
         const explicitSessionId = openParams.sessionId;
-        if (typeof explicitSessionId === 'string' && this.handles.has(explicitSessionId)) {
-            throw new SuperDocCliError(`Session id already open in this client: ${explicitSessionId}`, {
-                code: 'SESSION_ALREADY_OPEN',
-                details: { sessionId: explicitSessionId },
-            });
+        if (typeof explicitSessionId === 'string') {
+            if (this.handles.has(explicitSessionId) || this.pendingSessionIds.has(explicitSessionId)) {
+                throw new SuperDocCliError(`Session id already open in this client: ${explicitSessionId}`, {
+                    code: 'SESSION_ALREADY_OPEN',
+                    details: { sessionId: explicitSessionId },
+                });
+            }
+            this.pendingSessionIds.add(explicitSessionId);
+        }
+        try {
+            const result = (await this.rawApi.open(openParams, options));
+            const contextId = result.contextId;
+            const boundRuntime = new BoundRuntime(this.runtime, contextId);
+            const handle = new SuperDocDocument(boundRuntime, contextId, result, this);
+            this.handles.set(contextId, handle);
+            return handle;
+        }
+        finally {
+            if (typeof explicitSessionId === 'string')
+                this.pendingSessionIds.delete(explicitSessionId);
         }
-        const result = (await this.rawApi.open(openParams, options));
-        const contextId = result.contextId;
-        const boundRuntime = new BoundRuntime(this.runtime, contextId);
-        const handle = new SuperDocDocument(boundRuntime, contextId, result, this);
-        this.handles.set(contextId, handle);
-        return handle;
     }
     async describe(_params = {}, _options) {
         return describeContract();

package/dist/presets/core.cjs

@@ -392,26 +392,78 @@ async function coreGetCatalog() {
     };
 }
 /**
- * Drop the per-action documentation lines for excluded actions. Entries render
- * as single "- name: ..." lines (the drift-guard test enforces the format), so
- * line-level filtering is deterministic. Prose cross-references elsewhere in
- * the prompt are left alone — a mention costs a few tokens; a full per-action
- * manual for an uncallable action teaches the model to call it.
+ * Sentence boundary: terminal punctuation, whitespace, then something that
+ * plausibly opens a sentence — including lowercase, because prompt sentences
+ * regularly start with an action name ("comment_paragraphs applies ...").
+ * The lookbehind guards keep "e.g."/"i.e." from splitting mid-sentence; a
+ * false split is still safe because kept fragments are rejoined with their
+ * original whitespace, and erring toward MORE splits only narrows what a
+ * mention takes down with it.
+ */
+const SENTENCE_BOUNDARY = /((?<![ei]\.[ge]\.)(?<=[.!?])\s+(?=[A-Za-z"(]))/;
+function mentionsAnyAction(text, excludedActions) {
+    for (const name of excludedActions) {
+        if (new RegExp(`\\b${name}\\b`).test(text))
+            return true;
+    }
+    return false;
+}
+/**
+ * Drop the sentences of one prompt line that mention an excluded action.
+ * Returns null when nothing usable is left, so the caller drops the line.
+ */
+function stripExcludedActionSentences(line, excludedActions) {
+    if (!mentionsAnyAction(line, excludedActions))
+        return line;
+    // split() with a capturing group keeps the inter-sentence whitespace as
+    // separate array elements: even indexes are sentences, odd their separators.
+    const parts = line.split(SENTENCE_BOUNDARY);
+    const kept = [];
+    for (let i = 0; i < parts.length; i += 2) {
+        if (mentionsAnyAction(parts[i], excludedActions))
+            continue;
+        kept.push(parts[i]);
+        if (i + 1 < parts.length)
+            kept.push(parts[i + 1]);
+    }
+    let result = kept.join('').trimEnd();
+    // Losing the first sentence must not lose the bullet marker with it.
+    if (result && /^- /.test(line) && !/^- /.test(result))
+        result = `- ${result}`;
+    // Nothing left beyond the marker means the whole line was about excluded
+    // actions — drop it entirely rather than leaving an empty bullet.
+    return /[a-zA-Z0-9]/.test(result.replace(/^- /, '')) ? result : null;
+}
+/**
+ * Remove excluded actions from the prompt: drop their per-action
+ * documentation lines (entries render as single "- name: ..." lines — the
+ * drift-guard test enforces the format), then drop any remaining sentence
+ * that still mentions one. Guidance prose ("use move_range to relocate a
+ * section") is instruction, not a passing cross-reference: leaving it coaches
+ * the model into calls the schema forbids and dispatch rejects.
  */
 function stripExcludedActionLines(prompt, excludedActions) {
     if (excludedActions.size === 0)
         return prompt;
     return prompt
         .split('\n')
-        .filter((line) => {
+        .map((line) => {
         const match = /^- ([a-z_]+)(?: \/ ([a-z_]+))?:/.exec(line);
         if (!match)
-            return true;
+            return line;
         const names = [match[1], match[2]].filter((n) => Boolean(n));
-        // Drop the line only when EVERY action it documents is excluded (the
-        // paired accept/reject line survives if one side remains callable).
-        return !names.every((name) => excludedActions.has(name));
+        const callable = names.filter((name) => !excludedActions.has(name));
+        // Drop the line only when EVERY action it documents is excluded; a
+        // paired accept/reject line survives if one side remains callable, but
+        // its header keeps only the callable name.
+        if (callable.length === 0)
+            return null;
+        if (callable.length === names.length)
+            return line;
+        return `- ${callable.join(' / ')}:${line.slice(match[0].length)}`;
     })
+        .map((line) => (line === null ? null : stripExcludedActionSentences(line, excludedActions)))
+        .filter((line) => line !== null)
         .join('\n');
 }
 async function coreGetSystemPrompt(options) {

package/dist/presets/core.js

@@ -388,26 +388,78 @@ async function coreGetCatalog() {
     };
 }
 /**
- * Drop the per-action documentation lines for excluded actions. Entries render
- * as single "- name: ..." lines (the drift-guard test enforces the format), so
- * line-level filtering is deterministic. Prose cross-references elsewhere in
- * the prompt are left alone — a mention costs a few tokens; a full per-action
- * manual for an uncallable action teaches the model to call it.
+ * Sentence boundary: terminal punctuation, whitespace, then something that
+ * plausibly opens a sentence — including lowercase, because prompt sentences
+ * regularly start with an action name ("comment_paragraphs applies ...").
+ * The lookbehind guards keep "e.g."/"i.e." from splitting mid-sentence; a
+ * false split is still safe because kept fragments are rejoined with their
+ * original whitespace, and erring toward MORE splits only narrows what a
+ * mention takes down with it.
+ */
+const SENTENCE_BOUNDARY = /((?<![ei]\.[ge]\.)(?<=[.!?])\s+(?=[A-Za-z"(]))/;
+function mentionsAnyAction(text, excludedActions) {
+    for (const name of excludedActions) {
+        if (new RegExp(`\\b${name}\\b`).test(text))
+            return true;
+    }
+    return false;
+}
+/**
+ * Drop the sentences of one prompt line that mention an excluded action.
+ * Returns null when nothing usable is left, so the caller drops the line.
+ */
+function stripExcludedActionSentences(line, excludedActions) {
+    if (!mentionsAnyAction(line, excludedActions))
+        return line;
+    // split() with a capturing group keeps the inter-sentence whitespace as
+    // separate array elements: even indexes are sentences, odd their separators.
+    const parts = line.split(SENTENCE_BOUNDARY);
+    const kept = [];
+    for (let i = 0; i < parts.length; i += 2) {
+        if (mentionsAnyAction(parts[i], excludedActions))
+            continue;
+        kept.push(parts[i]);
+        if (i + 1 < parts.length)
+            kept.push(parts[i + 1]);
+    }
+    let result = kept.join('').trimEnd();
+    // Losing the first sentence must not lose the bullet marker with it.
+    if (result && /^- /.test(line) && !/^- /.test(result))
+        result = `- ${result}`;
+    // Nothing left beyond the marker means the whole line was about excluded
+    // actions — drop it entirely rather than leaving an empty bullet.
+    return /[a-zA-Z0-9]/.test(result.replace(/^- /, '')) ? result : null;
+}
+/**
+ * Remove excluded actions from the prompt: drop their per-action
+ * documentation lines (entries render as single "- name: ..." lines — the
+ * drift-guard test enforces the format), then drop any remaining sentence
+ * that still mentions one. Guidance prose ("use move_range to relocate a
+ * section") is instruction, not a passing cross-reference: leaving it coaches
+ * the model into calls the schema forbids and dispatch rejects.
  */
 function stripExcludedActionLines(prompt, excludedActions) {
     if (excludedActions.size === 0)
         return prompt;
     return prompt
         .split('\n')
-        .filter((line) => {
+        .map((line) => {
         const match = /^- ([a-z_]+)(?: \/ ([a-z_]+))?:/.exec(line);
         if (!match)
-            return true;
+            return line;
         const names = [match[1], match[2]].filter((n) => Boolean(n));
-        // Drop the line only when EVERY action it documents is excluded (the
-        // paired accept/reject line survives if one side remains callable).
-        return !names.every((name) => excludedActions.has(name));
+        const callable = names.filter((name) => !excludedActions.has(name));
+        // Drop the line only when EVERY action it documents is excluded; a
+        // paired accept/reject line survives if one side remains callable, but
+        // its header keeps only the callable name.
+        if (callable.length === 0)
+            return null;
+        if (callable.length === names.length)
+            return line;
+        return `- ${callable.join(' / ')}:${line.slice(match[0].length)}`;
     })
+        .map((line) => (line === null ? null : stripExcludedActionSentences(line, excludedActions)))
+        .filter((line) => line !== null)
         .join('\n');
 }
 async function coreGetSystemPrompt(options) {

package/dist/runtime/host.cjs

@@ -8,6 +8,7 @@ var documentRpc = require('./document-rpc.cjs');
 
 const HOST_PROTOCOL_VERSION = '1.0';
 const CLI_HOST_REQUIRED_FEATURES = ['cli.invoke', 'host.shutdown'];
+const COLLABORATION_AUTH_PER_OPEN_FEATURE = 'collaboration.auth.perOpen';
 const DOCUMENT_HOST_REQUIRED_FEATURES = [...documentRpc.DOCUMENT_RPC_FEATURES, 'host.shutdown'];
 const CHANGE_MODES = ['direct', 'tracked'];
 const FORWARD_HOST_STDERR = typeof process !== 'undefined' && typeof process.env?.SUPERDOC_DEBUG_TEXT_REWRITE === 'string'
@@ -187,7 +188,27 @@ class HostTransport {
         return this.runWhileActive(() => this.invokeWhileActive(operation, params, options));
     }
     async invokeWhileActive(operation, params, options) {
+        const collaborationAuth = options.collaborationAuth === undefined ? undefined : transportCommon.normalizeCollaborationAuth(options.collaborationAuth);
+        if (collaborationAuth !== undefined) {
+            if (operation.operationId !== 'doc.open') {
+                throw new errors.SuperDocCliError('collaborationAuth is supported only for doc.open requests.', {
+                    code: 'INVALID_ARGUMENT',
+                });
+            }
+            if (this.processMode !== 'cli') {
+                throw new errors.SuperDocCliError('Per-open collaboration authentication is not supported by the standalone document host.', {
+                    code: 'CAPABILITY_UNSUPPORTED',
+                    details: { feature: COLLABORATION_AUTH_PER_OPEN_FEATURE },
+                });
+            }
+        }
         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.', {
+                code: 'CAPABILITY_UNSUPPORTED',
+                details: { feature: COLLABORATION_AUTH_PER_OPEN_FEATURE },
+            });
+        }
         const shouldOpenThroughCliTimeoutFallback = this.processMode === 'cli' &&
             (this.requestTimeoutMs !== undefined ||
                 (options.timeoutMs !== undefined && !this.hostFeatures.has(documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE)));
@@ -282,6 +303,7 @@ class HostTransport {
         const response = await this.sendJsonRpcRequest('cli.invoke', {
             argv,
             stdinBase64,
+            ...(collaborationAuth === undefined ? {} : { collaborationAuth }),
         }, watchdogTimeout);
         if (typeof response !== 'object' || response == null || Array.isArray(response)) {
             throw new errors.SuperDocCliError('Host returned invalid cli.invoke result.', {
@@ -669,6 +691,7 @@ class HostTransport {
     }
 }
 
+exports.COLLABORATION_AUTH_PER_OPEN_FEATURE = COLLABORATION_AUTH_PER_OPEN_FEATURE;
 exports.HostTransport = HostTransport;
 exports.buildDocumentHostSpawnArgs = buildDocumentHostSpawnArgs;
 exports.buildHostSpawnArgs = buildHostSpawnArgs;

package/dist/runtime/host.d.ts

@@ -1,4 +1,5 @@
-import { type InvokeOptions, type OperationSpec, type SuperDocClientOptions } from './transport-common.js';
+import { type OperationSpec, type SuperDocClientOptions, type TransportInvokeOptions } from './transport-common.js';
+export declare const COLLABORATION_AUTH_PER_OPEN_FEATURE = "collaboration.auth.perOpen";
 export declare function mapCliInvocationResult(operation: OperationSpec, value: unknown): unknown;
 /**
  * Builds the argv passed to `spawn` for `superdoc host --stdio`. Propagates
@@ -62,7 +63,7 @@ export declare class HostTransport {
     connect(): Promise<void>;
     dispose(): Promise<void>;
     private disposeAfterActiveCalls;
-    invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+    invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: TransportInvokeOptions): Promise<TData>;
     private invokeWhileActive;
     private runWhileActive;
     private ensureConnected;

package/dist/runtime/host.js

@@ -1,10 +1,11 @@
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
-import { buildOperationArgv, resolveInvocation, } from './transport-common.js';
+import { buildOperationArgv, normalizeCollaborationAuth, resolveInvocation, } from './transport-common.js';
 import { SuperDocCliError } from './errors.js';
 import { DOCUMENT_RPC_FEATURES, DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE, DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE, DOCUMENT_RPC_SOURCE_SAVE_FEATURE, buildDocumentInvokeParams, buildDocumentOpenParams, canOpenWithDocumentRpc, documentRpcRequestSupportsResponseTimeout, documentRpcEnabled, mapDocumentLifecycleResult, mapDocumentOpenResult, supportsDocumentRpc, } from './document-rpc.js';
 const HOST_PROTOCOL_VERSION = '1.0';
 const CLI_HOST_REQUIRED_FEATURES = ['cli.invoke', 'host.shutdown'];
+export const COLLABORATION_AUTH_PER_OPEN_FEATURE = 'collaboration.auth.perOpen';
 const DOCUMENT_HOST_REQUIRED_FEATURES = [...DOCUMENT_RPC_FEATURES, 'host.shutdown'];
 const CHANGE_MODES = ['direct', 'tracked'];
 const FORWARD_HOST_STDERR = typeof process !== 'undefined' && typeof process.env?.SUPERDOC_DEBUG_TEXT_REWRITE === 'string'
@@ -184,7 +185,27 @@ export class HostTransport {
         return this.runWhileActive(() => this.invokeWhileActive(operation, params, options));
     }
     async invokeWhileActive(operation, params, options) {
+        const collaborationAuth = options.collaborationAuth === undefined ? undefined : normalizeCollaborationAuth(options.collaborationAuth);
+        if (collaborationAuth !== undefined) {
+            if (operation.operationId !== 'doc.open') {
+                throw new SuperDocCliError('collaborationAuth is supported only for doc.open requests.', {
+                    code: 'INVALID_ARGUMENT',
+                });
+            }
+            if (this.processMode !== 'cli') {
+                throw new SuperDocCliError('Per-open collaboration authentication is not supported by the standalone document host.', {
+                    code: 'CAPABILITY_UNSUPPORTED',
+                    details: { feature: COLLABORATION_AUTH_PER_OPEN_FEATURE },
+                });
+            }
+        }
         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.', {
+                code: 'CAPABILITY_UNSUPPORTED',
+                details: { feature: COLLABORATION_AUTH_PER_OPEN_FEATURE },
+            });
+        }
         const shouldOpenThroughCliTimeoutFallback = this.processMode === 'cli' &&
             (this.requestTimeoutMs !== undefined ||
                 (options.timeoutMs !== undefined && !this.hostFeatures.has(DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE)));
@@ -279,6 +300,7 @@ export class HostTransport {
         const response = await this.sendJsonRpcRequest('cli.invoke', {
             argv,
             stdinBase64,
+            ...(collaborationAuth === undefined ? {} : { collaborationAuth }),
         }, watchdogTimeout);
         if (typeof response !== 'object' || response == null || Array.isArray(response)) {
             throw new SuperDocCliError('Host returned invalid cli.invoke result.', {

package/dist/runtime/process.cjs

@@ -32,6 +32,10 @@ function resolveRuntimeProcess(options = {}, embedded = {
         processMode: 'cli',
     };
 }
+function toSafeInvokeTraceOptions(options) {
+    const { collaborationAuth: _collaborationAuth, ...traceOptions } = options;
+    return traceOptions;
+}
 /**
  * Internal runtime that delegates operations to a persistent host transport.
  *
@@ -60,7 +64,7 @@ class SuperDocRuntime {
             phase: 'start',
             operationId: operation.operationId,
             params,
-            options,
+            options: toSafeInvokeTraceOptions(options),
         });
         try {
             const result = await this.transport.invoke(operation, params, options);
@@ -88,3 +92,4 @@ class SuperDocRuntime {
 
 exports.SuperDocRuntime = SuperDocRuntime;
 exports.resolveRuntimeProcess = resolveRuntimeProcess;
+exports.toSafeInvokeTraceOptions = toSafeInvokeTraceOptions;

package/dist/runtime/process.d.ts

@@ -1,4 +1,4 @@
-import type { DocumentRuntimeKind, InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions } from './transport-common.js';
+import type { CollaborationAuth, DocumentRuntimeKind, DocOpenOptions, InvokeOptions, TransportInvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions } from './transport-common.js';
 type RuntimeProcessResolution = {
     hostBin: string;
     processMode: 'cli' | 'document';
@@ -8,6 +8,7 @@ type EmbeddedRuntimeResolvers = {
     documentHost: () => string;
 };
 export declare function resolveRuntimeProcess(options?: SuperDocClientOptions, embedded?: EmbeddedRuntimeResolvers): RuntimeProcessResolution;
+export declare function toSafeInvokeTraceOptions(options: TransportInvokeOptions): InvokeOptions;
 /**
  * Internal runtime that delegates operations to a persistent host transport.
  *
@@ -19,6 +20,6 @@ export declare class SuperDocRuntime {
     constructor(options?: SuperDocClientOptions);
     connect(): Promise<void>;
     dispose(): Promise<void>;
-    invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+    invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: TransportInvokeOptions): Promise<TData>;
 }
-export type { DocumentRuntimeKind, InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions, };
+export type { CollaborationAuth, DocumentRuntimeKind, DocOpenOptions, InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions, };

package/dist/runtime/process.js

@@ -29,6 +29,10 @@ export function resolveRuntimeProcess(options = {}, embedded = {
         processMode: 'cli',
     };
 }
+export function toSafeInvokeTraceOptions(options) {
+    const { collaborationAuth: _collaborationAuth, ...traceOptions } = options;
+    return traceOptions;
+}
 /**
  * Internal runtime that delegates operations to a persistent host transport.
  *
@@ -57,7 +61,7 @@ export class SuperDocRuntime {
             phase: 'start',
             operationId: operation.operationId,
             params,
-            options,
+            options: toSafeInvokeTraceOptions(options),
         });
         try {
             const result = await this.transport.invoke(operation, params, options);

package/dist/runtime/sdk-version.generated.cjs

@@ -3,6 +3,6 @@
 // AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
 // Source of truth: package.json. Regenerated on every SDK build so the
 // SDK retains its own version identity when bundled into another package.
-const SDK_VERSION = '2.8.0';
+const SDK_VERSION = '2.9.0-next.1';
 
 exports.SDK_VERSION = SDK_VERSION;

package/dist/runtime/sdk-version.generated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.8.0";
+export declare const SDK_VERSION = "2.9.0-next.1";

package/dist/runtime/sdk-version.generated.js

@@ -1,4 +1,4 @@
 // AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
 // Source of truth: package.json. Regenerated on every SDK build so the
 // SDK retains its own version identity when bundled into another package.
-export const SDK_VERSION = '2.8.0';
+export const SDK_VERSION = '2.9.0-next.1';

package/dist/runtime/transport-common.cjs

@@ -2,6 +2,27 @@
 
 var errors = require('./errors.cjs');
 
+function normalizeCollaborationAuth(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new errors.SuperDocCliError('collaborationAuth must be an object.', { code: 'INVALID_ARGUMENT' });
+    }
+    const record = value;
+    const unknownField = Object.keys(record).find((key) => key !== 'type' && key !== 'token');
+    if (unknownField) {
+        throw new errors.SuperDocCliError(`collaborationAuth.${unknownField} is not supported.`, {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (record.type !== 'token') {
+        throw new errors.SuperDocCliError('collaborationAuth.type must be "token".', { code: 'INVALID_ARGUMENT' });
+    }
+    if (typeof record.token !== 'string' || record.token.length === 0) {
+        throw new errors.SuperDocCliError('collaborationAuth.token must be a non-empty string.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    return { type: 'token', token: record.token };
+}
 function hasExtension(filePath, extension) {
     return filePath.toLowerCase().endsWith(extension);
 }
@@ -165,4 +186,5 @@ function buildOperationArgv(operation, params, options, runtimeTimeoutMs, defaul
 
 exports.applyOperationParamAliases = applyOperationParamAliases;
 exports.buildOperationArgv = buildOperationArgv;
+exports.normalizeCollaborationAuth = normalizeCollaborationAuth;
 exports.resolveInvocation = resolveInvocation;

package/dist/runtime/transport-common.d.ts

@@ -19,6 +19,17 @@ export interface InvokeOptions {
     expectedRevision?: string | number;
     changeMode?: ChangeMode;
 }
+export interface CollaborationAuth {
+    type: 'token';
+    token: string;
+}
+export interface DocOpenOptions extends InvokeOptions {
+    collaborationAuth?: CollaborationAuth;
+}
+export interface TransportInvokeOptions extends InvokeOptions {
+    collaborationAuth?: CollaborationAuth;
+}
+export declare function normalizeCollaborationAuth(value: unknown): CollaborationAuth;
 /**
  * Minimal invoke interface that both SuperDocRuntime and BoundRuntime satisfy.
  * Generated code depends on this interface, not on the concrete runtime class.

package/dist/runtime/transport-common.js

@@ -1,4 +1,25 @@
 import { SuperDocCliError } from './errors.js';
+export function normalizeCollaborationAuth(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new SuperDocCliError('collaborationAuth must be an object.', { code: 'INVALID_ARGUMENT' });
+    }
+    const record = value;
+    const unknownField = Object.keys(record).find((key) => key !== 'type' && key !== 'token');
+    if (unknownField) {
+        throw new SuperDocCliError(`collaborationAuth.${unknownField} is not supported.`, {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (record.type !== 'token') {
+        throw new SuperDocCliError('collaborationAuth.type must be "token".', { code: 'INVALID_ARGUMENT' });
+    }
+    if (typeof record.token !== 'string' || record.token.length === 0) {
+        throw new SuperDocCliError('collaborationAuth.token must be a non-empty string.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    return { type: 'token', token: record.token };
+}
 function hasExtension(filePath, extension) {
     return filePath.toLowerCase().endsWith(extension);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/sdk",
-  "version": "2.8.0",
+  "version": "2.9.0-next.1",
   "description": "Node SDK for SuperDoc, wrapping the SuperDoc CLI to read and edit .docx files from JavaScript and TypeScript.",
   "private": false,
   "license": "AGPL-3.0",
@@ -37,19 +37,20 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@superdoc/sdk-darwin-arm64": "2.8.0",
-    "@superdoc/sdk-darwin-x64": "2.8.0",
-    "@superdoc/sdk-linux-x64": "2.8.0",
-    "@superdoc/sdk-linux-arm64": "2.8.0",
-    "@superdoc/sdk-windows-x64": "2.8.0"
+    "@superdoc/sdk-darwin-arm64": "2.9.0-next.1",
+    "@superdoc/sdk-darwin-x64": "2.9.0-next.1",
+    "@superdoc/sdk-linux-x64": "2.9.0-next.1",
+    "@superdoc/sdk-linux-arm64": "2.9.0-next.1",
+    "@superdoc/sdk-windows-x64": "2.9.0-next.1"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "rm -rf dist && node scripts/embed-version.mjs && node scripts/embed-prompts.mjs && node scripts/embed-tools.mjs && tsc && rollup -c rollup.cjs.config.mjs && rm -rf dist/prompts && mkdir -p dist/prompts && cp src/prompts/*.md dist/prompts/ && pnpm run audit:publish",
+    "build": "rm -rf dist && node scripts/embed-version.mjs && node scripts/embed-prompts.mjs && node scripts/embed-tools.mjs && tsc && pnpm run typecheck:consumer && rollup -c rollup.cjs.config.mjs && rm -rf dist/prompts && mkdir -p dist/prompts && cp src/prompts/*.md dist/prompts/ && pnpm run audit:publish",
     "audit:publish": "node ../../../../scripts/audit-publish-artifact.mjs dist --label sdk-node-dist",
     "typecheck": "tsc --noEmit",
+    "typecheck:consumer": "tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext ../../../../tests/consumer-typecheck/src/sdk-per-open-collaboration-auth.mts",
     "test:document-host": "bun test src/runtime/__tests__/host-spawn-args.test.ts src/runtime/__tests__/document-rpc.test.ts src/__tests__/structured-document-rpc.e2e.test.ts src/__tests__/request-timeout-ms.e2e.test.ts",
     "smoke:product-action": "node scripts/product-action-smoke.mjs"
   }