@superdoc-dev/sdk 1.0.0-alpha.2 → 1.0.0-alpha.4

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { createDocApi } from './generated/client.js';
+import { type SuperDocClientOptions } from './runtime/process.js';
+/**
+ * High-level client for interacting with SuperDoc documents via the CLI.
+ *
+ * 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.
+ */
+export declare class SuperDocClient {
+    private readonly runtime;
+    readonly doc: ReturnType<typeof createDocApi>;
+    constructor(options?: SuperDocClientOptions);
+    connect(): Promise<void>;
+    dispose(): Promise<void>;
+}
+export declare function createSuperDocClient(options?: SuperDocClientOptions): SuperDocClient;
+export { getSkill, installSkill, listSkills } from './skills.js';
+export { chooseTools, dispatchSuperDocTool, getToolCatalog, inferDocumentFeatures, listTools, resolveToolOperation, } from './tools.js';
+export { SuperDocCliError } from './runtime/errors.js';
+export type { InvokeOptions, OperationSpec, OperationParamSpec, SuperDocClientOptions, } from './runtime/process.js';
+export type { DocumentFeatures, ToolChooserInput, ToolPhase, ToolProfile, ToolProvider, } from './tools.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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,EACL,WAAW,EACX,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,SAAS,EACT,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EACV,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACT,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,29 @@
+import { createDocApi } from './generated/client.js';
+import { SuperDocRuntime } from './runtime/process.js';
+/**
+ * High-level client for interacting with SuperDoc documents via the CLI.
+ *
+ * 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.
+ */
+export class SuperDocClient {
+    runtime;
+    doc;
+    constructor(options = {}) {
+        this.runtime = new SuperDocRuntime(options);
+        this.doc = createDocApi(this.runtime);
+    }
+    async connect() {
+        await this.runtime.connect();
+    }
+    async dispose() {
+        await this.runtime.dispose();
+    }
+}
+export function createSuperDocClient(options = {}) {
+    return new SuperDocClient(options);
+}
+export { getSkill, installSkill, listSkills } from './skills.js';
+export { chooseTools, dispatchSuperDocTool, getToolCatalog, inferDocumentFeatures, listTools, resolveToolOperation, } from './tools.js';
+export { SuperDocCliError } from './runtime/errors.js';

package/dist/runtime/embedded-cli.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Resolve the path to the embedded SuperDoc CLI binary for the current platform.
+ */
+export declare function resolveEmbeddedCliBinary(): string;
+//# sourceMappingURL=embedded-cli.d.ts.map

package/dist/runtime/embedded-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedded-cli.d.ts","sourceRoot":"","sources":["../../src/runtime/embedded-cli.ts"],"names":[],"mappings":"AAuEA;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CA2BjD"}

package/dist/runtime/embedded-cli.js

