@superdoc-dev/sdk 1.0.0-next.73 → 1.0.0-next.75

package/dist/generated/intent-dispatch.generated.cjs

@@ -10,6 +10,7 @@ function dispatchIntentTool(toolName, args, execute) {
                 case 'markdown': return execute('doc.getMarkdown', rest);
                 case 'html': return execute('doc.getHtml', rest);
                 case 'info': return execute('doc.info', rest);
+                case 'blocks': return execute('doc.blocks.list', rest);
                 default: throw new Error(`Unknown action for superdoc_get_content: ${action}`);
             }
         }

package/dist/generated/intent-dispatch.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intent-dispatch.generated.d.ts","sourceRoot":"","sources":["../../src/generated/intent-dispatch.generated.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GACxE,OAAO,CAwFT"}
+{"version":3,"file":"intent-dispatch.generated.d.ts","sourceRoot":"","sources":["../../src/generated/intent-dispatch.generated.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GACxE,OAAO,CAyFT"}

package/dist/generated/intent-dispatch.generated.js

@@ -8,6 +8,7 @@ export function dispatchIntentTool(toolName, args, execute) {
                 case 'markdown': return execute('doc.getMarkdown', rest);
                 case 'html': return execute('doc.getHtml', rest);
                 case 'info': return execute('doc.info', rest);
+                case 'blocks': return execute('doc.blocks.list', rest);
                 default: throw new Error(`Unknown action for superdoc_get_content: ${action}`);
             }
         }

package/dist/helpers/format.d.ts

@@ -12,21 +12,20 @@
  *
  * const client = createSuperDocClient();
  * await client.connect();
+ * const doc = await client.open({ doc: './file.docx' });
  *
  * // Apply bold ON:
- * await formatBold(client.doc, { target: { kind: 'text', blockId: 'p1', range: { start: 0, end: 5 } } });
+ * await formatBold(doc.format.apply, { target: { kind: 'text', blockId: 'p1', range: { start: 0, end: 5 } } });
  *
  * // Apply explicit bold OFF (override style inheritance):
- * await unformatBold(client.doc, { blockId: 'p1', start: 0, end: 5 });
+ * await unformatBold(doc.format.apply, { blockId: 'p1', start: 0, end: 5 });
  *
  * // Clear direct bold formatting (inherit from style cascade):
