@superdoc/sdk 2.6.0 → 2.8.0

package/dist/runtime/host.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 import { buildOperationArgv, resolveInvocation, } from './transport-common.js';
 import { SuperDocCliError } from './errors.js';
-import { DOCUMENT_RPC_FEATURES, buildDocumentInvokeParams, buildDocumentOpenParams, canOpenWithDocumentRpc, documentRpcEnabled, mapDocumentLifecycleResult, mapDocumentOpenResult, supportsDocumentRpc, } from './document-rpc.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'];
 const DOCUMENT_HOST_REQUIRED_FEATURES = [...DOCUMENT_RPC_FEATURES, 'host.shutdown'];
@@ -20,6 +20,21 @@ const HOST_DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 // abort. The buffer absorbs JSON-RPC serialization, stdio drain, and event-
 // loop latency.
 const WATCHDOG_HEADROOM_MS = 5_000;
+export function mapCliInvocationResult(operation, value) {
+    const envelopeKey = operation.responseEnvelopeKey;
+    if (envelopeKey === null || envelopeKey === undefined)
+        return value;
+    if (typeof envelopeKey !== 'string' || envelopeKey.length === 0) {
+        throw new SuperDocCliError('Generated operation has invalid response envelope metadata.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { operationId: operation.operationId, responseEnvelopeKey: envelopeKey },
+        });
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return value;
+    const extracted = value[envelopeKey];
+    return extracted === undefined ? value : extracted;
+}
 /**
  * Builds the argv passed to `spawn` for `superdoc host --stdio`. Propagates
  * `requestTimeoutMs` to the host via `--request-timeout-ms`, since the SDK
@@ -80,9 +95,15 @@ export class HostTransport {
     pending = new Map();
     nextRequestId = 1;
     connecting = null;
+    disposePromise = null;
+    terminalDisposalError = null;
     stopping = false;
+    activeCalls = new Set();
     hostFeatures = new Set();
     documentRpcSessions = new Set();
+    dirtyDocumentRpcSessions = new Set();
+    documentRpcMutationStates = new Map();
+    indeterminateDiscardCloses = new Set();
     constructor(options) {
         this.hostBin = options.hostBin;
         this.processMode = options.processMode ?? 'cli';
@@ -98,22 +119,48 @@ export class HostTransport {
                 details: { defaultChangeMode: options.defaultChangeMode },
             });
         }
-        this.defaultChangeMode = options.defaultChangeMode;
+        this.defaultChangeMode = options.defaultChangeMode ?? undefined;
         this.user = options.user;
-        this.documentRpcEnabled = documentRpcEnabled(options.env);
-        if (this.processMode === 'document' && !this.documentRpcEnabled) {
-            throw new SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN requires SUPERDOC_SDK_DOCUMENT_RPC=1.', {
-                code: 'INVALID_ARGUMENT',
-            });
-        }
+        this.documentRpcEnabled = this.processMode === 'document' || documentRpcEnabled(options.env);
     }
     async connect() {
-        await this.ensureConnected();
+        await this.runWhileActive(() => this.ensureConnected());
     }
     async dispose() {
-        if (!this.child)
+        if (this.disposePromise)
+            return this.disposePromise;
+        if (this.terminalDisposalError)
+            throw this.terminalDisposalError;
+        if (!this.child && !this.connecting && this.activeCalls.size === 0)
             return;
         this.stopping = true;
+        const disposal = this.disposeAfterActiveCalls();
+        this.disposePromise = disposal;
+        try {
+            await disposal;
+        }
+        finally {
+            if (this.disposePromise === disposal)
+                this.disposePromise = null;
+            this.stopping = false;
+        }
+    }
+    async disposeAfterActiveCalls() {
+        await Promise.allSettled(Array.from(this.activeCalls));
+        if (this.terminalDisposalError)
+            throw this.terminalDisposalError;
+        if (!this.child)
+            return;
+        try {
+            await this.reconcileIndeterminateDiscardCloses();
+            await this.persistDirtyDocumentRpcSessions();
+        }
+        catch (error) {
+            if (!this.child && error instanceof SuperDocCliError) {
+                this.terminalDisposalError = error;
+            }
+            throw error;
+        }
         const child = this.child;
         try {
             await this.sendJsonRpcRequest('host.shutdown', {}, this.shutdownTimeoutMs);
@@ -132,29 +179,80 @@ export class HostTransport {
             });
         });
         this.cleanupProcess(null);
-        this.stopping = false;
     }
     async invoke(operation, params = {}, options = {}) {
+        return this.runWhileActive(() => this.invokeWhileActive(operation, params, options));
+    }
+    async invokeWhileActive(operation, params, options) {
         await this.ensureConnected();
+        const shouldOpenThroughCliTimeoutFallback = this.processMode === 'cli' &&
+            (this.requestTimeoutMs !== undefined ||
+                (options.timeoutMs !== undefined && !this.hostFeatures.has(DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE)));
         if (this.documentRpcEnabled &&
             supportsDocumentRpc(this.hostFeatures) &&
-            this.defaultChangeMode === undefined &&
-            this.user === undefined &&
+            (this.defaultChangeMode === undefined || this.hostFeatures.has(DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE)) &&
             operation.operationId === 'doc.open' &&
-            canOpenWithDocumentRpc(params, options)) {
-            const opened = buildDocumentOpenParams(params);
-            const response = await this.sendJsonRpcRequest('document.open', opened.params, this.resolveWatchdogTimeout(options.timeoutMs));
+            canOpenWithDocumentRpc(params, options) &&
+            !shouldOpenThroughCliTimeoutFallback) {
+            const opened = buildDocumentOpenParams(params, this.user, this.defaultChangeMode);
+            const requestTimeoutMs = this.resolveDocumentRequestTimeout(options.timeoutMs);
+            const response = await this.sendJsonRpcRequest('document.open', opened.params, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
             const result = mapDocumentOpenResult(response, opened.sessionId, params.doc);
             this.documentRpcSessions.add(opened.sessionId);
+            this.indeterminateDiscardCloses.delete(opened.sessionId);
             return result;
         }
         const sessionId = typeof params.sessionId === 'string' ? params.sessionId : undefined;
         if (sessionId !== undefined && this.documentRpcSessions.has(sessionId)) {
-            const request = buildDocumentInvokeParams(sessionId, operation, params, options);
-            const response = await this.sendJsonRpcRequest(request.method, request.params, this.resolveWatchdogTimeout(options.timeoutMs));
-            const result = mapDocumentLifecycleResult(operation.operationId, response, sessionId);
-            if (operation.operationId === 'doc.close')
+            const request = buildDocumentInvokeParams(sessionId, operation, params, options, this.hostFeatures);
+            const supportsResponseTimeout = documentRpcRequestSupportsResponseTimeout(operation, request);
+            const requestTimeoutMs = supportsResponseTimeout
+                ? this.resolveDocumentRequestTimeout(options.timeoutMs)
+                : undefined;
+            const documentOperation = operation;
+            const requestOptions = typeof request.params.options === 'object' &&
+                request.params.options !== null &&
+                !Array.isArray(request.params.options)
+                ? request.params.options
+                : undefined;
+            const tracksMutation = request.method === 'document.invoke' && documentOperation.mutates === true && requestOptions?.dryRun !== true;
+            if (tracksMutation)
+                this.beginDocumentRpcMutation(sessionId);
+            let result;
+            try {
+                const response = await this.sendJsonRpcRequest(request.method, request.params, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
+                result = mapDocumentLifecycleResult(operation.operationId, response, sessionId, operation.operationId === 'doc.save' ? request.params.path === undefined : undefined);
+            }
+            catch (error) {
+                if (tracksMutation) {
+                    const indeterminate = error instanceof SuperDocCliError && ['TIMEOUT', 'HOST_TIMEOUT', 'HOST_DISCONNECTED'].includes(error.code);
+                    this.settleDocumentRpcMutation(sessionId, indeterminate ? 'indeterminate' : 'not-applied');
+                }
+                if (operation.operationId === 'doc.close' &&
+                    request.params.discard === true &&
+                    error instanceof SuperDocCliError &&
+                    error.code === 'TIMEOUT') {
+                    this.indeterminateDiscardCloses.add(sessionId);
+                }
+                throw error;
+            }
+            if (tracksMutation) {
+                const failedReceipt = typeof result === 'object' &&
+                    result !== null &&
+                    !Array.isArray(result) &&
+                    result.success === false;
+                this.settleDocumentRpcMutation(sessionId, failedReceipt ? 'not-applied' : 'applied');
+            }
+            if (operation.operationId === 'doc.close') {
                 this.documentRpcSessions.delete(sessionId);
+                this.clearDirtyDocumentRpcSession(sessionId);
+                this.indeterminateDiscardCloses.delete(sessionId);
+            }
+            else if (operation.operationId === 'doc.save') {
+                if (request.params.mode === undefined || request.params.mode === 'review-preserving') {
+                    this.markDocumentRpcSessionSaved(sessionId);
+                }
+            }
             return result;
         }
         if (this.processMode === 'document') {
@@ -163,6 +261,18 @@ export class HostTransport {
                 details: { operationId: operation.operationId },
             });
         }
+        const cliHostRequestTimeoutMs = this.requestTimeoutMs ?? HOST_DEFAULT_REQUEST_TIMEOUT_MS;
+        if (options.timeoutMs !== undefined && options.timeoutMs > cliHostRequestTimeoutMs) {
+            throw new SuperDocCliError(`CLI host cannot honor timeoutMs=${options.timeoutMs} above its ${cliHostRequestTimeoutMs}ms request ceiling.`, {
+                code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+                details: {
+                    feature: DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE,
+                    operationId: operation.operationId,
+                    timeoutMs: options.timeoutMs,
+                    hostRequestTimeoutMs: cliHostRequestTimeoutMs,
+                },
+            });
+        }
         const argv = buildOperationArgv(operation, params, options, this.requestTimeoutMs, this.defaultChangeMode, this.user);
         const stdinBase64 = options.stdinBytes ? Buffer.from(options.stdinBytes).toString('base64') : '';
         const watchdogTimeout = this.resolveWatchdogTimeout(options.timeoutMs);
@@ -177,7 +287,21 @@ export class HostTransport {
             });
         }
         const resultRecord = response;
-        return resultRecord.data;
+        return mapCliInvocationResult(operation, resultRecord.data);
+    }
+    runWhileActive(start) {
+        if (this.terminalDisposalError) {
+            return Promise.reject(this.terminalDisposalError);
+        }
+        if (this.stopping) {
+            return Promise.reject(new SuperDocCliError('Host is disposing.', {
+                code: 'HOST_DISCONNECTED',
+            }));
+        }
+        const activeCall = start();
+        this.activeCalls.add(activeCall);
+        void activeCall.then(() => this.activeCalls.delete(activeCall), () => this.activeCalls.delete(activeCall));
+        return activeCall;
     }
     async ensureConnected() {
         if (this.connecting) {
@@ -203,7 +327,7 @@ export class HostTransport {
         const child = spawn(command, args, {
             env: {
                 ...process.env,
-                ...(this.env ?? {}),
+                ...this.env,
             },
             stdio: ['pipe', 'pipe', 'pipe'],
         });
@@ -231,7 +355,7 @@ export class HostTransport {
             }));
         });
         child.on('close', (code, signal) => {
-            if (this.stopping) {
+            if (this.stopping && this.dirtyDocumentRpcSessions.size === 0) {
                 this.cleanupProcess(null);
                 return;
             }
@@ -282,7 +406,13 @@ export class HostTransport {
                 details: { features },
             });
         }
-        const requiredFeatures = this.processMode === 'document' ? DOCUMENT_HOST_REQUIRED_FEATURES : CLI_HOST_REQUIRED_FEATURES;
+        const requiredFeatures = this.processMode === 'document'
+            ? [
+                ...DOCUMENT_HOST_REQUIRED_FEATURES,
+                ...(this.defaultChangeMode === undefined ? [] : [DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE]),
+                ...(this.requestTimeoutMs === undefined ? [] : [DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE]),
+            ]
+            : CLI_HOST_REQUIRED_FEATURES;
         for (const requiredFeature of requiredFeatures) {
             if (!features.includes(requiredFeature)) {
                 throw new SuperDocCliError(`Host does not support required feature: ${requiredFeature}`, {
@@ -298,7 +428,79 @@ export class HostTransport {
     resolveWatchdogTimeout(timeoutMsOverride) {
         return resolveJsWatchdogTimeout(this.watchdogTimeoutMs, this.requestTimeoutMs, timeoutMsOverride);
     }
-    async sendJsonRpcRequest(method, params, watchdogTimeoutMs) {
+    resolveDocumentRequestTimeout(timeoutMsOverride) {
+        const requestTimeoutMs = timeoutMsOverride ?? this.requestTimeoutMs;
+        if (requestTimeoutMs === undefined)
+            return undefined;
+        if (this.hostFeatures.has(DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE))
+            return requestTimeoutMs;
+        if (this.processMode === 'cli' && timeoutMsOverride === undefined)
+            return undefined;
+        throw new SuperDocCliError(`Structured document RPC host does not support ${DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE}.`, {
+            code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+            details: { feature: DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE },
+        });
+    }
+    beginDocumentRpcMutation(sessionId) {
+        const state = this.documentRpcMutationStates.get(sessionId) ?? {
+            confirmedDirty: this.dirtyDocumentRpcSessions.has(sessionId),
+            pendingCount: 0,
+        };
+        state.pendingCount += 1;
+        this.documentRpcMutationStates.set(sessionId, state);
+        this.dirtyDocumentRpcSessions.add(sessionId);
+    }
+    settleDocumentRpcMutation(sessionId, outcome) {
+        const state = this.documentRpcMutationStates.get(sessionId);
+        if (!state)
+            return;
+        state.pendingCount = Math.max(0, state.pendingCount - 1);
+        if (outcome !== 'not-applied')
+            state.confirmedDirty = true;
+        if (state.confirmedDirty || state.pendingCount > 0) {
+            this.dirtyDocumentRpcSessions.add(sessionId);
+            return;
+        }
+        this.clearDirtyDocumentRpcSession(sessionId);
+    }
+    clearDirtyDocumentRpcSession(sessionId) {
+        this.dirtyDocumentRpcSessions.delete(sessionId);
+        this.documentRpcMutationStates.delete(sessionId);
+    }
+    markDocumentRpcSessionSaved(sessionId) {
+        const state = this.documentRpcMutationStates.get(sessionId);
+        if (!state || state.pendingCount === 0) {
+            this.clearDirtyDocumentRpcSession(sessionId);
+            return;
+        }
+        state.confirmedDirty = false;
+        this.dirtyDocumentRpcSessions.add(sessionId);
+    }
+    async persistDirtyDocumentRpcSessions() {
+        if (this.dirtyDocumentRpcSessions.size === 0)
+            return;
+        if (!this.hostFeatures.has(DOCUMENT_RPC_SOURCE_SAVE_FEATURE)) {
+            throw new SuperDocCliError('Document host cannot persist dirty sessions during client disposal because it does not support source saves.', {
+                code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+                details: { feature: DOCUMENT_RPC_SOURCE_SAVE_FEATURE },
+            });
+        }
+        for (const sessionId of this.dirtyDocumentRpcSessions) {
+            const response = await this.sendJsonRpcRequest('document.save', { sessionId }, this.resolveWatchdogTimeout(undefined));
+            mapDocumentLifecycleResult('doc.save', response, sessionId, true);
+            this.markDocumentRpcSessionSaved(sessionId);
+        }
+    }
+    async reconcileIndeterminateDiscardCloses() {
+        for (const sessionId of this.indeterminateDiscardCloses) {
+            const response = await this.sendJsonRpcRequest('document.close', { sessionId, discard: true }, this.resolveWatchdogTimeout(undefined));
+            mapDocumentLifecycleResult('doc.close', response, sessionId);
+            this.documentRpcSessions.delete(sessionId);
+            this.clearDirtyDocumentRpcSession(sessionId);
+            this.indeterminateDiscardCloses.delete(sessionId);
+        }
+    }
+    async sendJsonRpcRequest(method, params, watchdogTimeoutMs, metadata = {}) {
         const child = this.child;
         if (!child || !child.stdin.writable) {
             throw new SuperDocCliError('Host process is not available.', {
@@ -318,6 +520,7 @@ export class HostTransport {
             id,
             method,
             params,
+            ...(metadata.requestTimeoutMs === undefined ? {} : { requestTimeoutMs: metadata.requestTimeoutMs }),
         });
         const promise = new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
@@ -428,8 +631,17 @@ export class HostTransport {
         this.cleanupProcess(error);
     }
     cleanupProcess(error) {
+        if (error && this.dirtyDocumentRpcSessions.size > 0 && !this.terminalDisposalError) {
+            this.terminalDisposalError = new SuperDocCliError('Document host disconnected before dirty sessions could be persisted.', {
+                code: 'HOST_DISCONNECTED',
+                details: { causeCode: error.code, causeDetails: error.details },
+            });
+        }
         this.hostFeatures.clear();
         this.documentRpcSessions.clear();
+        this.dirtyDocumentRpcSessions.clear();
+        this.documentRpcMutationStates.clear();
+        this.indeterminateDiscardCloses.clear();
         const child = this.child;
         if (child) {
             child.removeAllListeners();

package/dist/runtime/process.cjs

@@ -2,9 +2,36 @@
 
 var host = require('./host.cjs');
 var embeddedCli = require('./embedded-cli.cjs');
+var embeddedDocumentHost = require('./embedded-document-host.cjs');
 var debugTrace = require('./debug-trace.cjs');
 var errors = require('./errors.cjs');
 
+function resolveRuntimeProcess(options = {}, embedded = {
+    cli: embeddedCli.resolveEmbeddedCliBinary,
+    documentHost: embeddedDocumentHost.resolveEmbeddedDocumentHostBinary,
+}) {
+    const configuredDocumentHostPath = options.documentHostPath;
+    if (configuredDocumentHostPath !== undefined && configuredDocumentHostPath.trim().length === 0) {
+        throw new errors.SuperDocCliError('documentHostPath must be a non-empty path.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    const configuredDocumentHostBin = options.env?.SUPERDOC_SDK_DOCUMENT_HOST_BIN ?? process.env.SUPERDOC_SDK_DOCUMENT_HOST_BIN;
+    const documentHostBin = configuredDocumentHostPath ??
+        (configuredDocumentHostBin === 'embedded' ? embedded.documentHost() : configuredDocumentHostBin);
+    if (documentHostBin !== undefined && documentHostBin.trim().length === 0) {
+        throw new errors.SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN must be a non-empty path.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (documentHostBin !== undefined) {
+        return { hostBin: documentHostBin, processMode: 'document' };
+    }
+    return {
+        hostBin: options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? embedded.cli(),
+        processMode: 'cli',
+    };
+}
 /**
  * Internal runtime that delegates operations to a persistent host transport.
  *
@@ -14,17 +41,10 @@ var errors = require('./errors.cjs');
 class SuperDocRuntime {
     transport;
     constructor(options = {}) {
-        const documentHostBin = options.env?.SUPERDOC_SDK_DOCUMENT_HOST_BIN ?? process.env.SUPERDOC_SDK_DOCUMENT_HOST_BIN;
-        if (documentHostBin !== undefined && documentHostBin.trim().length === 0) {
-            throw new errors.SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN must be a non-empty path.', {
-                code: 'INVALID_ARGUMENT',
-            });
-        }
-        const hostBin = documentHostBin ?? options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? embeddedCli.resolveEmbeddedCliBinary();
+        const runtimeProcess = resolveRuntimeProcess(options);
         this.transport = new host.HostTransport({
             ...options,
-            hostBin,
-            processMode: documentHostBin === undefined ? 'cli' : 'document',
+            ...runtimeProcess,
         });
     }
     async connect() {
@@ -67,3 +87,4 @@ class SuperDocRuntime {
 }
 
 exports.SuperDocRuntime = SuperDocRuntime;
+exports.resolveRuntimeProcess = resolveRuntimeProcess;

package/dist/runtime/process.d.ts

@@ -1,4 +1,13 @@
 import type { DocumentRuntimeKind, InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions } from './transport-common.js';
+type RuntimeProcessResolution = {
+    hostBin: string;
+    processMode: 'cli' | 'document';
+};
+type EmbeddedRuntimeResolvers = {
+    cli: () => string;
+    documentHost: () => string;
+};
+export declare function resolveRuntimeProcess(options?: SuperDocClientOptions, embedded?: EmbeddedRuntimeResolvers): RuntimeProcessResolution;
 /**
  * Internal runtime that delegates operations to a persistent host transport.
  *

package/dist/runtime/process.js

@@ -1,7 +1,34 @@
 import { HostTransport } from './host.js';
 import { resolveEmbeddedCliBinary } from './embedded-cli.js';
+import { resolveEmbeddedDocumentHostBinary } from './embedded-document-host.js';
 import { writeSdkDebugTrace } from './debug-trace.js';
 import { SuperDocCliError } from './errors.js';
+export function resolveRuntimeProcess(options = {}, embedded = {
+    cli: resolveEmbeddedCliBinary,
+    documentHost: resolveEmbeddedDocumentHostBinary,
+}) {
+    const configuredDocumentHostPath = options.documentHostPath;
+    if (configuredDocumentHostPath !== undefined && configuredDocumentHostPath.trim().length === 0) {
+        throw new SuperDocCliError('documentHostPath must be a non-empty path.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    const configuredDocumentHostBin = options.env?.SUPERDOC_SDK_DOCUMENT_HOST_BIN ?? process.env.SUPERDOC_SDK_DOCUMENT_HOST_BIN;
+    const documentHostBin = configuredDocumentHostPath ??
+        (configuredDocumentHostBin === 'embedded' ? embedded.documentHost() : configuredDocumentHostBin);
+    if (documentHostBin !== undefined && documentHostBin.trim().length === 0) {
+        throw new SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN must be a non-empty path.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (documentHostBin !== undefined) {
+        return { hostBin: documentHostBin, processMode: 'document' };
+    }
+    return {
+        hostBin: options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? embedded.cli(),
+        processMode: 'cli',
+    };
+}
 /**
  * Internal runtime that delegates operations to a persistent host transport.
  *
@@ -11,17 +38,10 @@ import { SuperDocCliError } from './errors.js';
 export class SuperDocRuntime {
     transport;
     constructor(options = {}) {
-        const documentHostBin = options.env?.SUPERDOC_SDK_DOCUMENT_HOST_BIN ?? process.env.SUPERDOC_SDK_DOCUMENT_HOST_BIN;
-        if (documentHostBin !== undefined && documentHostBin.trim().length === 0) {
-            throw new SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN must be a non-empty path.', {
-                code: 'INVALID_ARGUMENT',
-            });
-        }
-        const hostBin = documentHostBin ?? options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? resolveEmbeddedCliBinary();
+        const runtimeProcess = resolveRuntimeProcess(options);
         this.transport = new HostTransport({
             ...options,
-            hostBin,
-            processMode: documentHostBin === undefined ? 'cli' : 'document',
+            ...runtimeProcess,
         });
     }
     async connect() {

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

@@ -0,0 +1,8 @@
+'use strict';
+
+// 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';
+
+exports.SDK_VERSION = SDK_VERSION;

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

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "2.8.0";

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

@@ -0,0 +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';

package/dist/runtime/transport-common.cjs

@@ -163,5 +163,6 @@ function buildOperationArgv(operation, params, options, runtimeTimeoutMs, defaul
     return argv;
 }
 
+exports.applyOperationParamAliases = applyOperationParamAliases;
 exports.buildOperationArgv = buildOperationArgv;
 exports.resolveInvocation = resolveInvocation;

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

@@ -34,6 +34,14 @@ export interface UserIdentity {
 }
 export interface SuperDocClientOptions {
     env?: Record<string, string | undefined>;
+    /**
+     * Standalone document-host entry to use instead of the embedded CLI.
+     *
+     * The host-only path supports local lifecycle methods and generated Document
+     * API operations through structured RPC. Interface-only conveniences fail
+     * without CLI fallback.
+     */
+    documentHostPath?: string;
     /**
      * Default document engine for `client.open(...)`. Explicit `runtime` on an
      * individual open call takes precedence.
@@ -42,11 +50,13 @@ export interface SuperDocClientOptions {
     startupTimeoutMs?: number;
     shutdownTimeoutMs?: number;
     /**
-     * Upper bound (ms) on how long the host process may spend on a single
-     * `cli.invoke` request before it kills the operation and returns a
-     * `RequestTimeout` error. Propagated to the host via `--request-timeout-ms`
-     * at spawn. Raise this for documents that legitimately need more than 30s
-     * to process; the SDK widens its own JSON-RPC watchdog to match.
+     * Upper bound (ms) on how long the host process may spend on a request
+     * before it returns a `RequestTimeout` error. Retry-safe structured document
+     * requests carry this budget as transport metadata; requests that may apply
+     * non-idempotent side effects await a definitive result instead. CLI-host
+     * requests also receive the budget through `--request-timeout-ms` at spawn.
+     * Raise this for documents that legitimately need more than 30s to process;
+     * the SDK widens its own JSON-RPC watchdog to match.
      *
      * Defaults to the host's own default (30s) when unset.
      */
