@openvcs/sdk 0.2.3 → 0.2.4

package/README.md

@@ -7,7 +7,9 @@
 OpenVCS SDK for npm-based plugin development.
 
 Install this package in plugin projects, scaffold a starter plugin, and package
-plugins into `.ovcsp` bundles.
+plugins into `.ovcsp` bundles. The SDK also exports a Node-only JSON-RPC runtime
+layer and shared protocol/types so plugins do not have to hand-roll stdio
+framing or method dispatch.
 
 ## Install
 
@@ -61,6 +63,33 @@ The generated module template includes TypeScript and Node typings (`@types/node
 Plugin IDs entered during scaffold must not be `.`/`..` and must not contain path
 separators (`/` or `\\`).
 
+Generated module plugins now start with a working SDK runtime entrypoint:
+
+```ts
+import { createPluginRuntime, startPluginRuntime } from '@openvcs/sdk/runtime';
+
+const runtime = createPluginRuntime({
+  plugin: {
+    async 'plugin.init'(_params, context) {
+      context.host.info('OpenVCS plugin started');
+      return null;
+    },
+  },
+});
+
+startPluginRuntime(runtime);
+```
+
+Runtime and protocol imports are exposed as npm subpaths:
+
+```ts
+import { createPluginRuntime, pluginError } from '@openvcs/sdk/runtime';
+import type { PluginDelegates, VcsDelegates } from '@openvcs/sdk/types';
+```
+
+The runtime handles stdio framing, JSON-RPC request dispatch, host notifications,
+default `plugin.*` handlers, and exact-method delegate registration for `vcs.*`.
+
 Interactive theme plugin scaffold:
 
 ```bash

package/lib/init.d.ts

@@ -25,6 +25,7 @@ declare function defaultPluginIdFromDir(targetDir: string): string;
 declare function validatePluginId(pluginId: string): string | undefined;
 declare function createReadlinePromptDriver(output?: NodeJS.WritableStream): PromptDriver;
 declare function collectAnswers({ forceTheme, targetHint }: CollectAnswersOptions, promptDriver?: PromptDriver, output?: NodeJS.WritableStream): Promise<InitAnswers>;
+declare function writeModuleTemplate(answers: InitAnswers): void;
 export declare function runInitCommand(args: string[]): Promise<string>;
 export declare function isUsageError(error: unknown): error is InitCommandError;
 export declare const __private: {
@@ -33,5 +34,6 @@ export declare const __private: {
     defaultPluginIdFromDir: typeof defaultPluginIdFromDir;
     sanitizeIdToken: typeof sanitizeIdToken;
     validatePluginId: typeof validatePluginId;
+    writeModuleTemplate: typeof writeModuleTemplate;
 };
 export {};

package/lib/init.js

@@ -197,8 +197,10 @@ function writeModuleTemplate(answers) {
             dist: "openvcs dist --plugin-dir . --out dist",
             test: "openvcs dist --plugin-dir . --out dist --no-build --no-npm-deps",
         },
-        devDependencies: {
+        dependencies: {
             "@openvcs/sdk": `^${packageJson.version}`,
+        },
+        devDependencies: {
             "@types/node": "^22.0.0",
             typescript: "^5.8.2",
         },
@@ -216,7 +218,7 @@ function writeModuleTemplate(answers) {
         },
         include: ["src/**/*.ts"],
     });
-    writeText(path.join(answers.targetDir, "src", "plugin.ts"), "const message = \"OpenVCS plugin started\";\nprocess.stderr.write(`${message}\\n`);\n");
+    writeText(path.join(answers.targetDir, "src", "plugin.ts"), "// Copyright © 2025-2026 OpenVCS Contributors\n// SPDX-License-Identifier: GPL-3.0-or-later\n\nimport { createPluginRuntime, startPluginRuntime } from '@openvcs/sdk/runtime';\n\nconst runtime = createPluginRuntime({\n  plugin: {\n    async 'plugin.init'(_params, context) {\n      context.host.info('OpenVCS plugin started');\n      return null;\n    },\n  },\n});\n\nstartPluginRuntime(runtime);\n");
 }
 function writeThemeTemplate(answers) {
     writeCommonFiles(answers);
@@ -229,7 +231,7 @@ function writeThemeTemplate(answers) {
             dist: "openvcs dist --plugin-dir . --out dist",
             test: "openvcs dist --plugin-dir . --out dist --no-build --no-npm-deps",
         },
-        devDependencies: {
+        dependencies: {
             "@openvcs/sdk": `^${packageJson.version}`,
         },
     });