- * await clearBold(client.doc, { blockId: 'p1', start: 0, end: 5 });
+ * await clearBold(doc.format.apply, { blockId: 'p1', start: 0, end: 5 });
  * ```
  */
 import type { InvokeOptions, OperationSpec } from '../runtime/transport-common.js';
 export interface FormatHelperParams {
-    doc?: string;
-    sessionId?: string;
     target?: {
         kind: 'text';
         blockId: string;
@@ -46,9 +45,8 @@ export interface FormatHelperParams {
     expectedRevision?: string;
 }
 /**
- * Generic invoke function that works with the SuperDocRuntime.
- * The doc API proxy created by `createDocApi(runtime)` exposes generated methods,
- * but helpers call the runtime directly for forward-compatibility.
+ * Generic invoke function that works with a bound document handle runtime.
+ * Accepts the same signature as SuperDocRuntime.invoke.
  */
 type RuntimeInvokeFn = <T = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions) => Promise<T>;
 /** Apply bold ON. Equivalent to `format.apply` with `inline: { bold: 'on' }`. */

package/dist/helpers/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/helpers/format.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/helpers/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAoBnF,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IAClF,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAClC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,KAAK,eAAe,GAAG,CAAC,CAAC,GAAG,OAAO,EACjC,SAAS,EAAE,aAAa,EACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,aAAa,KACpB,OAAO,CAAC,CAAC,CAAC,CAAC;AA0BhB,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,GAAE,kBAAuB,EAAE,OAAO,CAAC,EAAE,aAAa,oBAE3G;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,GAAE,kBAAuB,EAAE,OAAO,CAAC,EAAE,aAAa,oBAE7G;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,GAAE,kBAAuB,EAAE,OAAO,CAAC,EAAE,aAAa,oBAEhH;AAED,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,GAAE,kBAAuB,EAAE,OAAO,CAAC,EAAE,aAAa,oBAEpH;AAMD,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,GAAE,kBAAuB,EAAE,OAAO,CAAC,EAAE,aAAa,oBAE7G;AAED,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,GAAE,kBAAuB,EAAE,OAAO,CAAC,EAAE,aAAa,oBAE/G;AAED,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,GAAE,kBAAuB,EAAE,OAAO,CAAC,EAAE,aAAa,oBAElH;AAED,8FAA8F;AAC9F,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,kBAAuB,EAC/B,OAAO,CAAC,EAAE,aAAa,oBAGxB;AAMD,4FAA4F;AAC5F,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,GAAE,kBAAuB,EAAE,OAAO,CAAC,EAAE,aAAa,oBAE1G;AAED,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,GAAE,kBAAuB,EAAE,OAAO,CAAC,EAAE,aAAa,oBAE5G;AAED,sGAAsG;AACtG,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,GAAE,kBAAuB,EAAE,OAAO,CAAC,EAAE,aAAa,oBAE/G;AAED,uGAAuG;AACvG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,GAAE,kBAAuB,EAAE,OAAO,CAAC,EAAE,aAAa,oBAEnH"}

package/dist/helpers/format.js

@@ -12,31 +12,28 @@
  *
  * const client = createSuperDocClient();
  * await client.connect();
+ * const doc = await client.open({ doc: './file.docx' });
  *
  * // Apply bold ON:
- * await formatBold(client.doc, { target: { kind: 'text', blockId: 'p1', range: { start: 0, end: 5 } } });
+ * await formatBold(doc.format.apply, { target: { kind: 'text', blockId: 'p1', range: { start: 0, end: 5 } } });
  *
  * // Apply explicit bold OFF (override style inheritance):
- * await unformatBold(client.doc, { blockId: 'p1', start: 0, end: 5 });
+ * await unformatBold(doc.format.apply, { blockId: 'p1', start: 0, end: 5 });
  *
  * // Clear direct bold formatting (inherit from style cascade):
- * await clearBold(client.doc, { blockId: 'p1', start: 0, end: 5 });
+ * await clearBold(doc.format.apply, { blockId: 'p1', start: 0, end: 5 });
  * ```
  */
 /**
  * Minimal operation spec for `format.apply`. Used to invoke the canonical
  * operation through the runtime without depending on generated code.
  *
- * Only canonical params are listed here. Flat-flag shortcuts (blockId,
- * start, end) are accepted via FormatHelperParams and normalized into
- * a `target` object before invoke.
+ * doc and sessionId are omitted — the bound document handle injects them.
  */
 const FORMAT_APPLY_SPEC = {
     operationId: 'doc.format.apply',
     commandTokens: ['format', 'apply'],
     params: [
-        { name: 'doc', kind: 'doc', type: 'string' },
-        { name: 'sessionId', kind: 'doc', flag: 'session', type: 'string' },
         { name: 'target', kind: 'jsonFlag', type: 'json' },
         { name: 'inline', kind: 'jsonFlag', type: 'json' },
         { name: 'dryRun', kind: 'flag', type: 'boolean' },

package/dist/index.cjs

@@ -1,37 +1,159 @@
 'use strict';
 
 var client = require('./generated/client.cjs');
+var contract = require('./generated/contract.cjs');
 var process = require('./runtime/process.cjs');
+var errors = require('./runtime/errors.cjs');
 var skills = require('./skills.cjs');
 var tools = require('./tools.cjs');
 var intentDispatch_generated = require('./generated/intent-dispatch.generated.cjs');
-var errors = require('./runtime/errors.cjs');
 
+// ---------------------------------------------------------------------------
+// Session-bound runtime wrapper
+// ---------------------------------------------------------------------------
 /**
- * High-level client for interacting with SuperDoc documents via the CLI.
+ * Wraps a raw runtime and injects a fixed sessionId into every invoke call.
+ * Implements RuntimeInvoker so generated code can use it directly.
  *
- * Provides a typed `doc` API for opening, querying, and mutating documents.
- * Call {@link connect} before operations and {@link dispose} when finished
- * to manage the host process lifecycle.
+ * @internal
+ */
+class BoundRuntime {
+    runtime;
+    sessionId;
+    closed = false;
+    constructor(runtime, sessionId) {
+        this.runtime = runtime;
+        this.sessionId = sessionId;
+    }
+    async invoke(operation, params = {}, options = {}) {
+        if (this.closed) {
+            throw new errors.SuperDocCliError('Document handle is closed.', {
+                code: 'DOCUMENT_CLOSED',
+                details: { sessionId: this.sessionId },
+            });
+        }
+        return this.runtime.invoke(operation, { ...params, sessionId: this.sessionId }, options);
+    }
+    markClosed() {
+        this.closed = true;
+    }
+}
+// ---------------------------------------------------------------------------
+// Document handle
+// ---------------------------------------------------------------------------
+/**
+ * Bound document handle. All document operations are available as typed methods.
+ * The handle injects its session id automatically — callers never pass
+ * doc or sessionId.
+ */
+class SuperDocDocumentCore {
+    boundRuntime;
+    _sessionId;
+    _openResult;
+    client;
+    /** @internal */
+    constructor(boundRuntime, sessionId, openResult, client$1) {
+        this.boundRuntime = boundRuntime;
+        this._sessionId = sessionId;
+        this._openResult = openResult;
+        this.client = client$1;
+        attachBoundDocApi(this, client.createBoundDocApi(this.boundRuntime));
+    }
+    get sessionId() {
+        return this._sessionId;
+    }
+    /** Read-only snapshot of the initial doc.open response metadata. */
+    get openResult() {
+        return this._openResult;
+    }
+    async save(params = {}, options = {}) {
+        return this.boundRuntime.invoke(contract.CONTRACT.operations['doc.save'], params, options);
+    }
+    async close(params = {}, options = {}) {
+        const result = await this.boundRuntime.invoke(contract.CONTRACT.operations['doc.close'], params, options);
+        this.boundRuntime.markClosed();
+        this.client.removeHandle(this._sessionId);
+        return result;
+    }
+    /** @internal */
+    markClosed() {
+        this.boundRuntime.markClosed();
+    }
+}
+function attachBoundDocApi(target, api) {
+    const { save: _save, close: _close, ...boundMethods } = api;
+    Object.assign(target, boundMethods);
+}
+const SuperDocDocument = SuperDocDocumentCore;
+/**
+ * SuperDoc client — transport manager and document factory.
+ *
+ * Use `client.open()` to get bound document handles. Each handle is
+ * independently session-scoped and safe for concurrent use.
+ *
+ *     const client = new SuperDocClient({ user: { name: 'bot' } });
+ *     await client.connect();
+ *     const doc = await client.open({ doc: './file.docx' });
+ *     const markdown = await doc.getMarkdown();
+ *     await doc.close();
+ *     await client.dispose();
  */
 class SuperDocClient {
     runtime;
-    doc;
+    rawApi;
+    handles = new Map();
     constructor(options = {}) {
         this.runtime = new process.SuperDocRuntime(options);
-        this.doc = client.createDocApi(this.runtime);
+        this.rawApi = client.createDocApi(this.runtime);
     }
     async connect() {
         await this.runtime.connect();
     }
+    /**
+     * Open a document and return a bound document handle.
+     *
+     * The returned handle injects its session id into every operation
+     * automatically. The same file can be opened multiple times with
+     * different session ids (useful for diff workflows).
+     */
+    async open(params, options) {
+        const explicitSessionId = params.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 },
+            });
+        }
+        const result = (await this.rawApi.open(params, 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 this.rawApi.describe(params, options);
+    }
+    async describeCommand(params, options) {
+        return this.rawApi.describeCommand(params, options);
+    }
     async dispose() {
+        for (const handle of this.handles.values()) {
+            handle.markClosed();
+        }
+        this.handles.clear();
         await this.runtime.dispose();
     }
+    /** @internal */
+    removeHandle(sessionId) {
+        this.handles.delete(sessionId);
+    }
 }
 function createSuperDocClient(options = {}) {
     return new SuperDocClient(options);
 }
 
