@openvcs/sdk 0.2.3 → 0.2.5

package/src/lib/init.ts

@@ -223,7 +223,7 @@ function writeCommonFiles(answers: InitAnswers): void {
     name: answers.pluginName,
     version: answers.pluginVersion,
     default_enabled: answers.defaultEnabled,
-    ...(answers.kind === "module" ? { module: { exec: "plugin.js" } } : {}),
+    ...(answers.kind === "module" ? { module: { exec: "openvcs-plugin.js" } } : {}),
   });
   writeText(path.join(answers.targetDir, ".gitignore"), "node_modules/\ndist/\n");
 }
@@ -241,8 +241,10 @@ function writeModuleTemplate(answers: InitAnswers): void {
       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",
     },
@@ -262,7 +264,7 @@ function writeModuleTemplate(answers: InitAnswers): void {
   });
   writeText(
     path.join(answers.targetDir, "src", "plugin.ts"),
-    "const message = \"OpenVCS plugin started\";\nprocess.stderr.write(`${message}\\n`);\n"
+    "// Copyright © 2025-2026 OpenVCS Contributors\n// SPDX-License-Identifier: GPL-3.0-or-later\n\nimport type { PluginModuleDefinition } from '@openvcs/sdk/runtime';\n\nexport const PluginDefinition: PluginModuleDefinition = {\n  plugin: {\n    async 'plugin.init'(_params, context) {\n      context.host.info('OpenVCS plugin started');\n      return null;\n    },\n  },\n};\n\n/** Runs plugin startup work before the generated runtime begins processing requests. */\nexport function OnPluginStart(): void {}\n"
   );
 }
 
@@ -277,7 +279,7 @@ function writeThemeTemplate(answers: InitAnswers): void {
       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}`,
     },
   });
@@ -363,4 +365,5 @@ export const __private = {
   defaultPluginIdFromDir,
   sanitizeIdToken,
   validatePluginId,
+  writeModuleTemplate,
 };

package/src/lib/runtime/contracts.ts

@@ -0,0 +1,52 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+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/src/lib/runtime/dispatcher.ts

@@ -0,0 +1,185 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import {
+  PLUGIN_INTERNAL_ERROR_CODE,
+  PROTOCOL_VERSION,
+  PROTOCOL_VERSION_MISMATCH_CODE,
+} from '../types';
+import type {
+  JsonRpcId,
+  PluginDelegates,
+  PluginImplements,
+  RequestParams,
+  RpcMethodHandler,
+  VcsDelegates,
+} from '../types';
+import type { PluginHost } from '../types';
+
+import type { CreatePluginRuntimeOptions, PluginRuntimeContext } from './contracts';
+import { isPluginFailure, pluginError } from './errors';
+
+/** 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 function createDefaultPluginDelegates<
+  TContext,
+>(): Required<Omit<PluginDelegates<TContext>, 'plugin.initialize'>> {
+  return {
+    async 'plugin.init'(): Promise<null> {
+      return null;
+    },
+    async 'plugin.deinit'(): Promise<null> {
+      return null;
+    },
+    async 'plugin.get_menus'(): Promise<[]> {
+      return [];
+    },
+    async 'plugin.handle_action'(): Promise<null> {
+      return null;
+    },
+    async 'plugin.settings.defaults'(): Promise<[]> {
+      return [];
+    },
+    async 'plugin.settings.on_load'(params: { values?: unknown[] }): Promise<unknown[]> {
+      return Array.isArray(params.values) ? params.values : [];
+    },
+    async 'plugin.settings.on_apply'(): Promise<null> {
+      return null;
+    },
+    async 'plugin.settings.on_save'(params: { values?: unknown[] }): Promise<unknown[]> {
+      return Array.isArray(params.values) ? params.values : [];
+    },
+    async 'plugin.settings.on_reset'(): Promise<null> {
+      return null;
+    },
+  };
+}
+
+/** Creates the JSON-RPC dispatcher used by the SDK plugin runtime. */
+export function createRuntimeDispatcher(
+  options: CreatePluginRuntimeOptions,
+  host: PluginHost,
+  writer: DispatcherResponseWriter,
+): RuntimeRequestDispatcher {
+  const defaultPluginDelegates = createDefaultPluginDelegates<PluginRuntimeContext>();
+  const pluginDelegates = options.plugin ?? {};
+  const vcsDelegates = options.vcs ?? {};
+  const runtimeImplements = buildRuntimeImplements(options.implements, options.vcs);
+  const timeout = options.timeout;
+  const typedPluginDelegates = pluginDelegates as Record<
+    string,
+    RpcMethodHandler<RequestParams, unknown, PluginRuntimeContext> | undefined
+  >;
+  const typedDefaultPluginDelegates = defaultPluginDelegates as Record<
+    string,
+    RpcMethodHandler<RequestParams, unknown, PluginRuntimeContext> | undefined
+  >;
+  const typedVcsDelegates = vcsDelegates as Record<
+    string,
+    RpcMethodHandler<RequestParams, unknown, PluginRuntimeContext> | undefined
+  >;
+
+  return async (id: JsonRpcId, method: string, params: RequestParams): Promise<void> => {
+    try {
+      if (method === 'plugin.initialize') {
+        const expectedVersion = params.expected_protocol_version;
+        if (typeof expectedVersion === 'number' && expectedVersion !== PROTOCOL_VERSION) {
+          writer.sendError(id, PROTOCOL_VERSION_MISMATCH_CODE, 'protocol version mismatch', {
+            code: 'protocol-version-mismatch',
+            message: `host expects protocol ${expectedVersion}, plugin supports ${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 ?? PROTOCOL_VERSION,
+          implements: {
+            ...runtimeImplements,
+            ...override.implements,
+          },
+        });
+        return;
+      }
+
+      const handler =
+        typedPluginDelegates[method] ??
+        typedDefaultPluginDelegates[method] ??
+        typedVcsDelegates[method];
+
+      if (!handler) {
+        throw pluginError('rpc-method-not-found', `method '${method}' is not implemented`);
+      }
+
+      let result: unknown;
+      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 as Error).name === 'AbortError') {
+            throw 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 (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, PLUGIN_INTERNAL_ERROR_CODE, messageText, {
+        code: 'plugin-internal-error',
+        message: messageText,
+      });
+    }
+  };
+}
+
+/** Builds the handshake capability flags returned from `plugin.initialize`. */
+function buildRuntimeImplements(
+  overrides: Partial<PluginImplements> | undefined,
+  vcsDelegates: VcsDelegates<PluginRuntimeContext> | undefined,
+): PluginImplements {
+  return {
+    plugin: overrides?.plugin ?? true,
+    vcs: overrides?.vcs ?? Boolean(vcsDelegates && Object.keys(vcsDelegates).length > 0),
+  };
+}