@@ -306,4 +308,5 @@ exports.__private = {
     defaultPluginIdFromDir,
     sanitizeIdToken,
     validatePluginId,
+    writeModuleTemplate,
 };

package/lib/runtime/contracts.d.ts

@@ -0,0 +1,45 @@
+import type { PluginHost, PluginImplements, PluginDelegates, JsonRpcId, JsonRpcRequest, VcsDelegates } from '../types';
+/** Describes the transport endpoints used by the plugin runtime loop. */
+export interface PluginRuntimeTransport {
+    /** Stores the readable stdin-like stream receiving framed messages. */
+    stdin: NodeJS.ReadStream;
+    /** Stores the writable stdout-like stream sending framed messages. */
+    stdout: NodeJS.WritableStream;
+}
+/** Describes the context object passed to every SDK delegate handler. */
+export interface PluginRuntimeContext {
+    /** Stores the active host notification helper. */
+    host: PluginHost;
+    /** Stores the request id currently being processed. */
+    requestId: JsonRpcId;
+    /** Stores the current host method name. */
+    method: string;
+}
+/** Describes the options accepted by `createPluginRuntime`. */
+export interface CreatePluginRuntimeOptions {
+    /** Stores optional plugin lifecycle and settings delegates. */
+    plugin?: PluginDelegates<PluginRuntimeContext>;
+    /** Stores optional VCS method delegates. */
+    vcs?: VcsDelegates<PluginRuntimeContext>;
+    /** Stores optional capability overrides for `plugin.initialize`. */
+    implements?: Partial<PluginImplements>;
+    /** Stores the `host.log` target emitted by the runtime. */
+    logTarget?: string;
+    /** Stores the timeout in milliseconds for request handlers. */
+    timeout?: number;
+    /** Called when runtime starts and begins processing requests. */
+    onStart?: () => void | Promise<void>;
+    /** Called during stop() after pending operations complete. Called with error if shutdown due to processing error. */
+    onShutdown?: (error?: Error) => void | Promise<void>;
+}
+/** Describes one created SDK plugin runtime instance. */
+export interface PluginRuntime {
+    /** Starts listening on stdio for framed JSON-RPC requests. */
+    start(transport?: PluginRuntimeTransport): void;
+    /** Stops the runtime and cleans up pending operations. */
+    stop(): void;
+    /** Consumes one raw stdio chunk and dispatches complete requests. */
+    consumeChunk(chunk: Buffer | string): void;
+    /** Dispatches one already-decoded JSON-RPC request. */
+    dispatchRequest(request: JsonRpcRequest): Promise<void>;
+}

package/lib/runtime/contracts.js

@@ -0,0 +1,4 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/runtime/dispatcher.d.ts

@@ -0,0 +1,16 @@
+import type { JsonRpcId, PluginDelegates, RequestParams } from '../types';
+import type { PluginHost } from '../types';
+import type { CreatePluginRuntimeOptions } from './contracts';
+/** Describes the response emitter used by the dispatcher. */
+export interface DispatcherResponseWriter {
+    /** Emits a JSON-RPC success response. */
+    sendResult<TResult>(id: JsonRpcId, result: TResult): void;
+    /** Emits a JSON-RPC error response. */
+    sendError(id: JsonRpcId, code: number, message: string, data?: unknown): void;
+}
+/** Describes the request handler built by `createRuntimeDispatcher`. */
+export type RuntimeRequestDispatcher = (id: JsonRpcId, method: string, params: RequestParams) => Promise<void>;
+/** Creates the plugin default handlers used when a delegate is omitted. */
+export declare function createDefaultPluginDelegates<TContext>(): Required<Omit<PluginDelegates<TContext>, 'plugin.initialize'>>;
+/** Creates the JSON-RPC dispatcher used by the SDK plugin runtime. */
+export declare function createRuntimeDispatcher(options: CreatePluginRuntimeOptions, host: PluginHost, writer: DispatcherResponseWriter): RuntimeRequestDispatcher;

package/lib/runtime/dispatcher.js