+exports.SuperDocCliError = errors.SuperDocCliError;
 exports.getSkill = skills.getSkill;
 exports.installSkill = skills.installSkill;
 exports.listSkills = skills.listSkills;
@@ -41,6 +163,6 @@ exports.getSystemPrompt = tools.getSystemPrompt;
 exports.getToolCatalog = tools.getToolCatalog;
 exports.listTools = tools.listTools;
 exports.dispatchIntentTool = intentDispatch_generated.dispatchIntentTool;
-exports.SuperDocCliError = errors.SuperDocCliError;
 exports.SuperDocClient = SuperDocClient;
+exports.SuperDocDocument = SuperDocDocument;
 exports.createSuperDocClient = createSuperDocClient;

package/dist/index.d.ts

@@ -1,24 +1,89 @@
-import { createDocApi } from './generated/client.js';
-import { type SuperDocClientOptions } from './runtime/process.js';
+import { type BoundDocApi, type DocCloseBoundParams, type DocCloseResult, type DocSaveBoundParams, type DocSaveResult } from './generated/client.js';
+import { SuperDocRuntime, type SuperDocClientOptions, type InvokeOptions, type OperationSpec, type RuntimeInvoker } from './runtime/process.js';
 /**
- * High-level client for interacting with SuperDoc documents via the CLI.
+ * Wraps a raw runtime and injects a fixed sessionId into every invoke call.
+ * Implements RuntimeInvoker so generated code can use it directly.
  *
- * Provides a typed `doc` API for opening, querying, and mutating documents.
- * Call {@link connect} before operations and {@link dispose} when finished
- * to manage the host process lifecycle.
+ * @internal
+ */
+declare class BoundRuntime implements RuntimeInvoker {
+    private readonly runtime;
+    private readonly sessionId;
+    private closed;
+    constructor(runtime: SuperDocRuntime, sessionId: string);
+    invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+    markClosed(): void;
+}
+/**
+ * Bound document handle. All document operations are available as typed methods.
+ * The handle injects its session id automatically — callers never pass
+ * doc or sessionId.
+ */
+declare class SuperDocDocumentCore {
+    private readonly boundRuntime;
+    private readonly _sessionId;
+    private readonly _openResult;
+    private readonly client;
+    /** @internal */
+    constructor(boundRuntime: BoundRuntime, sessionId: string, openResult: Record<string, unknown>, client: SuperDocClient);
+    get sessionId(): string;
+    /** Read-only snapshot of the initial doc.open response metadata. */
+    get openResult(): Record<string, unknown>;
+    save(params?: DocSaveBoundParams, options?: InvokeOptions): Promise<DocSaveResult>;
+    close(params?: DocCloseBoundParams, options?: InvokeOptions): Promise<DocCloseResult>;
+    /** @internal */
+    markClosed(): void;
+}
+type SuperDocDocumentInstance = SuperDocDocumentCore & BoundDocApi;
+export declare const SuperDocDocument: new (boundRuntime: BoundRuntime, sessionId: string, openResult: Record<string, unknown>, client: SuperDocClient) => SuperDocDocumentInstance;
+export type SuperDocDocument = SuperDocDocumentInstance;
+export interface DocOpenParams {
+    doc?: string;
+    sessionId?: string;
+    [key: string]: unknown;
+}
+export interface DocDescribeCommandParams {
+    operationId: string;
+    [key: string]: unknown;
+}
+/**
+ * SuperDoc client — transport manager and document factory.
+ *
+ * Use `client.open()` to get bound document handles. Each handle is
+ * independently session-scoped and safe for concurrent use.
+ *
+ *     const client = new SuperDocClient({ user: { name: 'bot' } });
+ *     await client.connect();
+ *     const doc = await client.open({ doc: './file.docx' });
+ *     const markdown = await doc.getMarkdown();
+ *     await doc.close();
+ *     await client.dispose();
  */
 export declare class SuperDocClient {
     private readonly runtime;
-    readonly doc: ReturnType<typeof createDocApi>;
+    private readonly rawApi;
+    private readonly handles;
     constructor(options?: SuperDocClientOptions);
     connect(): Promise<void>;
+    /**
+     * Open a document and return a bound document handle.
+     *
+     * The returned handle injects its session id into every operation
+     * automatically. The same file can be opened multiple times with
+     * different session ids (useful for diff workflows).
+     */
+    open(params: DocOpenParams, options?: InvokeOptions): Promise<SuperDocDocument>;
+    describe(params?: Record<string, unknown>, options?: InvokeOptions): Promise<unknown>;
+    describeCommand(params: DocDescribeCommandParams, options?: InvokeOptions): Promise<unknown>;
     dispose(): Promise<void>;
+    /** @internal */
+    removeHandle(sessionId: string): void;
 }
 export declare function createSuperDocClient(options?: SuperDocClientOptions): SuperDocClient;
 export { getSkill, installSkill, listSkills } from './skills.js';
 export { chooseTools, dispatchSuperDocTool, getSystemPrompt, getToolCatalog, listTools } from './tools.js';
 export { dispatchIntentTool } from './generated/intent-dispatch.generated.js';
 export { SuperDocCliError } from './runtime/errors.js';