package/src/lib/runtime/errors.ts

@@ -0,0 +1,27 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PLUGIN_FAILURE_CODE } from '../types';
+import type { PluginFailure } from '../types';
+
+/** Builds the host-facing plugin failure payload used for operational errors. */
+export function pluginError(code: string, message: string): PluginFailure {
+  return {
+    code: PLUGIN_FAILURE_CODE,
+    message,
+    data: {
+      code,
+      message,
+    },
+  };
+}
+
+/** Returns whether the supplied value is a structured plugin failure. */
+export function isPluginFailure(value: unknown): value is PluginFailure {
+  if (value == null || typeof value !== 'object') {
+    return false;
+  }
+
+  const candidate = value as Partial<PluginFailure>;
+  return candidate.code === PLUGIN_FAILURE_CODE && typeof candidate.message === 'string';
+}

package/src/lib/runtime/factory.ts

@@ -0,0 +1,182 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type { JsonRpcId, JsonRpcRequest, RequestParams } from '../types';
+
+import type {
+  CreatePluginRuntimeOptions,
+  PluginRuntime,
+  PluginRuntimeTransport,
+} from './contracts';
+import { createRuntimeDispatcher } from './dispatcher';
+import { createHost } from './host';
+import { parseFramedMessages, writeFramedMessage } from './transport';
+
+/** Creates a reusable stdio JSON-RPC runtime for OpenVCS Node plugins. */
+export function createPluginRuntime(
+  options: CreatePluginRuntimeOptions = {},
+): PluginRuntime {
+  let buffer: Buffer<ArrayBufferLike> = Buffer.alloc(0);
+  let processing: Promise<void> = Promise.resolve();
+  let started = false;
+  let currentTransport: PluginRuntimeTransport | null = null;
+  let chunkLock: Promise<void> = Promise.resolve();
+
+  const runtime: PluginRuntime = {
+    start(transport: PluginRuntimeTransport = defaultTransport()): void {
+      if (started) {
+        return;
+      }
+
+      started = true;
+      currentTransport = transport;
+      transport.stdin.on('data', (chunk: Buffer | string) => {
+        runtime.consumeChunk(chunk);
+      });
+      transport.stdin.on('error', () => {
+        process.exit(1);
+      });
+      options.onStart?.();
+    },
+    stop(): void {
+      if (!started) {
+        return;
+      }
+      started = false;
+      processing = processing
+        .catch(async (error: unknown) => {
+          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: Buffer | string): void {
+      if (!started) {
+        return;
+      }
+
+      const lock = chunkLock.then(() => {
+        buffer = Buffer.concat([buffer, normalizeChunk(chunk)]);
+        const parsed = parseFramedMessages(buffer);
+        buffer = parsed.remainder;
+
+        for (const request of parsed.messages) {
+          processing = processing
+            .then(async () => {
+              await runtime.dispatchRequest(request);
+            })
+            .catch((error: unknown) => {
+              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: JsonRpcRequest): Promise<void> {
+      const id = request.id;
+      const host = createRuntimeHost(currentTransport, options.logTarget);
+      const method = asTrimmedString(request.method);
+      const validationErrors: string[] = [];
+      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 = createRuntimeDispatcher(options, host, {
+        async sendResult<TResult>(requestId: JsonRpcId, result: TResult): Promise<void> {
+          await sendMessage(currentTransport, {
+            jsonrpc: '2.0',
+            id: requestId,
+            result,
+          });
+        },
+        async sendError(requestId: JsonRpcId, code: number, message: string, data?: unknown): Promise<void> {
+          await sendMessage(currentTransport, {
+            jsonrpc: '2.0',
+            id: requestId,
+            error: {
+              code,
+              message,
+              ...(data == null ? {} : { data }),
+            },
+          });
+        },
+      });
+
+      const methodName = method as string;
+      const params = asRecord(request.params) ?? {};
+      const requestId = id as JsonRpcId;
+      await dispatcher(requestId, methodName, params);
+    },
+  };
+
+  return runtime;
+}
+
+/** Returns the default stdio transport used by the runtime. */
+function defaultTransport(): PluginRuntimeTransport {
+  return {
+    stdin: process.stdin,
+    stdout: process.stdout,
+  };
+}
+
+/** Sends one JSON-RPC response or notification through the active transport. */
+async function sendMessage(
+  transport: PluginRuntimeTransport | null,
+  value: unknown,
+): Promise<void> {
+  await writeFramedMessage((transport ?? defaultTransport()).stdout, value);
+}
+
+/** Builds the host helper for the currently active transport. */
+function createRuntimeHost(
+  transport: PluginRuntimeTransport | null,
+  logTarget: string | undefined,
+) {
+  return createHost(
+    async (method: string, params: unknown) => {
+      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: unknown): value is RequestParams {
+  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: unknown): string | null {
+  return typeof value === 'string' ? value.trim() : null;
+}
+
+/** Coerces unknown params to a Record, returning null for invalid input. */
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (isRequestParams(value)) {
+    return value as Record<string, unknown>;
+  }
+  return null;
+}
+
+/** Normalizes incoming data chunks to UTF-8 buffers. */
+function normalizeChunk(chunk: Buffer | string): Buffer {
+  return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, 'utf8');
+}

package/src/lib/runtime/host.ts

@@ -0,0 +1,72 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type {
+  HostEventEmitParams,
+  HostLogLevel,
+  HostStatusSetParams,
+  HostUiNotifyParams,
+  JsonRpcId,
+  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 function createHost(
+  sendNotification: HostNotificationSender,
+  options: CreateHostOptions = {},
+): PluginHost {
+  const logTarget = options.logTarget ?? 'openvcs.plugin';
+
+  return {
+    log(level: HostLogLevel, message: string): void {
+      sendNotification('host.log', {
+        level,
+        target: logTarget,
+        message,
+      });
+    },
+    info(message: string): void {
+      sendNotification('host.log', {
+        level: 'info',
+        target: logTarget,
+        message,
+      });
+    },
+    error(message: string): void {
+      sendNotification('host.log', {
+        level: 'error',
+        target: logTarget,
+        message,
+      });
+    },
+    uiNotify(params: HostUiNotifyParams): void {
+      sendNotification('host.ui_notify', params);
+    },
+    statusSet(params: HostStatusSetParams): void {
+      sendNotification('host.status_set', params);
+    },
+    emitEvent(params: HostEventEmitParams): void {
+      sendNotification('host.event_emit', params);
+    },
+    emitVcsEvent(
+      sessionId: string,
+      requestId: JsonRpcId | null,
+      event: Record<string, unknown>,
+    ): void {
+      sendNotification('vcs.event', {
+        session_id: sessionId,
+        request_id: requestId,
+        event,
+      });
+    },
+  };
+}

package/src/lib/runtime/index.ts

@@ -0,0 +1,36 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type {
+  PluginRuntime,
+  PluginRuntimeTransport,
+} from './contracts';
+
+export type {
+  CreatePluginRuntimeOptions,
+  PluginRuntime,
+  PluginRuntimeContext,
+  PluginRuntimeTransport,
+} from './contracts';
+export type {
+  BootstrapPluginModuleOptions,
+  OnPluginStartHandler,
+  PluginBootstrapModule,
+  PluginModuleDefinition,
+} from './registration';
+export { createDefaultPluginDelegates, createRuntimeDispatcher } from './dispatcher';
+export { isPluginFailure, pluginError } from './errors';
+export { createPluginRuntime } from './factory';
+export { createHost } from './host';
+export {
+  bootstrapPluginModule,
+  createRegisteredPluginRuntime,
+} from './registration';
+
+/** Starts a previously created plugin runtime on process stdio. */
+export function startPluginRuntime(
+  runtime: PluginRuntime,
+  transport?: PluginRuntimeTransport,
+): void {
+  runtime.start(transport);
+}

package/src/lib/runtime/registration.ts

@@ -0,0 +1,93 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type {
+  PluginDelegates,
+  PluginImplements,
+  VcsDelegates,
+} from '../types';
+
+import type {
+  CreatePluginRuntimeOptions,
+  PluginRuntime,
+  PluginRuntimeContext,
+  PluginRuntimeTransport,
+} from './contracts';
+import { createPluginRuntime } from './factory';
+
+/** Describes the plugin module startup hook invoked by the generated bootstrap. */
+export type OnPluginStartHandler = () => void | Promise<void>;
+
+/** Describes runtime-wide options applied by the generated bootstrap. */
+export interface PluginModuleDefinition {
+  /** Stores optional `plugin.*` delegates contributed by the plugin module. */
+  plugin?: PluginDelegates<PluginRuntimeContext>;
+  /** Stores optional `vcs.*` delegates contributed by the plugin module. */
+  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 during stop() after pending operations complete. */
+  onShutdown?: (error?: Error) => void | Promise<void>;
+}
+
+/** Describes one imported plugin module consumed by the generated bootstrap. */
+export interface PluginBootstrapModule {
+  /** Stores the plugin author's declarative runtime definition. */
+  PluginDefinition?: PluginModuleDefinition;
+  /** Stores the plugin author's startup hook. */
+  OnPluginStart?: OnPluginStartHandler;
+}
+
+/** Describes the generated bootstrap inputs used to import and start a plugin. */
+export interface BootstrapPluginModuleOptions {
+  /** Imports the plugin author's compiled runtime module. */
+  importPluginModule: () => Promise<PluginBootstrapModule>;
+  /** Stores the plugin module path for error messages. */
+  modulePath: string;
+  /** Overrides the transport used by the runtime loop. */
+  transport?: PluginRuntimeTransport;
+}
+
+/** Creates a runtime from one declarative plugin module definition. */
+export function createRegisteredPluginRuntime(
+  definition: PluginModuleDefinition = {},
+): PluginRuntime {
+  const options: CreatePluginRuntimeOptions = {
+    plugin: definition.plugin,
+    vcs: definition.vcs,
+    implements: definition.implements,
+    logTarget: definition.logTarget,
+    timeout: definition.timeout,
+    onShutdown: definition.onShutdown,
+  };
+  return createPluginRuntime(options);
+}
+
+/** Imports the author module, applies its definition, runs `OnPluginStart`, and starts the runtime loop. */
+export async function bootstrapPluginModule(
+  options: BootstrapPluginModuleOptions,
+): Promise<PluginRuntime> {
+  const pluginModule = await options.importPluginModule();
+  const onPluginStart = pluginModule.OnPluginStart;
+
+  if (typeof onPluginStart !== 'function') {
+    throw new Error(
+      `plugin module '${options.modulePath}' must export OnPluginStart()`,
+    );
+  }
+
+  try {
+    await onPluginStart();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`plugin startup failed: ${message}`);
+  }
+
+  const runtime = createRegisteredPluginRuntime(pluginModule.PluginDefinition);
+  runtime.start(options.transport);
+  return runtime;
+}