@@ -0,0 +1,133 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultPluginDelegates = createDefaultPluginDelegates;
+exports.createRuntimeDispatcher = createRuntimeDispatcher;
+const types_1 = require("../types");
+const errors_1 = require("./errors");
+/** Creates the plugin default handlers used when a delegate is omitted. */
+function createDefaultPluginDelegates() {
+    return {
+        async 'plugin.init'() {
+            return null;
+        },
+        async 'plugin.deinit'() {
+            return null;
+        },
+        async 'plugin.get_menus'() {
+            return [];
+        },
+        async 'plugin.handle_action'() {
+            return null;
+        },
+        async 'plugin.settings.defaults'() {
+            return [];
+        },
+        async 'plugin.settings.on_load'(params) {
+            return Array.isArray(params.values) ? params.values : [];
+        },
+        async 'plugin.settings.on_apply'() {
+            return null;
+        },
+        async 'plugin.settings.on_save'(params) {
+            return Array.isArray(params.values) ? params.values : [];
+        },
+        async 'plugin.settings.on_reset'() {
+            return null;
+        },
+    };
+}
+/** Creates the JSON-RPC dispatcher used by the SDK plugin runtime. */
+function createRuntimeDispatcher(options, host, writer) {
+    const defaultPluginDelegates = createDefaultPluginDelegates();
+    const pluginDelegates = options.plugin ?? {};
+    const vcsDelegates = options.vcs ?? {};
+    const runtimeImplements = buildRuntimeImplements(options.implements, options.vcs);
+    const timeout = options.timeout;
+    const typedPluginDelegates = pluginDelegates;
+    const typedDefaultPluginDelegates = defaultPluginDelegates;
+    const typedVcsDelegates = vcsDelegates;
+    return async (id, method, params) => {
+        try {
+            if (method === 'plugin.initialize') {
+                const expectedVersion = params.expected_protocol_version;
+                if (typeof expectedVersion === 'number' && expectedVersion !== types_1.PROTOCOL_VERSION) {
+                    writer.sendError(id, types_1.PROTOCOL_VERSION_MISMATCH_CODE, 'protocol version mismatch', {
+                        code: 'protocol-version-mismatch',
+                        message: `host expects protocol ${expectedVersion}, plugin supports ${types_1.PROTOCOL_VERSION}`,
+                    });
+                    return;
+                }
+                const override = pluginDelegates['plugin.initialize']
+                    ? await pluginDelegates['plugin.initialize'](params, {
+                        host,
+                        requestId: id,
+                        method,
+                    })
+                    : {};
+                writer.sendResult(id, {
+                    protocol_version: override.protocol_version ?? types_1.PROTOCOL_VERSION,
+                    implements: {
+                        ...runtimeImplements,
+                        ...override.implements,
+                    },
+                });
+                return;
+            }
+            const handler = typedPluginDelegates[method] ??
+                typedDefaultPluginDelegates[method] ??
+                typedVcsDelegates[method];
+            if (!handler) {
+                throw (0, errors_1.pluginError)('rpc-method-not-found', `method '${method}' is not implemented`);
+            }
+            let result;
+            if (timeout && timeout > 0) {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), timeout);
+                try {
+                    result = await handler(params, {
+                        host,
+                        requestId: id,
+                        method,
+                    });
+                }
+                catch (error) {
+                    clearTimeout(timeoutId);
+                    if (error.name === 'AbortError') {
+                        throw (0, errors_1.pluginError)('request-timeout', `method '${method}' timed out after ${timeout}ms`);
+                    }
+                    throw error;
+                }
+                clearTimeout(timeoutId);
+            }
+            else {
+                result = await handler(params, {
+                    host,
+                    requestId: id,
+                    method,
+                });
+            }
+            writer.sendResult(id, result == null ? null : result);
+        }
+        catch (error) {
+            if ((0, errors_1.isPluginFailure)(error)) {
+                writer.sendError(id, error.code, error.message, error.data);
+                return;
+            }
+            const messageText = error instanceof Error ? error.message : String(error || 'unknown error');
+            host.error(messageText);
+            writer.sendError(id, types_1.PLUGIN_INTERNAL_ERROR_CODE, messageText, {
+                code: 'plugin-internal-error',
+                message: messageText,
+            });
+        }
+    };
+}
+/** Builds the handshake capability flags returned from `plugin.initialize`. */
+function buildRuntimeImplements(overrides, vcsDelegates) {
+    return {
+        plugin: overrides?.plugin ?? true,
+        vcs: overrides?.vcs ?? Boolean(vcsDelegates && Object.keys(vcsDelegates).length > 0),
+    };
+}