@@ -0,0 +1,94 @@
+import { chmodSync, existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SuperDocCliError } from './errors.js';
+const require = createRequire(import.meta.url);
+const TARGET_TO_PACKAGE = {
+    'darwin-arm64': '@superdoc-dev/sdk-darwin-arm64',
+    'darwin-x64': '@superdoc-dev/sdk-darwin-x64',
+    'linux-x64': '@superdoc-dev/sdk-linux-x64',
+    'linux-arm64': '@superdoc-dev/sdk-linux-arm64',
+    'windows-x64': '@superdoc-dev/sdk-windows-x64',
+};
+const TARGET_TO_DIR = {
+    'darwin-arm64': 'sdk-darwin-arm64',
+    'darwin-x64': 'sdk-darwin-x64',
+    'linux-x64': 'sdk-linux-x64',
+    'linux-arm64': 'sdk-linux-arm64',
+    'windows-x64': 'sdk-windows-x64',
+};
+function resolveTarget() {
+    const platform = process.platform;
+    const arch = process.arch;
+    if (platform === 'darwin' && arch === 'arm64')
+        return 'darwin-arm64';
+    if (platform === 'darwin' && arch === 'x64')
+        return 'darwin-x64';
+    if (platform === 'linux' && arch === 'x64')
+        return 'linux-x64';
+    if (platform === 'linux' && arch === 'arm64')
+        return 'linux-arm64';
+    if (platform === 'win32' && arch === 'x64')
+        return 'windows-x64';
+    return null;
+}
+function binaryNameForTarget(target) {
+    return target === 'windows-x64' ? 'superdoc.exe' : 'superdoc';
+}
+function ensureExecutable(binaryPath) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        chmodSync(binaryPath, 0o755);
+    }
+    catch {
+        // Non-fatal: if chmod fails, spawn() will surface the real execution error.
+    }
+}
+function resolveFromPlatformPackage(target) {
+    const pkg = TARGET_TO_PACKAGE[target];
+    const binaryName = binaryNameForTarget(target);
+    try {
+        return require.resolve(`${pkg}/bin/${binaryName}`);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveFromWorkspaceFallback(target) {
+    const binaryName = binaryNameForTarget(target);
+    const dirName = TARGET_TO_DIR[target];
+    const filePath = path.resolve(fileURLToPath(new URL('../../platforms', import.meta.url)), dirName, 'bin', binaryName);
+    if (!existsSync(filePath))
+        return null;
+    return filePath;
+}
+/**
+ * Resolve the path to the embedded SuperDoc CLI binary for the current platform.
+ */
+export function resolveEmbeddedCliBinary() {
+    const target = resolveTarget();
+    if (!target) {
+        throw new SuperDocCliError('No embedded SuperDoc CLI binary is available for this platform.', {
+            code: 'UNSUPPORTED_PLATFORM',
+            details: {
+                platform: process.platform,
+                arch: process.arch,
+            },
+        });
+    }
+    const platformPackagePath = resolveFromPlatformPackage(target);
+    const resolvedPath = platformPackagePath ?? resolveFromWorkspaceFallback(target);
+    if (!resolvedPath) {
+        throw new SuperDocCliError('Embedded SuperDoc CLI binary is missing for this platform.', {
+            code: 'CLI_BINARY_MISSING',
+            details: {
+                target,
+                packageName: TARGET_TO_PACKAGE[target],
+            },
+        });
+    }
+    ensureExecutable(resolvedPath);
+    return resolvedPath;
+}

package/dist/runtime/errors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Error thrown by the SuperDoc SDK when a CLI operation fails.
+ *
+ * Includes a machine-readable `code` for programmatic error handling
+ * and optional `details` with structured diagnostic context.
+ */
+export declare class SuperDocCliError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    readonly exitCode?: number;
+    constructor(message: string, options: {
+        code: string;
+        details?: unknown;
+        exitCode?: number;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;CAO7F"}

package/dist/runtime/errors.js

@@ -0,0 +1,18 @@
+/**
+ * Error thrown by the SuperDoc SDK when a CLI operation fails.
+ *
+ * Includes a machine-readable `code` for programmatic error handling
+ * and optional `details` with structured diagnostic context.
+ */
+export class SuperDocCliError extends Error {
+    code;
+    details;
+    exitCode;
+    constructor(message, options) {
+        super(message);
+        this.name = 'SuperDocCliError';
+        this.code = options.code;
+        this.details = options.details;
+        this.exitCode = options.exitCode;
+    }
+}

package/dist/runtime/host.d.ts

@@ -0,0 +1,36 @@
+import { type InvokeOptions, type OperationSpec, type SuperDocClientOptions } from './transport-common.js';
+/**
+ * Transport that communicates with a long-lived CLI host process over JSON-RPC stdio.
+ */
+export declare class HostTransport {
+    private readonly cliBin;
+    private readonly env?;
+    private readonly startupTimeoutMs;
+    private readonly shutdownTimeoutMs;
+    private readonly requestTimeoutMs?;
+    private readonly watchdogTimeoutMs;
+    private readonly maxQueueDepth;
+    private readonly defaultChangeMode?;
+    private child;
+    private stdoutReader;
+    private readonly pending;
+    private nextRequestId;
+    private connecting;
+    private stopping;
+    constructor(options: {
+        cliBin: string;
+    } & SuperDocClientOptions);
+    connect(): Promise<void>;
+    dispose(): Promise<void>;
+    invoke<TData extends Record<string, unknown>>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+    private ensureConnected;
+    private startHostProcess;
+    private assertCapabilities;
+    private resolveWatchdogTimeout;
+    private sendJsonRpcRequest;
+    private onStdoutLine;
+    private mapJsonRpcError;
+    private handleDisconnect;
+    private cleanupProcess;
+}
+//# sourceMappingURL=host.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/runtime/host.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC3B,MAAM,uBAAuB,CAAC;AA4B/B;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAqC;IAC1D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAa;IAEhD,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,qBAAqB;IAkBzD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BxB,MAAM,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChD,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,KAAK,CAAC;YA2BH,eAAe;YAkBf,gBAAgB;IAuE9B,OAAO,CAAC,kBAAkB;IAuC1B,OAAO,CAAC,sBAAsB;YAYhB,kBAAkB;IAkEhC,OAAO,CAAC,YAAY;IA2CpB,OAAO,CAAC,eAAe;IAmCvB,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,cAAc;CA6BvB"}

package/dist/runtime/host.js

@@ -0,0 +1,345 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { buildOperationArgv, resolveInvocation, } from './transport-common.js';
+import { SuperDocCliError } from './errors.js';
+const HOST_PROTOCOL_VERSION = '1.0';
+const REQUIRED_FEATURES = ['cli.invoke', 'host.shutdown'];
+const CHANGE_MODES = ['direct', 'tracked'];
+const JSON_RPC_TIMEOUT_CODE = -32011;
+/**
+ * Transport that communicates with a long-lived CLI host process over JSON-RPC stdio.
+ */
+export class HostTransport {
+    cliBin;
+    env;
+    startupTimeoutMs;
+    shutdownTimeoutMs;
+    requestTimeoutMs;
+    watchdogTimeoutMs;
+    maxQueueDepth;
+    defaultChangeMode;
+    child = null;
+    stdoutReader = null;
+    pending = new Map();
+    nextRequestId = 1;
+    connecting = null;
+    stopping = false;
+    constructor(options) {
+        this.cliBin = options.cliBin;
+        this.env = options.env;
+        this.startupTimeoutMs = options.startupTimeoutMs ?? 5_000;
+        this.shutdownTimeoutMs = options.shutdownTimeoutMs ?? 5_000;
+        this.requestTimeoutMs = options.requestTimeoutMs;
+        this.watchdogTimeoutMs = options.watchdogTimeoutMs ?? 30_000;
+        this.maxQueueDepth = options.maxQueueDepth ?? 100;
+        if (options.defaultChangeMode != null && !CHANGE_MODES.includes(options.defaultChangeMode)) {
+            throw new SuperDocCliError('defaultChangeMode must be "direct" or "tracked".', {
+                code: 'INVALID_ARGUMENT',
+                details: { defaultChangeMode: options.defaultChangeMode },
+            });
+        }
+        this.defaultChangeMode = options.defaultChangeMode;
+    }
+    async connect() {
+        await this.ensureConnected();
+    }
+    async dispose() {
+        if (!this.child)
+            return;
+        this.stopping = true;
+        const child = this.child;
+        try {
+            await this.sendJsonRpcRequest('host.shutdown', {}, this.shutdownTimeoutMs);
+        }
+        catch {
+            // ignore and force shutdown below
+        }
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                child.kill('SIGKILL');
+                resolve();
+            }, this.shutdownTimeoutMs);
+            child.once('close', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+        this.cleanupProcess(null);
+        this.stopping = false;
+    }
+    async invoke(operation, params = {}, options = {}) {
+        await this.ensureConnected();
+        const argv = buildOperationArgv(operation, params, options, this.requestTimeoutMs, this.defaultChangeMode);
+        const stdinBase64 = options.stdinBytes ? Buffer.from(options.stdinBytes).toString('base64') : '';
+        const watchdogTimeout = this.resolveWatchdogTimeout(options.timeoutMs);
+        const response = await this.sendJsonRpcRequest('cli.invoke', {
+            argv,
+            stdinBase64,
+        }, watchdogTimeout);
+        if (typeof response !== 'object' || response == null || Array.isArray(response)) {
+            throw new SuperDocCliError('Host returned invalid cli.invoke result.', {
+                code: 'HOST_PROTOCOL_ERROR',
+                details: { result: response },
+            });
+        }
+        const resultRecord = response;
+        return resultRecord.data;
+    }
+    async ensureConnected() {
+        if (this.child && !this.child.killed) {
+            return;
+        }
+        if (this.connecting) {
+            await this.connecting;
+            return;
+        }
+        this.connecting = this.startHostProcess();
+        try {
+            await this.connecting;
+        }
+        finally {
+            this.connecting = null;
+        }
+    }
+    async startHostProcess() {
+        const { command, prefixArgs } = resolveInvocation(this.cliBin);
+        const args = [...prefixArgs, 'host', '--stdio'];
+        const child = spawn(command, args, {
+            env: {
+                ...process.env,
+                ...(this.env ?? {}),
+            },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.child = child;
+        const stdoutReader = createInterface({
+            input: child.stdout,
+            crlfDelay: Number.POSITIVE_INFINITY,
+        });
+        this.stdoutReader = stdoutReader;
+        stdoutReader.on('line', (line) => {
+            this.onStdoutLine(line);
+        });
+        child.stderr.on('data', () => {
+            // stderr intentionally ignored in host mode
+        });
+        child.on('error', (error) => {
+            this.handleDisconnect(new SuperDocCliError('Host process failed.', {
+                code: 'HOST_DISCONNECTED',
+                details: {
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            }));
+        });
+        child.on('close', (code, signal) => {
+            if (this.stopping) {
+                this.cleanupProcess(null);
+                return;
+            }
+            this.handleDisconnect(new SuperDocCliError('Host process disconnected.', {
+                code: 'HOST_DISCONNECTED',
+                details: { exitCode: code, signal },
+            }));
+        });
+        try {
+            const capabilities = await this.sendJsonRpcRequest('host.capabilities', {}, this.startupTimeoutMs);
+            this.assertCapabilities(capabilities);
+        }
+        catch (error) {
+            const normalized = error instanceof SuperDocCliError
+                ? error
+                : new SuperDocCliError('Host handshake failed.', {
+                    code: 'HOST_HANDSHAKE_FAILED',
+                    details: {
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            this.handleDisconnect(normalized);
+            throw normalized;
+        }
+    }
+    assertCapabilities(response) {
+        if (typeof response !== 'object' || response == null || Array.isArray(response)) {
+            throw new SuperDocCliError('Host capabilities response is invalid.', {
+                code: 'HOST_HANDSHAKE_FAILED',
+                details: { response },
+            });
+        }
+        const record = response;
+        const protocolVersion = record.protocolVersion;
+        const features = record.features;
+        if (protocolVersion !== HOST_PROTOCOL_VERSION) {
+            throw new SuperDocCliError('Host protocol version is unsupported.', {
+                code: 'HOST_HANDSHAKE_FAILED',
+                details: {
+                    expected: HOST_PROTOCOL_VERSION,
+                    actual: protocolVersion,
+                },
+            });
+        }
+        if (!Array.isArray(features) || features.some((f) => typeof f !== 'string')) {
+            throw new SuperDocCliError('Host capabilities.features must be a string array.', {
+                code: 'HOST_HANDSHAKE_FAILED',
+                details: { features },
+            });
+        }
+        for (const requiredFeature of REQUIRED_FEATURES) {
+            if (!features.includes(requiredFeature)) {
+                throw new SuperDocCliError(`Host does not support required feature: ${requiredFeature}`, {
+                    code: 'HOST_HANDSHAKE_FAILED',
+                    details: { features },
+                });
+            }
+        }
+    }
+    resolveWatchdogTimeout(timeoutMsOverride) {
+        if (timeoutMsOverride != null) {
+            return Math.max(this.watchdogTimeoutMs, timeoutMsOverride + 1_000);
+        }
+        if (this.requestTimeoutMs != null) {
+            return Math.max(this.watchdogTimeoutMs, this.requestTimeoutMs + 1_000);
+        }
+        return this.watchdogTimeoutMs;
+    }
+    async sendJsonRpcRequest(method, params, watchdogTimeoutMs) {
+        const child = this.child;
+        if (!child || !child.stdin.writable) {
+            throw new SuperDocCliError('Host process is not available.', {
+                code: 'HOST_DISCONNECTED',
+            });
+        }
+        if (this.pending.size >= this.maxQueueDepth) {
+            throw new SuperDocCliError('Host request queue is full.', {
+                code: 'HOST_QUEUE_FULL',
+                details: { maxQueueDepth: this.maxQueueDepth },
+            });
+        }
+        const id = this.nextRequestId;
+        this.nextRequestId += 1;
+        const payload = JSON.stringify({
+            jsonrpc: '2.0',
+            id,
+            method,
+            params,
+        });
+        const promise = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new SuperDocCliError(`Host watchdog timed out waiting for ${method}.`, {
+                    code: 'HOST_TIMEOUT',
+                    details: { method, timeoutMs: watchdogTimeoutMs },
+                }));
+                this.handleDisconnect(new SuperDocCliError('Host watchdog timeout; host process will be restarted on next request.', {
+                    code: 'HOST_DISCONNECTED',
+                    details: { method, timeoutMs: watchdogTimeoutMs },
+                }));
+            }, watchdogTimeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            child.stdin.write(`${payload}\n`, (error) => {
+                if (!error)
+                    return;
+                const pending = this.pending.get(id);
+                if (!pending)
+                    return;
+                clearTimeout(pending.timer);
+                this.pending.delete(id);
+                reject(new SuperDocCliError('Failed to write request to host process.', {
+                    code: 'HOST_DISCONNECTED',
+                    details: { method, message: error.message },
+                }));
+            });
+        });
+        return promise;
+    }
+    onStdoutLine(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (typeof parsed !== 'object' || parsed == null || Array.isArray(parsed)) {
+            return;
+        }
+        const record = parsed;
+        if (record.jsonrpc !== '2.0') {
+            return;
+        }
+        // Notification (no id) — reserved for future eventing
+        if ('method' in record && !('id' in record)) {
+            return;
+        }
+        const idRaw = record.id;
+        if (typeof idRaw !== 'number') {
+            return;
+        }
+        const pending = this.pending.get(idRaw);
+        if (!pending) {
+            return;
+        }
+        clearTimeout(pending.timer);
+        this.pending.delete(idRaw);
+        if ('error' in record) {
+            pending.reject(this.mapJsonRpcError(record.error));
+            return;
+        }
+        pending.resolve(record.result);
+    }
+    mapJsonRpcError(rawError) {
+        if (typeof rawError !== 'object' || rawError == null || Array.isArray(rawError)) {
+            return new SuperDocCliError('Host returned an unknown JSON-RPC error.', {
+                code: 'HOST_PROTOCOL_ERROR',
+                details: { error: rawError },
+            });
+        }
+        const error = rawError;
+        const data = error.data;
+        const cliCode = typeof data?.cliCode === 'string' ? data.cliCode : undefined;
+        const cliMessage = typeof data?.message === 'string' ? data.message : undefined;
+        const exitCode = typeof data?.exitCode === 'number' ? data.exitCode : undefined;
+        if (cliCode) {
+            return new SuperDocCliError(cliMessage ?? error.message ?? 'Command failed.', {
+                code: cliCode,
+                details: data?.details,
+                exitCode,
+            });
+        }
+        if (error.code === JSON_RPC_TIMEOUT_CODE) {
+            return new SuperDocCliError(error.message, {
+                code: 'TIMEOUT',
+                details: data,
+            });
+        }
+        return new SuperDocCliError(error.message, {
+            code: 'COMMAND_FAILED',
+            details: data,
+        });
+    }
+    handleDisconnect(error) {
+        this.cleanupProcess(error);
+    }
+    cleanupProcess(error) {
+        const child = this.child;
+        if (child) {
+            child.removeAllListeners();
+            child.kill('SIGKILL');
+        }
+        this.child = null;
+        if (this.stdoutReader) {
+            this.stdoutReader.removeAllListeners();
+            this.stdoutReader.close();
+            this.stdoutReader = null;
+        }
+        const pendingEntries = Array.from(this.pending.values());
+        this.pending.clear();
+        const rejection = error ??
+            new SuperDocCliError('Host process was disposed while request was in flight.', {
+                code: 'HOST_DISCONNECTED',
+            });
+        for (const pending of pendingEntries) {
+            clearTimeout(pending.timer);
+            pending.reject(rejection);
+        }
+    }
+}

package/dist/runtime/process.d.ts

@@ -0,0 +1,16 @@
+import type { InvokeOptions, OperationParamSpec, OperationSpec, SuperDocClientOptions } from './transport-common.js';
+/**
+ * Internal runtime that delegates CLI invocations to a persistent host transport.
+ *
+ * Resolves the CLI binary and creates a {@link HostTransport} that communicates
+ * with a long-lived `superdoc host --stdio` process.
+ */
+export declare class SuperDocRuntime {
+    private readonly transport;
+    constructor(options?: SuperDocClientOptions);
+    connect(): Promise<void>;
+    dispose(): Promise<void>;
+    invoke<TData extends Record<string, unknown>>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+}
+export type { InvokeOptions, OperationParamSpec, OperationSpec, SuperDocClientOptions };
+//# sourceMappingURL=process.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/runtime/process.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,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,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChD,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"}

package/dist/runtime/process.js

@@ -0,0 +1,27 @@
+import { HostTransport } from './host.js';
+import { resolveEmbeddedCliBinary } from './embedded-cli.js';
+/**
+ * Internal runtime that delegates CLI invocations to a persistent host transport.
+ *
+ * Resolves the CLI binary and creates a {@link HostTransport} that communicates
+ * with a long-lived `superdoc host --stdio` process.
+ */
+export class SuperDocRuntime {
+    transport;
+    constructor(options = {}) {
+        const cliBin = options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? resolveEmbeddedCliBinary();
+        this.transport = new HostTransport({
+            cliBin,
+            ...options,
+        });
+    }
+    async connect() {
+        await this.transport.connect();
+    }
+    async dispose() {
+        await this.transport.dispose();
+    }
+    async invoke(operation, params = {}, options = {}) {
+        return this.transport.invoke(operation, params, options);
+    }
+}