@@ -54,11 +64,13 @@ export interface SuperDocClientOptions {
     /**
      * JS-side watchdog (ms) the SDK waits for a host reply before giving up.
      * Independent of {@link requestTimeoutMs} (which controls the host-side
-     * operation budget). Most callers should leave this at its default and use
-     * {@link requestTimeoutMs} as the single operation-timeout knob —
-     * `resolveWatchdogTimeout` already widens the watchdog above the host
-     * ceiling automatically. Override only when you need to detect a hung or
-     * crashed host faster than the operation budget allows.
+     * operation budget). Structured requests that may apply non-idempotent side
+     * effects wait for a definitive host result instead of applying an unsafe
+     * response deadline. Most callers should leave this at its default and use
+     * {@link requestTimeoutMs} as the single timeout knob for retry-safe work —
+     * `resolveWatchdogTimeout` already widens the watchdog above the host ceiling
+     * automatically. Override only when you need to detect a hung or crashed host
+     * faster than the operation budget allows.
      */
     watchdogTimeoutMs?: number;
     maxQueueDepth?: number;
@@ -70,6 +82,12 @@ export interface CliInvocation {
     prefixArgs: string[];
 }
 export declare function resolveInvocation(cliBin: string): CliInvocation;
+/**
+ * Resolve contract-shaped param aliases onto their canonical generated names.
+ * Returns the same object when no alias applies. Throws on a conflicting
+ * canonical/alias pair so divergent values can never be silently coalesced.
+ */
+export declare function applyOperationParamAliases(operation: OperationSpec, params: Record<string, unknown>): Record<string, unknown>;
 /**
  * Build the CLI argument vector for an operation invocation.
  *

package/dist/runtime/transport-common.js

@@ -54,7 +54,7 @@ function assertKnownTemplatesApplyParams(operation, params) {
  * Returns the same object when no alias applies. Throws on a conflicting
  * canonical/alias pair so divergent values can never be silently coalesced.
  */
-function applyOperationParamAliases(operation, params) {
+export function applyOperationParamAliases(operation, params) {
     const aliasMap = OPERATION_PARAM_ALIASES[operation.operationId];
     if (!aliasMap)
         return params;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/sdk",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "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,17 +37,17 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@superdoc/sdk-darwin-arm64": "2.6.0",
-    "@superdoc/sdk-linux-x64": "2.6.0",
-    "@superdoc/sdk-darwin-x64": "2.6.0",
-    "@superdoc/sdk-linux-arm64": "2.6.0",
-    "@superdoc/sdk-windows-x64": "2.6.0"
+    "@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"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "rm -rf dist && 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 && 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",
     "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",

package/tools/tools-policy.json

@@ -43,5 +43,5 @@
       "mutates": true
     }
   ],
-  "contractHash": "5967b3cb6c6ca5f65dd887d1c3b2908478e47ac6a2b76f7b2bb207f3b5b21324"
+  "contractHash": "570f35bff614f42af4610ad37ad4d21d776cdf8e3515c206d25d50c0102d7484"
 }