-export type { InvokeOptions, OperationSpec, OperationParamSpec, SuperDocClientOptions } from './runtime/process.js';
+export type { InvokeOptions, OperationSpec, OperationParamSpec, RuntimeInvoker, SuperDocClientOptions, } from './runtime/process.js';
 export type { ToolChooserInput, ToolProvider } from './tools.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAmB,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAEnF;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;gBAElC,OAAO,GAAE,qBAA0B;IAKzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAExF;AAED,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,eAAe,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC3G,OAAO,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACpH,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,25 +1,147 @@
-import { createDocApi } from './generated/client.js';
-import { SuperDocRuntime } from './runtime/process.js';
+import { createDocApi, createBoundDocApi, } from './generated/client.js';
+import { CONTRACT } from './generated/contract.js';
+import { SuperDocRuntime, } from './runtime/process.js';
+import { SuperDocCliError } from './runtime/errors.js';
+// ---------------------------------------------------------------------------
+// Session-bound runtime wrapper
+// ---------------------------------------------------------------------------
 /**
- * High-level client for interacting with SuperDoc documents via the CLI.
+ * Wraps a raw runtime and injects a fixed sessionId into every invoke call.
+ * Implements RuntimeInvoker so generated code can use it directly.
  *
- * Provides a typed `doc` API for opening, querying, and mutating documents.
- * Call {@link connect} before operations and {@link dispose} when finished
- * to manage the host process lifecycle.
+ * @internal
+ */
+class BoundRuntime {
+    runtime;
+    sessionId;
+    closed = false;
+    constructor(runtime, sessionId) {
+        this.runtime = runtime;
+        this.sessionId = sessionId;
+    }
+    async invoke(operation, params = {}, options = {}) {
+        if (this.closed) {
+            throw new SuperDocCliError('Document handle is closed.', {
+                code: 'DOCUMENT_CLOSED',
+                details: { sessionId: this.sessionId },
+            });
+        }
+        return this.runtime.invoke(operation, { ...params, sessionId: this.sessionId }, options);
+    }
+    markClosed() {
+        this.closed = true;
+    }
+}
+// ---------------------------------------------------------------------------
+// Document handle
+// ---------------------------------------------------------------------------
+/**
+ * Bound document handle. All document operations are available as typed methods.
+ * The handle injects its session id automatically — callers never pass
+ * doc or sessionId.
+ */
+class SuperDocDocumentCore {
+    boundRuntime;
+    _sessionId;
+    _openResult;
+    client;
+    /** @internal */
+    constructor(boundRuntime, sessionId, openResult, client) {
+        this.boundRuntime = boundRuntime;
+        this._sessionId = sessionId;
+        this._openResult = openResult;
+        this.client = client;
+        attachBoundDocApi(this, createBoundDocApi(this.boundRuntime));
+    }
+    get sessionId() {
+        return this._sessionId;
+    }
+    /** Read-only snapshot of the initial doc.open response metadata. */
+    get openResult() {
+        return this._openResult;
+    }
+    async save(params = {}, options = {}) {
+        return this.boundRuntime.invoke(CONTRACT.operations['doc.save'], params, options);
+    }
+    async close(params = {}, options = {}) {
+        const result = await this.boundRuntime.invoke(CONTRACT.operations['doc.close'], params, options);
+        this.boundRuntime.markClosed();
+        this.client.removeHandle(this._sessionId);
+        return result;
+    }
+    /** @internal */
+    markClosed() {
+        this.boundRuntime.markClosed();
+    }
+}
+function attachBoundDocApi(target, api) {
+    const { save: _save, close: _close, ...boundMethods } = api;
+    Object.assign(target, boundMethods);
+}
+export const SuperDocDocument = SuperDocDocumentCore;
+/**
+ * SuperDoc client — transport manager and document factory.
+ *
+ * Use `client.open()` to get bound document handles. Each handle is
+ * independently session-scoped and safe for concurrent use.
+ *
+ *     const client = new SuperDocClient({ user: { name: 'bot' } });
+ *     await client.connect();
+ *     const doc = await client.open({ doc: './file.docx' });
+ *     const markdown = await doc.getMarkdown();
+ *     await doc.close();
+ *     await client.dispose();
  */
 export class SuperDocClient {
     runtime;
-    doc;
+    rawApi;
+    handles = new Map();
     constructor(options = {}) {
         this.runtime = new SuperDocRuntime(options);
-        this.doc = createDocApi(this.runtime);
+        this.rawApi = createDocApi(this.runtime);
     }
     async connect() {
         await this.runtime.connect();
     }
+    /**
+     * Open a document and return a bound document handle.
+     *
+     * The returned handle injects its session id into every operation
+     * automatically. The same file can be opened multiple times with
+     * different session ids (useful for diff workflows).
+     */
+    async open(params, options) {
+        const explicitSessionId = params.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 },
+            });
+        }
+        const result = (await this.rawApi.open(params, 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 this.rawApi.describe(params, options);
+    }
+    async describeCommand(params, options) {
+        return this.rawApi.describeCommand(params, options);
+    }
     async dispose() {
+        for (const handle of this.handles.values()) {
+            handle.markClosed();
+        }
+        this.handles.clear();
         await this.runtime.dispose();
     }
+    /** @internal */
+    removeHandle(sessionId) {
+        this.handles.delete(sessionId);
+    }
 }
 export function createSuperDocClient(options = {}) {
     return new SuperDocClient(options);

package/dist/runtime/process.d.ts

@@ -1,4 +1,4 @@
-import type { InvokeOptions, OperationParamSpec, OperationSpec, SuperDocClientOptions } from './transport-common.js';
+import type { InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions } from './transport-common.js';
 /**
  * Internal runtime that delegates CLI invocations to a persistent host transport.
  *
@@ -12,5 +12,5 @@ export declare class SuperDocRuntime {
     dispose(): Promise<void>;
     invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
 }
-export type { InvokeOptions, OperationParamSpec, OperationSpec, SuperDocClientOptions };
+export type { InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions };
 //# sourceMappingURL=process.d.ts.map

package/dist/runtime/process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/runtime/process.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAErH;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,OAAO,GAAE,qBAA0B;IASzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,MAAM,CAAC,KAAK,GAAG,OAAO,EAC1B,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,KAAK,CAAC;CAGlB;AAED,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,qBAAqB,EAAE,CAAC"}
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/runtime/process.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,OAAO,GAAE,qBAA0B;IASzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,MAAM,CAAC,KAAK,GAAG,OAAO,EAC1B,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,KAAK,CAAC;CAGlB;AAED,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,cAAc,EAAE,qBAAqB,EAAE,CAAC"}

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

@@ -16,6 +16,13 @@ export interface InvokeOptions {
     timeoutMs?: number;
     stdinBytes?: Uint8Array;
 }
+/**
+ * Minimal invoke interface that both SuperDocRuntime and BoundRuntime satisfy.
+ * Generated code depends on this interface, not on the concrete runtime class.
+ */
+export interface RuntimeInvoker {
+    invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+}
 export type ChangeMode = 'direct' | 'tracked';
 export interface UserIdentity {
     name: string;

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

@@ -1 +1 @@
-{"version":3,"file":"transport-common.d.ts","sourceRoot":"","sources":["../../src/runtime/transport-common.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAC9E,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAU/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,iBAAiB,CAAC,EAAE,UAAU,EAC9B,IAAI,CAAC,EAAE,YAAY,GAClB,MAAM,EAAE,CAiEV"}
+{"version":3,"file":"transport-common.d.ts","sourceRoot":"","sources":["../../src/runtime/transport-common.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAC9E,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,KAAK,GAAG,OAAO,EACpB,SAAS,EAAE,aAAa,EACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,KAAK,CAAC,CAAC;CACnB;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAU/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,iBAAiB,CAAC,EAAE,UAAU,EAC9B,IAAI,CAAC,EAAE,YAAY,GAClB,MAAM,EAAE,CAiEV"}

package/dist/tools.cjs

@@ -87,9 +87,9 @@ async function chooseTools(input) {
         },
     };
 }
-function resolveDocApiMethod(client, operationId) {
+function resolveDocApiMethod(documentHandle, operationId) {
     const tokens = operationId.split('.').slice(1);
-    let cursor = client.doc;
+    let cursor = documentHandle;
     for (const token of tokens) {
         if (!isRecord(cursor) || !(token in cursor)) {
             throw new errors.SuperDocCliError(`No SDK doc method found for operation ${operationId}.`, {
@@ -189,7 +189,13 @@ function validateOperationRequired(toolName, action, args, op) {
         }
     }
 }
-async function dispatchSuperDocTool(client, toolName, args = {}, invokeOptions) {
+/**
+ * Dispatch a tool call against a bound document handle.
+ *
+ * The document handle injects session targeting automatically.
+ * Tool arguments should not contain `doc` or `sessionId`.
+ */
+async function dispatchSuperDocTool(documentHandle, toolName, args = {}, invokeOptions) {
     if (!isRecord(args)) {
         throw new errors.SuperDocCliError(`Tool arguments for ${toolName} must be an object.`, {
             code: 'INVALID_ARGUMENT',
@@ -206,10 +212,17 @@ async function dispatchSuperDocTool(client, toolName, args = {}, invokeOptions)
         });
     }
     validateToolArgs(toolName, args, tool);
-    // Strip doc/sessionId — the SDK client manages session targeting after doc.open().
-    const { doc: _doc, sessionId: _sid, ...cleanArgs } = args;
+    // Strip empty strings for known optional ID/enum params that LLMs fill with ""
+    // instead of omitting. Only target params where "" is never a valid value.
+    const STRIP_EMPTY = new Set(['parentId', 'parentCommentId', 'id', 'status']);
+    const cleanArgs = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (value === '' && STRIP_EMPTY.has(key))
+            continue;
+        cleanArgs[key] = value;
+    }
     return intentDispatch_generated.dispatchIntentTool(toolName, cleanArgs, (operationId, input) => {
-        const method = resolveDocApiMethod(client, operationId);
+        const method = resolveDocApiMethod(documentHandle, operationId);
         return method(input, invokeOptions);
     });
 }