@superdoc/sdk 2.10.0-next.4 → 2.10.0-next.6

package/dist/agent/runtime.js

@@ -1,7 +1,7 @@
 import { CONTRACT } from '../generated/contract.js';
 import { SuperDocCliError } from '../runtime/errors.js';
 import { validatePlan } from './ir.js';
-import { buildDocumentSnapshot, resolveSnapshotSelector, AmbiguousSelectorError, } from './doc-snapshot.js';
+import { buildDocumentSnapshot, buildMutationSnapshot, resolveSnapshotSelector, AmbiguousSelectorError, MutationSnapshotError, } from './doc-snapshot.js';
 import { getOperationCatalogEntry } from './operation-catalog.js';
 const RESERVED_ARG_KEYS = new Set(['sessionId', 'doc']);
 function ensureKnownOperation(operationId) {
@@ -224,8 +224,8 @@ function computeDeltaChecks(pre, post, checks, saveReopen) {
         else if (check.kind === 'comment-count-delta') {
             results.push({
                 check,
-                passed: post.comments.length - pre.comments.length === check.delta,
-                detail: `pre=${pre.comments.length} post=${post.comments.length}`,
+                passed: post.counts.comments - pre.counts.comments === check.delta,
+                detail: `pre=${pre.counts.comments} post=${post.counts.comments}`,
             });
         }
         else if (check.kind === 'tracked-change-count-delta') {
@@ -310,7 +310,7 @@ async function trySaveReopen(doc, checks) {
         await saveAny.call(doc, {});
         // Rebuild a fresh snapshot after save. Host-level true reopen still needs
         // a new document handle, which this runtime cannot force on its own.
-        const fresh = await buildDocumentSnapshot(doc);
+        const fresh = await buildMutationSnapshot(doc);
         for (const check of checks) {
             if (check.kind === 'save-reopen-text-contains') {
                 const found = fresh.blocks.some((b) => b.text.includes(check.text));
@@ -347,7 +347,23 @@ export async function agentApply(doc, args) {
             errors: validation.errors.map((e) => ({ code: e.code, message: e.message })),
         };
     }
-    const preSnapshot = await buildDocumentSnapshot(doc);
+    let preSnapshot;
+    try {
+        preSnapshot = await buildMutationSnapshot(doc);
+    }
+    catch (error) {
+        if (!(error instanceof MutationSnapshotError))
+            throw error;
+        return {
+            status: 'failed',
+            intent: plan.intent,
+            preSnapshot: { revision: 'unknown', counts: emptyCounts() },
+            selectedTargets: [],
+            executedOperations: [],
+            verification: [],
+            errors: [{ code: error.code, message: error.message, recovery: { kind: 'retry' } }],
+        };
+    }
     const selectedTargets = [];
     const executedOperations = [];
     const bindings = new Map();
@@ -412,7 +428,23 @@ export async function agentApply(doc, args) {
             errors: [{ code: 'APPLY_FAILED', message }],
         };
     }
-    const postSnapshot = await buildDocumentSnapshot(doc);
+    let postSnapshot;
+    try {
+        postSnapshot = await buildMutationSnapshot(doc);
+    }
+    catch (error) {
+        if (!(error instanceof MutationSnapshotError))
+            throw error;
+        return {
+            status: 'failed',
+            intent: plan.intent,
+            preSnapshot: { revision: preSnapshot.revision, counts: preSnapshot.counts },
+            selectedTargets,
+            executedOperations,
+            verification: [],
+            errors: [{ code: error.code, message: error.message, recovery: { kind: 'reinspect' } }],
+        };
+    }
     const verifyStep = plan.steps.find((s) => s.kind === 'verify');
     let saveReopen;
     const shouldSaveReopen = (verifyStep?.kind === 'verify' && (verifyStep.saveReopen || verificationNeedsSaveReopen(verifyStep.checks))) ||
@@ -434,7 +466,23 @@ export async function agentApply(doc, args) {
     };
 }
 export async function agentVerify(doc, args) {
-    const snapshot = await buildDocumentSnapshot(doc);
+    let snapshot;
+    try {
+        snapshot = await buildMutationSnapshot(doc);
+    }
+    catch (error) {
+        if (!(error instanceof MutationSnapshotError))
+            throw error;
+        return {
+            status: 'failed',
+            intent: 'verify',
+            preSnapshot: { revision: 'unknown', counts: emptyCounts() },
+            selectedTargets: [],
+            executedOperations: [],
+            verification: [],
+            errors: [{ code: error.code, message: error.message, recovery: { kind: 'retry' } }],
+        };
+    }
     let saveReopen;
     if (args.saveReopen || verificationNeedsSaveReopen(args.checks)) {
         saveReopen = await trySaveReopen(doc, args.checks);

package/dist/generated/contract.cjs

@@ -21,6 +21,7 @@ const CONTRACT = {
                         "document.open",
                         "document.open.defaultChangeMode",
                         "document.currentRevision",
+                        "document.replaceFile",
                         "document.invoke",
                         "document.save",
                         "document.save.source",

package/dist/generated/contract.js

@@ -2905,6 +2905,7 @@ export const CONTRACT = {
             "document.open",
             "document.open.defaultChangeMode",
             "document.currentRevision",
+            "document.replaceFile",
             "document.invoke",
             "document.save",
             "document.save.source",
@@ -2936,6 +2937,7 @@ export const CONTRACT = {
                         "document.open",
                         "document.open.defaultChangeMode",
                         "document.currentRevision",
+                        "document.replaceFile",
                         "document.invoke",
                         "document.save",
                         "document.save.source",

package/dist/index.cjs

@@ -37,6 +37,15 @@ class BoundRuntime {
         }
         return this.runtime.invoke(operation, { ...params, sessionId: this.sessionId }, options);
     }
+    async replaceFile(source, options = {}) {
+        if (this.closed) {
+            throw new errors.SuperDocCliError('Document handle is closed; cannot replace its file.', {
+                code: 'DOCUMENT_CLOSED',
+                details: { sessionId: this.sessionId },
+            });
+        }
+        return this.runtime.replaceFile(this.sessionId, source, options);
+    }
     markClosed() {
         this.closed = true;
     }
@@ -72,6 +81,9 @@ class SuperDocDocumentCore {
     async save(params = {}, options = {}) {
         return this.boundRuntime.invoke(contract.CONTRACT.operations['doc.save'], params, options);
     }
+    async replaceFile(source, options = {}) {
+        return this.boundRuntime.replaceFile(source, options);
+    }
     async close(params = {}, options = {}) {
         const result = await this.boundRuntime.invoke(contract.CONTRACT.operations['doc.close'], params, options);
         this.boundRuntime.markClosed();

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 DocOpenOptions, type InvokeOptions, type OperationSpec, type RuntimeInvoker } from './runtime/process.js';
+import { SuperDocRuntime, type SuperDocClientOptions, type DocOpenOptions, type InvokeOptions, type OperationSpec, type ReplaceFileOptions, type ReplaceFileResult, type ReplaceFileSource, 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.
@@ -12,6 +12,7 @@ declare class BoundRuntime implements RuntimeInvoker {
     private closed;
     constructor(runtime: SuperDocRuntime, sessionId: string);
     invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+    replaceFile(source: ReplaceFileSource, options?: ReplaceFileOptions): Promise<ReplaceFileResult>;
     markClosed(): void;
 }
 export interface DocFormatRangeBoundParams extends Omit<DocFormatApplyBoundParams, 'inline'> {
@@ -33,6 +34,7 @@ declare class SuperDocDocumentCore {
     /** Read-only snapshot of the initial doc.open response metadata. */
     get openResult(): DocOpenResult;
     save(params?: DocSaveBoundParams, options?: InvokeOptions): Promise<DocSaveResult>;
+    replaceFile(source: ReplaceFileSource, options?: ReplaceFileOptions): Promise<ReplaceFileResult>;
     close(params?: DocCloseBoundParams, options?: InvokeOptions): Promise<DocCloseResult>;
     /** @internal */
     markClosed(): void;
@@ -42,6 +44,7 @@ type SuperDocDocumentInstance = SuperDocDocumentCore & BoundDocApi;
 export declare const SuperDocDocument: new (boundRuntime: BoundRuntime, sessionId: string, openResult: DocOpenResult, client: SuperDocClient) => SuperDocDocumentInstance;
 export type SuperDocDocument = SuperDocDocumentInstance;
 export type DocOpenParams = GeneratedDocOpenParams;
+export type { ReplaceFileOptions, ReplaceFileResult, ReplaceFileSource };
 export interface DocDescribeCommandParams {
     operationId: string;
     [key: string]: unknown;

package/dist/index.js

@@ -29,6 +29,15 @@ class BoundRuntime {
         }
         return this.runtime.invoke(operation, { ...params, sessionId: this.sessionId }, options);
     }
+    async replaceFile(source, options = {}) {
+        if (this.closed) {
+            throw new SuperDocCliError('Document handle is closed; cannot replace its file.', {
+                code: 'DOCUMENT_CLOSED',
+                details: { sessionId: this.sessionId },
+            });
+        }
+        return this.runtime.replaceFile(this.sessionId, source, options);
+    }
     markClosed() {
         this.closed = true;
     }
@@ -64,6 +73,9 @@ class SuperDocDocumentCore {
     async save(params = {}, options = {}) {
         return this.boundRuntime.invoke(CONTRACT.operations['doc.save'], params, options);
     }
+    async replaceFile(source, options = {}) {
+        return this.boundRuntime.replaceFile(source, options);
+    }
     async close(params = {}, options = {}) {
         const result = await this.boundRuntime.invoke(CONTRACT.operations['doc.close'], params, options);
         this.boundRuntime.markClosed();

package/dist/runtime/document-rpc.cjs

@@ -5,6 +5,7 @@ var errors = require('./errors.cjs');
 var transportCommon = require('./transport-common.cjs');
 
 const DOCUMENT_RPC_FEATURES = ['document.open', 'document.invoke', 'document.save', 'document.close'];
+const DOCUMENT_RPC_REPLACE_FILE_FEATURE = 'document.replaceFile';
 const DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = 'document.open.defaultChangeMode';
 const DOCUMENT_RPC_SOURCE_SAVE_FEATURE = 'document.save.source';
 const DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = 'host.request.timeoutMs';
@@ -103,6 +104,30 @@ function mapDocumentOpenResult(response, sessionId, path) {
         dirty: false,
     };
 }
+function mapDocumentReplaceFileResult(response, sessionId) {
+    if (typeof response !== 'object' || response == null || Array.isArray(response)) {
+        throw new errors.SuperDocCliError('Host returned invalid document.replaceFile result.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    const record = response;
+    if (record.sessionId !== sessionId ||
+        record.replaced !== true ||
+        typeof record.byteLength !== 'number' ||
+        typeof record.revision !== 'string') {
+        throw new errors.SuperDocCliError('Host returned invalid document.replaceFile session metadata.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { expectedSessionId: sessionId, result: response },
+        });
+    }
+    return {
+        contextId: sessionId,
+        runtime: 'v2',
+        replaced: true,
+        document: { byteLength: record.byteLength, revision: record.revision },
+    };
+}
 function supportsTrackedMode(operation) {
     return operation.supportsTrackedMode === true || operation.supportsConditionalTrackedMode === true;
 }
@@ -316,6 +341,7 @@ function mapDocumentLifecycleResult(operationId, response, sessionId, expectedIn
 
 exports.DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE;
 exports.DOCUMENT_RPC_FEATURES = DOCUMENT_RPC_FEATURES;
+exports.DOCUMENT_RPC_REPLACE_FILE_FEATURE = DOCUMENT_RPC_REPLACE_FILE_FEATURE;
 exports.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE;
 exports.DOCUMENT_RPC_SOURCE_SAVE_FEATURE = DOCUMENT_RPC_SOURCE_SAVE_FEATURE;
 exports.buildDocumentInvokeParams = buildDocumentInvokeParams;
@@ -325,4 +351,5 @@ exports.documentRpcEnabled = documentRpcEnabled;
 exports.documentRpcRequestSupportsResponseTimeout = documentRpcRequestSupportsResponseTimeout;
 exports.mapDocumentLifecycleResult = mapDocumentLifecycleResult;
 exports.mapDocumentOpenResult = mapDocumentOpenResult;
+exports.mapDocumentReplaceFileResult = mapDocumentReplaceFileResult;
 exports.supportsDocumentRpc = supportsDocumentRpc;

package/dist/runtime/document-rpc.d.ts

@@ -1,5 +1,6 @@
 import { type ChangeMode, type InvokeOptions, type OperationSpec, type UserIdentity } from './transport-common.js';
 export declare const DOCUMENT_RPC_FEATURES: readonly ["document.open", "document.invoke", "document.save", "document.close"];
+export declare const DOCUMENT_RPC_REPLACE_FILE_FEATURE = "document.replaceFile";
 export declare const DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = "document.open.defaultChangeMode";
 export declare const DOCUMENT_RPC_SOURCE_SAVE_FEATURE = "document.save.source";
 export declare const DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = "host.request.timeoutMs";
@@ -15,6 +16,7 @@ export declare function buildDocumentOpenParams(params: Record<string, unknown>,
     readonly params: Record<string, unknown>;
 };
 export declare function mapDocumentOpenResult(response: unknown, sessionId: string, path: string): Record<string, unknown>;
+export declare function mapDocumentReplaceFileResult(response: unknown, sessionId: string): Record<string, unknown>;
 export declare function buildDocumentInvokeParams(sessionId: string, operation: OperationSpec, params: Record<string, unknown>, options: InvokeOptions, hostFeatures?: ReadonlySet<string>): {
     readonly method: string;
     readonly params: Record<string, unknown>;

package/dist/runtime/document-rpc.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { SuperDocCliError } from './errors.js';
 import { applyOperationParamAliases, } from './transport-common.js';
 export const DOCUMENT_RPC_FEATURES = ['document.open', 'document.invoke', 'document.save', 'document.close'];
+export const DOCUMENT_RPC_REPLACE_FILE_FEATURE = 'document.replaceFile';
 export const DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = 'document.open.defaultChangeMode';
 export const DOCUMENT_RPC_SOURCE_SAVE_FEATURE = 'document.save.source';
 export const DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = 'host.request.timeoutMs';
@@ -100,6 +101,30 @@ export function mapDocumentOpenResult(response, sessionId, path) {
         dirty: false,
     };
 }
+export function mapDocumentReplaceFileResult(response, sessionId) {
+    if (typeof response !== 'object' || response == null || Array.isArray(response)) {
+        throw new SuperDocCliError('Host returned invalid document.replaceFile result.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    const record = response;
+    if (record.sessionId !== sessionId ||
+        record.replaced !== true ||
+        typeof record.byteLength !== 'number' ||
+        typeof record.revision !== 'string') {
+        throw new SuperDocCliError('Host returned invalid document.replaceFile session metadata.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { expectedSessionId: sessionId, result: response },
+        });
+    }
+    return {
+        contextId: sessionId,
+        runtime: 'v2',
+        replaced: true,
+        document: { byteLength: record.byteLength, revision: record.revision },
+    };
+}
 function supportsTrackedMode(operation) {
     return operation.supportsTrackedMode === true || operation.supportsConditionalTrackedMode === true;
 }

package/dist/runtime/host.cjs

@@ -187,6 +187,34 @@ class HostTransport {
     async invoke(operation, params = {}, options = {}) {
         return this.runWhileActive(() => this.invokeWhileActive(operation, params, options));
     }
+    async replaceFile(sessionId, path, options = {}) {
+        return this.runWhileActive(async () => {
+            await this.ensureConnected();
+            if (!this.hostFeatures.has(documentRpc.DOCUMENT_RPC_REPLACE_FILE_FEATURE)) {
+                throw new errors.SuperDocCliError('The connected host does not support document replacement.', {
+                    code: 'CAPABILITY_UNSUPPORTED',
+                    details: { feature: documentRpc.DOCUMENT_RPC_REPLACE_FILE_FEATURE },
+                });
+            }
+            const tracksDirectSession = this.documentRpcSessions.has(sessionId);
+            if (tracksDirectSession)
+                this.beginDocumentRpcMutation(sessionId);
+            try {
+                const response = await this.sendJsonRpcRequest(documentRpc.DOCUMENT_RPC_REPLACE_FILE_FEATURE, { sessionId, path }, this.resolveWatchdogTimeout(options.timeoutMs));
+                const result = documentRpc.mapDocumentReplaceFileResult(response, sessionId);
+                if (tracksDirectSession)
+                    this.settleDocumentRpcMutation(sessionId, 'applied');
+                return result;
+            }
+            catch (error) {
+                if (tracksDirectSession) {
+                    const indeterminate = error instanceof errors.SuperDocCliError && ['TIMEOUT', 'HOST_TIMEOUT', 'HOST_DISCONNECTED'].includes(error.code);
+                    this.settleDocumentRpcMutation(sessionId, indeterminate ? 'indeterminate' : 'not-applied');
+                }
+                throw error;
+            }
+        });
+    }
     async invokeWhileActive(operation, params, options) {
         const collaborationAuth = options.collaborationAuth === undefined ? undefined : transportCommon.normalizeCollaborationAuth(options.collaborationAuth);
         if (collaborationAuth !== undefined) {
@@ -285,8 +313,11 @@ class HostTransport {
                 details: { operationId: operation.operationId },
             });
         }
+        const supportsRequestTimeoutMetadata = this.hostFeatures.has(documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE);
         const cliHostRequestTimeoutMs = this.requestTimeoutMs ?? HOST_DEFAULT_REQUEST_TIMEOUT_MS;
-        if (options.timeoutMs !== undefined && options.timeoutMs > cliHostRequestTimeoutMs) {
+        if (!supportsRequestTimeoutMetadata &&
+            options.timeoutMs !== undefined &&
+            options.timeoutMs > cliHostRequestTimeoutMs) {
             throw new errors.SuperDocCliError(`CLI host cannot honor timeoutMs=${options.timeoutMs} above its ${cliHostRequestTimeoutMs}ms request ceiling.`, {
                 code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
                 details: {
@@ -304,7 +335,9 @@ class HostTransport {
             argv,
             stdinBase64,
             ...(collaborationAuth === undefined ? {} : { collaborationAuth }),
-        }, watchdogTimeout);
+        }, watchdogTimeout, {
+            requestTimeoutMs: supportsRequestTimeoutMetadata ? options.timeoutMs : undefined,
+        });
         if (typeof response !== 'object' || response == null || Array.isArray(response)) {
             throw new errors.SuperDocCliError('Host returned invalid cli.invoke result.', {
                 code: 'HOST_PROTOCOL_ERROR',

package/dist/runtime/host.d.ts

@@ -64,6 +64,7 @@ export declare class HostTransport {
     dispose(): Promise<void>;
     private disposeAfterActiveCalls;
     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;
     private runWhileActive;
     private ensureConnected;

package/dist/runtime/host.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 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';
+import { DOCUMENT_RPC_FEATURES, DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE, DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE, DOCUMENT_RPC_REPLACE_FILE_FEATURE, DOCUMENT_RPC_SOURCE_SAVE_FEATURE, buildDocumentInvokeParams, buildDocumentOpenParams, canOpenWithDocumentRpc, documentRpcRequestSupportsResponseTimeout, documentRpcEnabled, mapDocumentLifecycleResult, mapDocumentOpenResult, mapDocumentReplaceFileResult, 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';
@@ -184,6 +184,34 @@ export class HostTransport {
     async invoke(operation, params = {}, options = {}) {
         return this.runWhileActive(() => this.invokeWhileActive(operation, params, options));
     }
+    async replaceFile(sessionId, path, options = {}) {
+        return this.runWhileActive(async () => {
+            await this.ensureConnected();
+            if (!this.hostFeatures.has(DOCUMENT_RPC_REPLACE_FILE_FEATURE)) {
+                throw new SuperDocCliError('The connected host does not support document replacement.', {
+                    code: 'CAPABILITY_UNSUPPORTED',
+                    details: { feature: DOCUMENT_RPC_REPLACE_FILE_FEATURE },
+                });
+            }
+            const tracksDirectSession = this.documentRpcSessions.has(sessionId);
+            if (tracksDirectSession)
+                this.beginDocumentRpcMutation(sessionId);
+            try {
+                const response = await this.sendJsonRpcRequest(DOCUMENT_RPC_REPLACE_FILE_FEATURE, { sessionId, path }, this.resolveWatchdogTimeout(options.timeoutMs));
+                const result = mapDocumentReplaceFileResult(response, sessionId);
+                if (tracksDirectSession)
+                    this.settleDocumentRpcMutation(sessionId, 'applied');
+                return result;
+            }
+            catch (error) {
+                if (tracksDirectSession) {
+                    const indeterminate = error instanceof SuperDocCliError && ['TIMEOUT', 'HOST_TIMEOUT', 'HOST_DISCONNECTED'].includes(error.code);
+                    this.settleDocumentRpcMutation(sessionId, indeterminate ? 'indeterminate' : 'not-applied');
+                }
+                throw error;
+            }
+        });
+    }
     async invokeWhileActive(operation, params, options) {
         const collaborationAuth = options.collaborationAuth === undefined ? undefined : normalizeCollaborationAuth(options.collaborationAuth);
         if (collaborationAuth !== undefined) {
@@ -282,8 +310,11 @@ export class HostTransport {
                 details: { operationId: operation.operationId },
             });
         }
+        const supportsRequestTimeoutMetadata = this.hostFeatures.has(DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE);
         const cliHostRequestTimeoutMs = this.requestTimeoutMs ?? HOST_DEFAULT_REQUEST_TIMEOUT_MS;
-        if (options.timeoutMs !== undefined && options.timeoutMs > cliHostRequestTimeoutMs) {
+        if (!supportsRequestTimeoutMetadata &&
+            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: {
@@ -301,7 +332,9 @@ export class HostTransport {
             argv,
             stdinBase64,
             ...(collaborationAuth === undefined ? {} : { collaborationAuth }),
-        }, watchdogTimeout);
+        }, watchdogTimeout, {
+            requestTimeoutMs: supportsRequestTimeoutMetadata ? options.timeoutMs : undefined,
+        });
         if (typeof response !== 'object' || response == null || Array.isArray(response)) {
             throw new SuperDocCliError('Host returned invalid cli.invoke result.', {
                 code: 'HOST_PROTOCOL_ERROR',

package/dist/runtime/process.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+var promises = require('node:fs/promises');
+var os = require('node:os');
+var path = require('node:path');
 var host = require('./host.cjs');
 var embeddedCli = require('./embedded-cli.cjs');
 var embeddedDocumentHost = require('./embedded-document-host.cjs');
@@ -88,6 +91,35 @@ class SuperDocRuntime {
             throw error;
         }
     }
+    async replaceFile(sessionId, source, options = {}) {
+        if (typeof source === 'string') {
+            if (source.trim().length === 0) {
+                throw new errors.SuperDocCliError('replaceFile source path must be non-empty.', { code: 'INVALID_ARGUMENT' });
+            }
+            return (await this.transport.replaceFile(sessionId, source, options));
+        }
+        let bytes;
+        if (source instanceof Uint8Array) {
+            bytes = new Uint8Array(source);
+        }
+        else if (source instanceof ArrayBuffer) {
+            bytes = new Uint8Array(source.slice(0));
+        }
+        else {
+            throw new errors.SuperDocCliError('replaceFile source must be a path, Uint8Array, or ArrayBuffer.', {
+                code: 'INVALID_ARGUMENT',
+            });
+        }
+        const stagingDirectory = await promises.mkdtemp(path.join(os.tmpdir(), 'superdoc-sdk-replace-'));
+        const stagedPath = path.join(stagingDirectory, 'replacement.docx');
+        try {
+            await promises.writeFile(stagedPath, bytes, { mode: 0o600 });
+            return (await this.transport.replaceFile(sessionId, stagedPath, options));
+        }
+        finally {
+            await promises.rm(stagingDirectory, { recursive: true, force: true });
+        }
+    }
 }
 
 exports.SuperDocRuntime = SuperDocRuntime;

package/dist/runtime/process.d.ts

@@ -7,6 +7,19 @@ type EmbeddedRuntimeResolvers = {
     cli: () => string;
     documentHost: () => string;
 };
+export type ReplaceFileSource = string | Uint8Array | ArrayBuffer;
+export interface ReplaceFileOptions {
+    readonly timeoutMs?: number;
+}
+export interface ReplaceFileResult {
+    readonly contextId: string;
+    readonly runtime: 'v2';
+    readonly replaced: true;
+    readonly document: {
+        readonly byteLength: number;
+        readonly revision: string;
+    };
+}
 export declare function resolveRuntimeProcess(options?: SuperDocClientOptions, embedded?: EmbeddedRuntimeResolvers): RuntimeProcessResolution;
 export declare function toSafeInvokeTraceOptions(options: TransportInvokeOptions): InvokeOptions;
 /**
@@ -21,5 +34,6 @@ export declare class SuperDocRuntime {
     connect(): Promise<void>;
     dispose(): Promise<void>;
     invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: TransportInvokeOptions): Promise<TData>;
+    replaceFile(sessionId: string, source: ReplaceFileSource, options?: ReplaceFileOptions): Promise<ReplaceFileResult>;
 }
 export type { CollaborationAuth, DocumentRuntimeKind, DocOpenOptions, InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions, };

package/dist/runtime/process.js

@@ -1,3 +1,6 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { HostTransport } from './host.js';
 import { resolveEmbeddedCliBinary } from './embedded-cli.js';
 import { resolveEmbeddedDocumentHostBinary } from './embedded-document-host.js';
@@ -85,4 +88,33 @@ export class SuperDocRuntime {
             throw error;
         }
     }
+    async replaceFile(sessionId, source, options = {}) {
+        if (typeof source === 'string') {
+            if (source.trim().length === 0) {
+                throw new SuperDocCliError('replaceFile source path must be non-empty.', { code: 'INVALID_ARGUMENT' });
+            }
+            return (await this.transport.replaceFile(sessionId, source, options));
+        }
+        let bytes;
+        if (source instanceof Uint8Array) {
+            bytes = new Uint8Array(source);
+        }
+        else if (source instanceof ArrayBuffer) {
+            bytes = new Uint8Array(source.slice(0));
+        }
+        else {
+            throw new SuperDocCliError('replaceFile source must be a path, Uint8Array, or ArrayBuffer.', {
+                code: 'INVALID_ARGUMENT',
+            });
+        }
+        const stagingDirectory = await mkdtemp(join(tmpdir(), 'superdoc-sdk-replace-'));
+        const stagedPath = join(stagingDirectory, 'replacement.docx');
+        try {
+            await writeFile(stagedPath, bytes, { mode: 0o600 });
+            return (await this.transport.replaceFile(sessionId, stagedPath, options));
+        }
+        finally {
+            await rm(stagingDirectory, { recursive: true, force: true });
+        }
+    }
 }

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.10.0-next.4';
+const SDK_VERSION = '2.10.0-next.6';
 
 exports.SDK_VERSION = SDK_VERSION;

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

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.10.0-next.4";
+export declare const SDK_VERSION = "2.10.0-next.6";

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.10.0-next.4';
+export const SDK_VERSION = '2.10.0-next.6';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/sdk",
-  "version": "2.10.0-next.4",
+  "version": "2.10.0-next.6",
   "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,11 +37,11 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@superdoc/sdk-darwin-arm64": "2.10.0-next.4",
-    "@superdoc/sdk-darwin-x64": "2.10.0-next.4",
-    "@superdoc/sdk-linux-x64": "2.10.0-next.4",
-    "@superdoc/sdk-linux-arm64": "2.10.0-next.4",
-    "@superdoc/sdk-windows-x64": "2.10.0-next.4"
+    "@superdoc/sdk-darwin-arm64": "2.10.0-next.6",
+    "@superdoc/sdk-darwin-x64": "2.10.0-next.6",
+    "@superdoc/sdk-linux-x64": "2.10.0-next.6",
+    "@superdoc/sdk-linux-arm64": "2.10.0-next.6",
+    "@superdoc/sdk-windows-x64": "2.10.0-next.6"
   },
   "publishConfig": {
     "access": "public"
@@ -50,7 +50,8 @@
     "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",
+    "typecheck:consumer": "tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext ../../../../tests/consumer-typecheck/src/sdk-per-open-collaboration-auth.mts ../../../../tests/consumer-typecheck/src/sdk-replace-file.mts",
+    "test:agent-actions": "bun test src/__tests__/actions.test.ts",
     "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"
   }