package/lib/runtime/errors.d.ts

@@ -0,0 +1,5 @@
+import type { PluginFailure } from '../types';
+/** Builds the host-facing plugin failure payload used for operational errors. */
+export declare function pluginError(code: string, message: string): PluginFailure;
+/** Returns whether the supplied value is a structured plugin failure. */
+export declare function isPluginFailure(value: unknown): value is PluginFailure;

package/lib/runtime/errors.js

@@ -0,0 +1,26 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginError = pluginError;
+exports.isPluginFailure = isPluginFailure;
+const types_1 = require("../types");
+/** Builds the host-facing plugin failure payload used for operational errors. */
+function pluginError(code, message) {
+    return {
+        code: types_1.PLUGIN_FAILURE_CODE,
+        message,
+        data: {
+            code,
+            message,
+        },
+    };
+}
+/** Returns whether the supplied value is a structured plugin failure. */
+function isPluginFailure(value) {
+    if (value == null || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return candidate.code === types_1.PLUGIN_FAILURE_CODE && typeof candidate.message === 'string';
+}

package/lib/runtime/host.d.ts

@@ -0,0 +1,10 @@
+import type { PluginHost } from '../types';
+/** Describes the low-level notification sender used by `createHost`. */
+export type HostNotificationSender = (method: string, params: unknown) => void;
+/** Describes the options accepted by `createHost`. */
+export interface CreateHostOptions {
+    /** Stores the `host.log` target name to emit for diagnostic messages. */
+    logTarget?: string;
+}
+/** Creates the host notification helper used inside runtime delegates. */
+export declare function createHost(sendNotification: HostNotificationSender, options?: CreateHostOptions): PluginHost;

package/lib/runtime/host.js

@@ -0,0 +1,48 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHost = createHost;
+/** Creates the host notification helper used inside runtime delegates. */
+function createHost(sendNotification, options = {}) {
+    const logTarget = options.logTarget ?? 'openvcs.plugin';
+    return {
+        log(level, message) {
+            sendNotification('host.log', {
+                level,
+                target: logTarget,
+                message,
+            });
+        },
+        info(message) {
+            sendNotification('host.log', {
+                level: 'info',
+                target: logTarget,
+                message,
+            });
+        },
+        error(message) {
+            sendNotification('host.log', {
+                level: 'error',
+                target: logTarget,
+                message,
+            });
+        },
+        uiNotify(params) {
+            sendNotification('host.ui_notify', params);
+        },
+        statusSet(params) {
+            sendNotification('host.status_set', params);
+        },
+        emitEvent(params) {
+            sendNotification('host.event_emit', params);
+        },
+        emitVcsEvent(sessionId, requestId, event) {
+            sendNotification('vcs.event', {
+                session_id: sessionId,
+                request_id: requestId,
+                event,
+            });
+        },
+    };
+}

package/lib/runtime/index.d.ts

@@ -0,0 +1,9 @@
+import type { CreatePluginRuntimeOptions, PluginRuntime, PluginRuntimeTransport } from './contracts';
+export type { CreatePluginRuntimeOptions, PluginRuntime, PluginRuntimeContext, PluginRuntimeTransport, } from './contracts';
+export { createDefaultPluginDelegates } from './dispatcher';
+export { isPluginFailure, pluginError } from './errors';
+export { createHost } from './host';
+/** Creates a reusable stdio JSON-RPC runtime for OpenVCS Node plugins. */
+export declare function createPluginRuntime(options?: CreatePluginRuntimeOptions): PluginRuntime;
+/** Starts a previously created plugin runtime on process stdio. */
+export declare function startPluginRuntime(runtime: PluginRuntime, transport?: PluginRuntimeTransport): void;

package/lib/runtime/index.js

@@ -0,0 +1,166 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHost = exports.pluginError = exports.isPluginFailure = exports.createDefaultPluginDelegates = void 0;
+exports.createPluginRuntime = createPluginRuntime;
+exports.startPluginRuntime = startPluginRuntime;
+const dispatcher_1 = require("./dispatcher");
+const host_1 = require("./host");
+const transport_1 = require("./transport");
+var dispatcher_2 = require("./dispatcher");
+Object.defineProperty(exports, "createDefaultPluginDelegates", { enumerable: true, get: function () { return dispatcher_2.createDefaultPluginDelegates; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "isPluginFailure", { enumerable: true, get: function () { return errors_1.isPluginFailure; } });
+Object.defineProperty(exports, "pluginError", { enumerable: true, get: function () { return errors_1.pluginError; } });
+var host_2 = require("./host");
+Object.defineProperty(exports, "createHost", { enumerable: true, get: function () { return host_2.createHost; } });
+/** Creates a reusable stdio JSON-RPC runtime for OpenVCS Node plugins. */
+function createPluginRuntime(options = {}) {
+    let buffer = Buffer.alloc(0);
+    let processing = Promise.resolve();
+    let started = false;
+    let currentTransport = null;
+    let chunkLock = Promise.resolve();
+    const runtime = {
+        start(transport = defaultTransport()) {
+            if (started) {
+                return;
+            }
+            started = true;
+            currentTransport = transport;
+            transport.stdin.on('data', (chunk) => {
+                runtime.consumeChunk(chunk);
+            });
+            transport.stdin.on('error', () => {
+                process.exit(1);
+            });
+            options.onStart?.();
+        },
+        stop() {
+            if (!started) {
+                return;
+            }
+            started = false;
+            processing = processing
+                .catch(async (error) => {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error(`[runtime] shutdown error: ${errorMessage}`);
+                const err = error instanceof Error ? error : new Error(errorMessage);
+                await options.onShutdown?.(err);
+            })
+                .then(async () => {
+                await options.onShutdown?.();
+            });
+            currentTransport = null;
+        },
+        consumeChunk(chunk) {
+            if (!started) {
+                return;
+            }
+            const lock = chunkLock.then(() => {
+                buffer = Buffer.concat([buffer, normalizeChunk(chunk)]);
+                const parsed = (0, transport_1.parseFramedMessages)(buffer);
+                buffer = parsed.remainder;
+                for (const request of parsed.messages) {
+                    processing = processing
+                        .then(async () => {
+                        await runtime.dispatchRequest(request);
+                    })
+                        .catch((error) => {
+                        const message = error instanceof Error ? error.message : String(error || 'unknown plugin processing error');
+                        const host = createRuntimeHost(currentTransport, options.logTarget);
+                        host.error(message);
+                    });
+                }
+            });
+            chunkLock = lock;
+        },
+        async dispatchRequest(request) {
+            const id = request.id;
+            const host = createRuntimeHost(currentTransport, options.logTarget);
+            const method = asTrimmedString(request.method);
+            const validationErrors = [];
+            if (!method)
+                validationErrors.push('missing method');
+            if (typeof id !== 'number' && typeof id !== 'string')
+                validationErrors.push(`invalid id type: ${typeof id}`);
+            if (validationErrors.length > 0) {
+                host.error(`invalid request: ${validationErrors.join(', ')}`);
+                return;
+            }
+            const dispatcher = (0, dispatcher_1.createRuntimeDispatcher)(options, host, {
+                async sendResult(requestId, result) {
+                    await sendMessage(currentTransport, {
+                        jsonrpc: '2.0',
+                        id: requestId,
+                        result,
+                    });
+                },
+                async sendError(requestId, code, message, data) {
+                    await sendMessage(currentTransport, {
+                        jsonrpc: '2.0',
+                        id: requestId,
+                        error: {
+                            code,
+                            message,
+                            ...(data == null ? {} : { data }),
+                        },
+                    });
+                },
+            });
+            const methodName = method;
+            const params = asRecord(request.params) ?? {};
+            const requestId = id;
+            await dispatcher(requestId, methodName, params);
+        },
+    };
+    return runtime;
+}
+/** Starts a previously created plugin runtime on process stdio. */
+function startPluginRuntime(runtime, transport) {
+    runtime.start(transport);
+}
+/** Returns the default stdio transport used by the runtime. */
+function defaultTransport() {
+    return {
+        stdin: process.stdin,
+        stdout: process.stdout,
+    };
+}
+/** Sends one JSON-RPC response or notification through the active transport. */
+async function sendMessage(transport, value) {
+    await (0, transport_1.writeFramedMessage)((transport ?? defaultTransport()).stdout, value);
+}
+/** Builds the host helper for the currently active transport. */
+function createRuntimeHost(transport, logTarget) {
+    return (0, host_1.createHost)(async (method, params) => {
+        await sendMessage(transport, {
+            jsonrpc: '2.0',
+            method,
+            params,
+        });
+    }, { logTarget });
+}
+/** Type guard that returns true if the value is a valid RequestParams object. */
+function isRequestParams(value) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    return true;
+}
+/** Coerces unknown request method values into trimmed strings. Returns null for non-strings. */
+function asTrimmedString(value) {
+    return typeof value === 'string' ? value.trim() : null;
+}
+/** Coerces unknown params to a Record, returning null for invalid input. */
+function asRecord(value) {
+    if (isRequestParams(value)) {
+        return value;
+    }
+    return null;
+}
+/** Normalizes incoming data chunks to UTF-8 buffers. */
+function normalizeChunk(chunk) {
+    return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, 'utf8');
+}

package/lib/runtime/transport.d.ts

@@ -0,0 +1,14 @@
+import type { JsonRpcRequest } from '../types';
+/** Describes the parsed result of draining one buffered transport chunk. */
+export interface FramedMessageParseResult {
+    /** Stores the decoded requests found in the current buffer. */
+    messages: JsonRpcRequest[];
+    /** Stores any remaining incomplete bytes. */
+    remainder: Buffer;
+}
+/** Serializes one JSON-RPC payload into an LSP-style framed stdio message. */
+export declare function serializeFramedMessage(value: unknown): Buffer;
+/** Writes one JSON-RPC payload to the supplied stdout-like stream. */
+export declare function writeFramedMessage(writer: NodeJS.WritableStream, value: unknown): Promise<void>;
+/** Parses all complete framed JSON-RPC requests currently present in a buffer. */
+export declare function parseFramedMessages(buffer: Buffer): FramedMessageParseResult;

package/lib/runtime/transport.js

@@ -0,0 +1,72 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeFramedMessage = serializeFramedMessage;
+exports.writeFramedMessage = writeFramedMessage;
+exports.parseFramedMessages = parseFramedMessages;
+/** Serializes one JSON-RPC payload into an LSP-style framed stdio message. */
+function serializeFramedMessage(value) {
+    const payload = Buffer.from(JSON.stringify(value), 'utf8');
+    const header = Buffer.from(`Content-Length: ${payload.length}\r\n\r\n`, 'utf8');
+    return Buffer.concat([header, payload]);
+}
+/** Writes one JSON-RPC payload to the supplied stdout-like stream. */
+async function writeFramedMessage(writer, value) {
+    try {
+        const serialized = serializeFramedMessage(value);
+        const canContinue = writer.write(serialized);
+        if (!canContinue) {
+            await new Promise((resolve) => writer.once('drain', resolve));
+        }
+    }
+    catch (error) {
+        console.error(`[transport] failed to write framed message: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Parses all complete framed JSON-RPC requests currently present in a buffer. */
+function parseFramedMessages(buffer) {
+    const messages = [];
+    let remainder = buffer;
+    while (true) {
+        const marker = remainder.indexOf('\r\n\r\n');
+        if (marker < 0) {
+            return { messages, remainder };
+        }
+        const header = remainder.subarray(0, marker).toString('utf8');
+        const contentLength = readContentLength(header);
+        if (contentLength == null) {
+            remainder = remainder.subarray(marker + 4);
+            continue;
+        }
+        const totalLength = marker + 4 + contentLength;
+        if (remainder.length < totalLength) {
+            return { messages, remainder };
+        }
+        const payload = remainder.subarray(marker + 4, totalLength).toString('utf8');
+        remainder = remainder.subarray(totalLength);
+        try {
+            messages.push(JSON.parse(payload));
+        }
+        catch {
+            continue;
+        }
+    }
+}
+/** Reads one `Content-Length` header value from a framed message header block. */
+function readContentLength(header) {
+    const headerLines = header.split(/\r?\n/g);
+    for (const line of headerLines) {
+        const separatorIndex = line.indexOf(':');
+        if (separatorIndex < 0) {
+            continue;
+        }
+        const name = line.slice(0, separatorIndex).trim().toLowerCase();
+        if (name !== 'content-length') {
+            continue;
+        }
+        const rawValue = Number(line.slice(separatorIndex + 1).trim());
+        return Number.isFinite(rawValue) && rawValue >= 0 ? rawValue : null;
+    }
+    return null;
+}