@openvcs/sdk 0.3.0-nightly.20260423.29 → 0.3.0

package/lib/runtime/index.d.ts

@@ -9,7 +9,7 @@ export { ModalBuilder } from './modal';
 export { bootstrapPluginModule, createRegisteredPluginRuntime, } from './registration';
 export { VcsDelegateBase } from './vcs-delegate-base';
 export type { VcsDelegateAssignments } from './vcs-delegate-metadata';
-export { getMenu, getOrCreateMenu, createMenu, addMenuItem, addMenuSeparator, removeMenu, hideMenu, showMenu, registerAction, invoke, notify, } from './menu';
+export { getMenu, getOrCreateMenu, createMenu, addMenuItem, addMenuSeparator, removeMenu, hideMenu, showMenu, registerAction, resetMenuRegistry, invoke, notify, } from './menu';
 export type { MenuHandle } from './menu';
 /** Starts a previously created plugin runtime on process stdio. */
 export declare function startPluginRuntime(runtime: PluginRuntime, transport?: PluginRuntimeTransport): void;

package/lib/runtime/index.js

@@ -2,7 +2,7 @@
 // Copyright © 2025-2026 OpenVCS Contributors
 // SPDX-License-Identifier: GPL-3.0-or-later
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.notify = exports.invoke = exports.registerAction = exports.showMenu = exports.hideMenu = exports.removeMenu = exports.addMenuSeparator = exports.addMenuItem = exports.createMenu = exports.getOrCreateMenu = exports.getMenu = exports.VcsDelegateBase = exports.createRegisteredPluginRuntime = exports.bootstrapPluginModule = exports.ModalBuilder = exports.createHost = exports.createPluginRuntime = exports.pluginError = exports.isPluginFailure = exports.createRuntimeDispatcher = exports.createDefaultPluginDelegates = void 0;
+exports.notify = exports.invoke = exports.resetMenuRegistry = exports.registerAction = exports.showMenu = exports.hideMenu = exports.removeMenu = exports.addMenuSeparator = exports.addMenuItem = exports.createMenu = exports.getOrCreateMenu = exports.getMenu = exports.VcsDelegateBase = exports.createRegisteredPluginRuntime = exports.bootstrapPluginModule = exports.ModalBuilder = exports.createHost = exports.createPluginRuntime = exports.pluginError = exports.isPluginFailure = exports.createRuntimeDispatcher = exports.createDefaultPluginDelegates = void 0;
 exports.startPluginRuntime = startPluginRuntime;
 var dispatcher_1 = require("./dispatcher");
 Object.defineProperty(exports, "createDefaultPluginDelegates", { enumerable: true, get: function () { return dispatcher_1.createDefaultPluginDelegates; } });
@@ -31,6 +31,7 @@ Object.defineProperty(exports, "removeMenu", { enumerable: true, get: function (
 Object.defineProperty(exports, "hideMenu", { enumerable: true, get: function () { return menu_1.hideMenu; } });
 Object.defineProperty(exports, "showMenu", { enumerable: true, get: function () { return menu_1.showMenu; } });
 Object.defineProperty(exports, "registerAction", { enumerable: true, get: function () { return menu_1.registerAction; } });
+Object.defineProperty(exports, "resetMenuRegistry", { enumerable: true, get: function () { return menu_1.resetMenuRegistry; } });
 Object.defineProperty(exports, "invoke", { enumerable: true, get: function () { return menu_1.invoke; } });
 Object.defineProperty(exports, "notify", { enumerable: true, get: function () { return menu_1.notify; } });
 /** Starts a previously created plugin runtime on process stdio. */

package/lib/runtime/menu.d.ts

@@ -1,17 +1,27 @@
 import type { MenubarItem } from '../types/menubar.js';
-import type { PluginDelegates } from '../types/plugin.js';
+import type { PluginDelegates, PluginHandleActionParams } from '../types/plugin.js';
 import type { PluginRuntimeContext } from './contracts.js';
 type MenubarMenuOptions = {
     before?: string;
     after?: string;
 };
+/** UI surface targeted by a menu: 'menubar' (top-level bar) or 'settings' (preferences panel). */
 type MenuSurface = 'menubar' | 'settings';
+/** Validates and returns the incoming plugin action id. */
+export declare function requireActionId(params: PluginHandleActionParams): string;
+/** Clears all registered menus and action handlers.
+ * @internal
+ * Called by bootstrap to prevent state leaking between in-process plugin setup runs.
+ */
+export declare function resetMenuRegistry(): void;
+/** Returns whether one registered action handler exists. */
+export declare function hasRegisteredAction(actionId: string): boolean;
 /** Runs a registered action handler by id. */
 export declare function runRegisteredAction(actionId: string, ...args: unknown[]): Promise<unknown>;
 export interface MenuHandle {
     id: string;
     addItem(item: MenubarItem): void;
-    addSeparator(beforeAction?: string): void;
+    addSeparator(beforeAction?: string, afterAction?: string): void;
     removeItem(actionId: string): void;
     hideItem(actionId: string): void;
     showItem(actionId: string): void;
@@ -19,19 +29,19 @@ export interface MenuHandle {
 /** Returns a menu by id, or null when it does not exist. */
 export declare function getMenu(menuId: string): MenuHandle | null;
 /** Returns a menu by id, creating it if needed.
- * @param menuId - Menu identifier
- * @param label - User-visible label
- * @param options - Surface target ('menubar' or 'settings'), MUST be explicitly provided
+ * @param menuId - Menu identifier.
+ * @param label - User-visible label.
+ * @param options - Placement options, including the required `surface` so the runtime can serialize the menu for the correct host UI surface.
  */
 export declare function getOrCreateMenu(menuId: string, label: string, options: MenubarMenuOptions & {
     surface: MenuSurface;
 }): MenuHandle | null;
 /** Creates a menu at a specific position (alias for getOrCreateMenu). */
 export declare const createMenu: typeof getOrCreateMenu;
-/** Adds one item to a menu. */
+/** Adds one item to a menu, silently no-op if the menu does not exist. */
 export declare function addMenuItem(menuId: string, item: MenubarItem): void;
-/** Adds one separator to a menu. */
-export declare function addMenuSeparator(menuId: string, beforeAction?: string): void;
+/** Adds one separator to a menu, silently no-op if the menu does not exist. */
+export declare function addMenuSeparator(menuId: string, beforeAction?: string, afterAction?: string): void;
 /** Removes one menu from the registry. */
 export declare function removeMenu(menuId: string): void;
 /** Hides one menu from the registry. */

package/lib/runtime/menu.js

@@ -3,6 +3,9 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMenu = void 0;
+exports.requireActionId = requireActionId;
+exports.resetMenuRegistry = resetMenuRegistry;
+exports.hasRegisteredAction = hasRegisteredAction;
 exports.runRegisteredAction = runRegisteredAction;
 exports.getMenu = getMenu;
 exports.getOrCreateMenu = getOrCreateMenu;
@@ -15,10 +18,29 @@ exports.registerAction = registerAction;
 exports.invoke = invoke;
 exports.notify = notify;
 exports.createMenuPluginDelegates = createMenuPluginDelegates;
+const errors_js_1 = require("./errors.js");
 const menus = new Map();
 const menuOrder = [];
 const actionHandlers = new Map();
 let syntheticId = 0;
+/** Validates and returns the incoming plugin action id. */
+function requireActionId(params) {
+    const actionId = typeof params?.action_id === 'string' ? params.action_id.trim() : '';
+    if (!actionId) {
+        throw (0, errors_js_1.pluginError)('plugin-invalid-action-id', 'plugin.handle_action requires params.action_id to be a non-empty string');
+    }
+    return actionId;
+}
+/** Clears all registered menus and action handlers.
+ * @internal
+ * Called by bootstrap to prevent state leaking between in-process plugin setup runs.
+ */
+function resetMenuRegistry() {
+    menus.clear();
+    menuOrder.splice(0, menuOrder.length);
+    actionHandlers.clear();
+    syntheticId = 0;
+}
 /** Returns the host-side OpenVCS helper, when the environment provides one. */
 function getOpenVCS() {
     return globalThis.OpenVCS;
@@ -157,6 +179,13 @@ function serializeMenus() {
     })
         .filter((menu) => Boolean(menu));
 }
+/** Returns whether one registered action handler exists. */
+function hasRegisteredAction(actionId) {
+    const id = String(actionId || '').trim();
+    if (!id)
+        return false;
+    return actionHandlers.has(id);
+}
 /** Runs a registered action handler by id. */
 async function runRegisteredAction(actionId, ...args) {
     const id = String(actionId || '').trim();
@@ -190,7 +219,7 @@ function createMenuHandle(menuId) {
                 action,
             }, item.before, item.after);
         },
-        addSeparator(beforeAction) {
+        addSeparator(beforeAction, afterAction) {
             let menu = getStoredMenu(this.id);
             if (!menu) {
                 // Default to menubar for internal menu handle operations.
@@ -201,7 +230,7 @@ function createMenuHandle(menuId) {
                 id: allocateSyntheticId(`${menu.id}-separator`),
                 label: 'Separator',
                 content: '—',
-            }, beforeAction);
+            }, beforeAction, afterAction);
         },
         removeItem(actionId) {
             const menu = getStoredMenu(this.id);
@@ -236,25 +265,29 @@ function getMenu(menuId) {
     return createMenuHandle(stored.id);
 }
 /** Returns a menu by id, creating it if needed.
- * @param menuId - Menu identifier
- * @param label - User-visible label
- * @param options - Surface target ('menubar' or 'settings'), MUST be explicitly provided
+ * @param menuId - Menu identifier.
+ * @param label - User-visible label.
+ * @param options - Placement options, including the required `surface` so the runtime can serialize the menu for the correct host UI surface.
  */
 function getOrCreateMenu(menuId, label, options) {
-    const surface = options.surface;
-    const { surface: _, ...restOptions } = options;
+    const { surface, ...restOptions } = options;
     const stored = ensureStoredMenu(menuId, label, restOptions, surface);
     return createMenuHandle(stored.id);
 }
 /** Creates a menu at a specific position (alias for getOrCreateMenu). */
 exports.createMenu = getOrCreateMenu;
-/** Adds one item to a menu. */
+/** Adds one item to a menu, silently no-op if the menu does not exist. */
 function addMenuItem(menuId, item) {
-    createMenuHandle(menuId).addItem(item);
+    const handle = createMenuHandle(menuId);
+    if (!getStoredMenu(menuId))
+        return;
+    handle.addItem(item);
 }
-/** Adds one separator to a menu. */
-function addMenuSeparator(menuId, beforeAction) {
-    createMenuHandle(menuId).addSeparator(beforeAction);
+/** Adds one separator to a menu, silently no-op if the menu does not exist. */
+function addMenuSeparator(menuId, beforeAction, afterAction) {
+    if (!getStoredMenu(menuId))
+        return;
+    createMenuHandle(menuId).addSeparator(beforeAction, afterAction);
 }
 /** Removes one menu from the registry. */
 function removeMenu(menuId) {
@@ -292,7 +325,10 @@ function invoke(cmd, args) {
 /** Emits a notification when the host helper is available. */
 function notify(msg) {
     const openvcs = getOpenVCS();
-    openvcs?.notify(msg);
+    if (!openvcs) {
+        throw new Error('OpenVCS host is not available in this runtime');
+    }
+    openvcs.notify(msg);
 }
 /** Builds SDK delegates from the local menu/action registries. */
 function createMenuPluginDelegates() {
@@ -301,11 +337,7 @@ function createMenuPluginDelegates() {
             return serializeMenus();
         },
         async 'plugin.handle_action'(params) {
-            const actionId = String(params?.action_id || params?.id || '').trim();
-            if (actionId) {
-                return await runRegisteredAction(actionId, params?.payload);
-            }
-            return null;
+            return await runRegisteredAction(requireActionId(params), params?.payload);
         },
     };
 }

package/lib/runtime/registration.js

@@ -26,8 +26,8 @@ function createRegisteredPluginRuntime(definition = {}) {
                 ];
             },
             'plugin.handle_action': async (params, ctx) => {
-                const actionId = String(params?.action_id || '').trim();
-                if (actionId) {
+                const actionId = (0, menu_1.requireActionId)(params);
+                if ((0, menu_1.hasRegisteredAction)(actionId)) {
                     const result = await (0, menu_1.runRegisteredAction)(actionId, params?.payload);
                     if (result !== null && result !== undefined) {
                         return result;
@@ -36,6 +36,7 @@ function createRegisteredPluginRuntime(definition = {}) {
                 if (explicitHandleAction) {
                     return explicitHandleAction(params, ctx);
                 }
+                ctx.host.info(`plugin.handle_action ignored unhandled action_id '${actionId}'`);
                 return null;
             },
         },
@@ -54,6 +55,8 @@ async function bootstrapPluginModule(options) {
     if (typeof onPluginStart !== 'function') {
         throw new Error(`plugin module '${options.modulePath}' must export OnPluginStart()`);
     }
+    // Reset internal state so repeated in-process setups do not leak menu or action state.
+    (0, menu_1.resetMenuRegistry)();
     try {
         await onPluginStart();
     }

package/lib/types/menubar.d.ts

@@ -22,8 +22,8 @@ export interface MenubarMenu {
     id: string;
     /** Adds an item to this menu. */
     addItem(item: MenubarItem): void;
-    /** Adds a separator to this menu. */
-    addSeparator(beforeAction?: string): void;
+    /** Adds a separator to this menu before or after an existing action. */
+    addSeparator(beforeAction?: string, afterAction?: string): void;
     /** Removes an item by action ID. */
     removeItem(actionId: string): void;
     /** Hides an item by action ID. */

package/lib/types/plugin.d.ts

@@ -54,9 +54,7 @@ export interface PluginMenuDefinition {
 export type PluginSettingsValue = Record<string, unknown>;
 /** Describes the params shape for plugin action handling. */
 export interface PluginHandleActionParams extends RequestParams {
-    /** Stores the action id selected by the user when provided by the transport. */
-    id?: string;
-    /** Stores the action id selected by the user. */
+    /** Stores the action id selected by the user. Runtime handlers require a non-empty string. */
     action_id?: string;
     /** Stores an optional payload supplied by the triggering UI. */
     payload?: Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvcs/sdk",
-  "version": "0.3.0-nightly.20260423.29",
+  "version": "0.3.0",
   "description": "OpenVCS SDK CLI for plugin scaffolding and runtime asset builds",
   "license": "GPL-3.0-or-later",
   "homepage": "https://openvcs.app/",
@@ -40,7 +40,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.3.3",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   },
   "files": [
     "src/",

package/src/lib/runtime/index.ts

@@ -39,6 +39,7 @@ export {
   hideMenu,
   showMenu,
   registerAction,
+  resetMenuRegistry,
   invoke,
   notify,
 } from './menu';

package/src/lib/runtime/menu.ts

@@ -5,13 +5,16 @@ import type { MenubarItem } from '../types/menubar.js';
 import type {
   PluginDelegates,
   PluginHandleActionParams,
+  PluginMenuElement,
   PluginMenuDefinition,
 } from '../types/plugin.js';
 
 import type { PluginRuntimeContext } from './contracts.js';
+import { pluginError } from './errors.js';
 
 type MenubarMenuOptions = { before?: string; after?: string };
 type MenuEntryKind = 'button' | 'text' | 'separator';
+/** UI surface targeted by a menu: 'menubar' (top-level bar) or 'settings' (preferences panel). */
 type MenuSurface = 'menubar' | 'settings';
 
 type OpenVCSGlobal = typeof globalThis & {
@@ -27,6 +30,7 @@ interface StoredMenuItem {
   label: string;
   title?: string;
   content?: string;
+  /** Action id dispatched back to the plugin when the user activates this item. */
   action?: string;
   hidden?: boolean;
 }
@@ -40,26 +44,34 @@ interface StoredMenuState {
   items: StoredMenuItem[];
 }
 
-interface SerializedMenuItem {
-  type: 'button' | 'text';
-  id: string;
-  label?: string;
-  content?: string;
-}
-
-interface SerializedMenuDefinition {
-  id: string;
-  label: string;
-  order: number;
-  surface: 'menubar' | 'settings';
-  elements: SerializedMenuItem[];
-}
-
 const menus = new Map<string, StoredMenuState>();
 const menuOrder: string[] = [];
 const actionHandlers = new Map<string, (...args: unknown[]) => unknown>();
 let syntheticId = 0;
 
+/** Validates and returns the incoming plugin action id. */
+export function requireActionId(params: PluginHandleActionParams): string {
+  const actionId = typeof params?.action_id === 'string' ? params.action_id.trim() : '';
+  if (!actionId) {
+    throw pluginError(
+      'plugin-invalid-action-id',
+      'plugin.handle_action requires params.action_id to be a non-empty string',
+    );
+  }
+  return actionId;
+}
+
+/** Clears all registered menus and action handlers.
+ * @internal
+ * Called by bootstrap to prevent state leaking between in-process plugin setup runs.
+ */
+export function resetMenuRegistry(): void {
+  menus.clear();
+  menuOrder.splice(0, menuOrder.length);
+  actionHandlers.clear();
+  syntheticId = 0;
+}
+
 /** Returns the host-side OpenVCS helper, when the environment provides one. */
 function getOpenVCS() {
   return (globalThis as OpenVCSGlobal).OpenVCS;
@@ -177,7 +189,7 @@ function insertMenuItem(menu: StoredMenuState, item: StoredMenuItem, before?: st
 }
 
 /** Converts one stored item into a serializable menu payload element. */
-function serializeMenuItem(item: StoredMenuItem): SerializedMenuItem | null {
+function serializeMenuItem(item: StoredMenuItem): PluginMenuElement | null {
   if (item.hidden) return null;
 
   if (item.kind === 'separator') {
@@ -204,7 +216,7 @@ function serializeMenuItem(item: StoredMenuItem): SerializedMenuItem | null {
 }
 
 /** Serializes the local registry into plugin menu payloads. */
-function serializeMenus(): SerializedMenuDefinition[] {
+function serializeMenus(): PluginMenuDefinition[] {
   return menuOrder
     .map((menuId, index) => {
       const menu = menus.get(menuId);
@@ -216,10 +228,17 @@ function serializeMenus(): SerializedMenuDefinition[] {
         surface: menu.surface,
         elements: menu.items
           .map((item) => serializeMenuItem(item))
-          .filter((item): item is SerializedMenuItem => Boolean(item)),
+          .filter((item): item is PluginMenuElement => Boolean(item)),
       };
     })
-    .filter((menu): menu is SerializedMenuDefinition => Boolean(menu));
+    .filter((menu): menu is PluginMenuDefinition => Boolean(menu));
+}
+
+/** Returns whether one registered action handler exists. */
+export function hasRegisteredAction(actionId: string): boolean {
+  const id = String(actionId || '').trim();
+  if (!id) return false;
+  return actionHandlers.has(id);
 }
 
 /** Runs a registered action handler by id. */
@@ -236,7 +255,7 @@ export async function runRegisteredAction(actionId: string, ...args: unknown[]):
 export interface MenuHandle {
   id: string;
   addItem(item: MenubarItem): void;
-  addSeparator(beforeAction?: string): void;
+  addSeparator(beforeAction?: string, afterAction?: string): void;
   removeItem(actionId: string): void;
   hideItem(actionId: string): void;
   showItem(actionId: string): void;
@@ -266,7 +285,7 @@ function createMenuHandle(menuId: string): MenuHandle {
         action,
       }, item.before, item.after);
     },
-    addSeparator(beforeAction?: string) {
+    addSeparator(beforeAction?: string, afterAction?: string) {
       let menu = getStoredMenu(this.id);
       if (!menu) {
         // Default to menubar for internal menu handle operations.
@@ -277,7 +296,7 @@ function createMenuHandle(menuId: string): MenuHandle {
         id: allocateSyntheticId(`${menu.id}-separator`),
         label: 'Separator',
         content: '—',
-      }, beforeAction);
+      }, beforeAction, afterAction);
     },
     removeItem(actionId: string) {
       const menu = getStoredMenu(this.id);
@@ -308,17 +327,16 @@ export function getMenu(menuId: string): MenuHandle | null {
 }
 
 /** Returns a menu by id, creating it if needed.
- * @param menuId - Menu identifier
- * @param label - User-visible label
- * @param options - Surface target ('menubar' or 'settings'), MUST be explicitly provided
+ * @param menuId - Menu identifier.
+ * @param label - User-visible label.
+ * @param options - Placement options, including the required `surface` so the runtime can serialize the menu for the correct host UI surface.
  */
 export function getOrCreateMenu(
   menuId: string,
   label: string,
   options: MenubarMenuOptions & { surface: MenuSurface },
 ): MenuHandle | null {
-  const surface = options.surface;
-  const { surface: _, ...restOptions } = options;
+  const { surface, ...restOptions } = options;
   const stored = ensureStoredMenu(menuId, label, restOptions, surface);
   return createMenuHandle(stored.id);
 }
@@ -326,14 +344,17 @@ export function getOrCreateMenu(
 /** Creates a menu at a specific position (alias for getOrCreateMenu). */
 export const createMenu = getOrCreateMenu;
 
-/** Adds one item to a menu. */
+/** Adds one item to a menu, silently no-op if the menu does not exist. */
 export function addMenuItem(menuId: string, item: MenubarItem): void {
-  createMenuHandle(menuId).addItem(item);
+  const handle = createMenuHandle(menuId);
+  if (!getStoredMenu(menuId)) return;
+  handle.addItem(item);
 }
 
-/** Adds one separator to a menu. */
-export function addMenuSeparator(menuId: string, beforeAction?: string): void {
-  createMenuHandle(menuId).addSeparator(beforeAction);
+/** Adds one separator to a menu, silently no-op if the menu does not exist. */
+export function addMenuSeparator(menuId: string, beforeAction?: string, afterAction?: string): void {
+  if (!getStoredMenu(menuId)) return;
+  createMenuHandle(menuId).addSeparator(beforeAction, afterAction);
 }
 
 /** Removes one menu from the registry. */
@@ -374,21 +395,20 @@ export function invoke<T = unknown>(cmd: string, args?: unknown): Promise<T> {
 /** Emits a notification when the host helper is available. */
 export function notify(msg: string): void {
   const openvcs = getOpenVCS();
-  openvcs?.notify(msg);
+  if (!openvcs) {
+    throw new Error('OpenVCS host is not available in this runtime');
+  }
+  openvcs.notify(msg);
 }
 
 /** Builds SDK delegates from the local menu/action registries. */
 export function createMenuPluginDelegates(): PluginDelegates<PluginRuntimeContext> {
   return {
     async 'plugin.get_menus'(): Promise<PluginMenuDefinition[]> {
-      return serializeMenus() as unknown as PluginMenuDefinition[];
+      return serializeMenus();
     },
     async 'plugin.handle_action'(params: PluginHandleActionParams): Promise<unknown> {
-      const actionId = String(params?.action_id || params?.id || '').trim();
-      if (actionId) {
-        return await runRegisteredAction(actionId, params?.payload);
-      }
-      return null;
+      return await runRegisteredAction(requireActionId(params), params?.payload);
     },
   };
 }

package/src/lib/runtime/registration.ts

@@ -16,6 +16,9 @@ import type {
 import { createPluginRuntime } from './factory';
 import {
   createMenuPluginDelegates,
+  hasRegisteredAction,
+  requireActionId,
+  resetMenuRegistry,
   runRegisteredAction,
 } from './menu';
 
@@ -79,8 +82,8 @@ export function createRegisteredPluginRuntime(
         ];
       },
       'plugin.handle_action': async (params, ctx) => {
-        const actionId = String(params?.action_id || '').trim();
-        if (actionId) {
+        const actionId = requireActionId(params);
+        if (hasRegisteredAction(actionId)) {
           const result = await runRegisteredAction(actionId, params?.payload);
           if (result !== null && result !== undefined) {
             return result;
@@ -89,6 +92,7 @@ export function createRegisteredPluginRuntime(
         if (explicitHandleAction) {
           return explicitHandleAction(params, ctx);
         }
+        ctx.host.info(`plugin.handle_action ignored unhandled action_id '${actionId}'`);
         return null;
       },
     },
@@ -114,6 +118,9 @@ export async function bootstrapPluginModule(
     );
   }
 
+  // Reset internal state so repeated in-process setups do not leak menu or action state.
+  resetMenuRegistry();
+
   try {
     await onPluginStart();
   } catch (error) {

package/src/lib/types/menubar.ts

@@ -23,8 +23,8 @@ export interface MenubarMenu {
   id: string;
   /** Adds an item to this menu. */
   addItem(item: MenubarItem): void;
-  /** Adds a separator to this menu. */
-  addSeparator(beforeAction?: string): void;
+  /** Adds a separator to this menu before or after an existing action. */
+  addSeparator(beforeAction?: string, afterAction?: string): void;
   /** Removes an item by action ID. */
   removeItem(actionId: string): void;
   /** Hides an item by action ID. */

package/src/lib/types/plugin.ts

@@ -67,9 +67,7 @@ export type PluginSettingsValue = Record<string, unknown>;
 
 /** Describes the params shape for plugin action handling. */
 export interface PluginHandleActionParams extends RequestParams {
-  /** Stores the action id selected by the user when provided by the transport. */
-  id?: string;
-  /** Stores the action id selected by the user. */
+  /** Stores the action id selected by the user. Runtime handlers require a non-empty string. */
   action_id?: string;
   /** Stores an optional payload supplied by the triggering UI. */
   payload?: Record<string, unknown>;

package/test/runtime.test.js

@@ -4,7 +4,21 @@ const test = require("node:test");
 
 const {
   bootstrapPluginModule,
-  createPluginRuntime,
+  createRegisteredPluginRuntime,
+  resetMenuRegistry,
+} = require("../lib/runtime");
+const {
+  addMenuItem,
+  addMenuSeparator,
+  createMenu,
+  getMenu,
+  registerAction,
+  removeMenu,
+  hideMenu,
+  showMenu,
+} = require("../lib/runtime/menu");
+const {
+  createMenu: createMenuFromRoot,
 } = require("../lib/runtime");
 const {
   parseFramedMessages,
@@ -20,7 +34,7 @@ function createRuntimeHarness(options) {
       return true;
     },
   };
-  const runtime = createPluginRuntime(options);
+  const runtime = createRegisteredPluginRuntime(options);
   runtime.start({ stdin, stdout });
 
   return {
@@ -233,3 +247,308 @@ test("bootstrapPluginModule rejects when OnPluginStart throws", async () => {
     /plugin startup failed/
   );
 });
+
+test("resetMenuRegistry clears all menus and action handlers", () => {
+  createMenu("reset-test", "Reset Test", { surface: "menubar" });
+  registerAction("reset-test-action", () => "ok");
+  assert.notEqual(getMenu("reset-test"), null);
+
+  resetMenuRegistry();
+
+  assert.equal(getMenu("reset-test"), null);
+  // After reset, addMenuItem/addMenuSeparator must silently no-op for unknown menus.
+});
+
+test("addMenuItem silently ignores when menu does not exist", () => {
+  resetMenuRegistry();
+  // Must not throw.
+  addMenuItem("nonexistent-menu", {
+    label: "Irrelevant",
+    action: "test-action",
+  });
+  assert.equal(getMenu("nonexistent-menu"), null);
+});
+
+test("addMenuSeparator silently ignores when menu does not exist", () => {
+  resetMenuRegistry();
+  // Must not throw.
+  addMenuSeparator("nonexistent-menu");
+  assert.equal(getMenu("nonexistent-menu"), null);
+});
+
+test("addMenuItem and addMenuSeparator do not implicitly create menus", () => {
+  resetMenuRegistry();
+  createMenu("existing-menu", "Existing Menu", { surface: "menubar" });
+  addMenuItem("existing-menu", {
+    label: "Test Item",
+    action: "test-action",
+  });
+  addMenuSeparator("existing-menu");
+  assert.notEqual(getMenu("existing-menu"), null);
+  // Verify state was not leaked from prior tests.
+  assert.equal(getMenu("reset-test"), null);
+  removeMenu("existing-menu");
+});
+
+test("hideMenu and showMenu toggle menu visibility", () => {
+  resetMenuRegistry();
+  createMenu("visible-menu", "Visible Menu", { surface: "menubar" });
+  addMenuItem("visible-menu", {
+    label: "Test Item",
+    action: "visibility-action",
+  });
+
+  const menu = getMenu("visible-menu");
+  assert.notEqual(menu, null);
+  hideMenu("visible-menu");
+  assert.notEqual(getMenu("visible-menu"), null);
+
+  showMenu("visible-menu");
+  assert.notEqual(getMenu("visible-menu"), null);
+
+  removeMenu("visible-menu");
+});
+
+test("hideMenu and showMenu affect serialized menus", async () => {
+  resetMenuRegistry();
+  createMenu("serial-menu", "Serial Menu", { surface: "menubar" });
+  addMenuItem("serial-menu", {
+    label: "Serial Item",
+    action: "serial-action",
+  });
+
+  const harness = createRuntimeHarness({ plugin: {} });
+
+  hideMenu("serial-menu");
+  let hidden = await harness.request({
+    jsonrpc: "2.0",
+    id: 30,
+    method: "plugin.get_menus",
+    params: {},
+  });
+  assert.deepEqual(hidden, [{ jsonrpc: "2.0", id: 30, result: [] }]);
+
+  showMenu("serial-menu");
+  const visible = await harness.request({
+    jsonrpc: "2.0",
+    id: 31,
+    method: "plugin.get_menus",
+    params: {},
+  });
+  assert.deepEqual(visible, [{
+    jsonrpc: "2.0",
+    id: 31,
+    result: [{
+      id: "serial-menu",
+      label: "Serial Menu",
+      order: 1,
+      surface: "menubar",
+      elements: [{ type: "button", id: "serial-action", label: "Serial Item" }],
+    }],
+  }]);
+});
+
+test("addMenuSeparator supports afterAction positioning", async () => {
+  resetMenuRegistry();
+  createMenu("separator-menu", "Separator Menu", { surface: "menubar" });
+  addMenuItem("separator-menu", {
+    label: "First Item",
+    action: "first-action",
+  });
+  addMenuItem("separator-menu", {
+    label: "Second Item",
+    action: "second-action",
+  });
+
+  addMenuSeparator("separator-menu", undefined, "first-action");
+
+  const harness = createRuntimeHarness({ plugin: {} });
+  const messages = await harness.request({
+    jsonrpc: "2.0",
+    id: 32,
+    method: "plugin.get_menus",
+    params: {},
+  });
+
+  assert.deepEqual(messages, [{
+    jsonrpc: "2.0",
+    id: 32,
+    result: [{
+      id: "separator-menu",
+      label: "Separator Menu",
+      order: 1,
+      surface: "menubar",
+      elements: [
+        { type: "button", id: "first-action", label: "First Item" },
+        { type: "text", id: "separator-menu-separator-1", content: "—" },
+        { type: "button", id: "second-action", label: "Second Item" },
+      ],
+    }],
+  }]);
+
+  removeMenu("separator-menu");
+});
+
+test("plugin.handle_action rejects missing action_id", async () => {
+  resetMenuRegistry();
+  const harness = createRuntimeHarness({ plugin: {} });
+
+  const missing = await harness.request({
+    jsonrpc: "2.0",
+    id: 20,
+    method: "plugin.handle_action",
+    params: {},
+  });
+  assert.deepEqual(missing, [
+    {
+      jsonrpc: "2.0",
+      id: 20,
+      error: {
+        code: -32001,
+        message: "plugin.handle_action requires params.action_id to be a non-empty string",
+        data: {
+          code: "plugin-invalid-action-id",
+          message: "plugin.handle_action requires params.action_id to be a non-empty string",
+        },
+      },
+    },
+  ]);
+});
+
+test("plugin.handle_action rejects empty action_id", async () => {
+  resetMenuRegistry();
+  const harness = createRuntimeHarness({ plugin: {} });
+
+  const empty = await harness.request({
+    jsonrpc: "2.0",
+    id: 21,
+    method: "plugin.handle_action",
+    params: { action_id: "" },
+  });
+  assert.deepEqual(empty, [
+    {
+      jsonrpc: "2.0",
+      id: 21,
+      error: {
+        code: -32001,
+        message: "plugin.handle_action requires params.action_id to be a non-empty string",
+        data: {
+          code: "plugin-invalid-action-id",
+          message: "plugin.handle_action requires params.action_id to be a non-empty string",
+        },
+      },
+    },
+  ]);
+});
+
+test("createMenu is available from runtime root export", () => {
+  resetMenuRegistry();
+  const menu = createMenuFromRoot("root-export-menu", "Root Export Menu", { surface: "menubar" });
+  assert.notEqual(menu, null);
+  assert.equal(menu.id, "root-export-menu");
+
+  resetMenuRegistry();
+});
+
+test("plugin.handle_action dispatches only on action_id (not id)", async () => {
+  resetMenuRegistry();
+  // Register after reset so the handler is present.
+  registerAction("test-action-id", (payload) => {
+    if (typeof payload === "object" && payload != null) {
+      return (payload).message;
+    }
+    return null;
+  });
+
+  const harness = createRuntimeHarness({
+    plugin: {},
+  });
+
+  // Valid dispatch via action_id.
+  const valid = await harness.request({
+    jsonrpc: "2.0",
+    id: 10,
+    method: "plugin.handle_action",
+    params: { action_id: "test-action-id", payload: { message: "hello" } },
+  });
+  assert.deepEqual(valid, [
+    { jsonrpc: "2.0", id: 10, result: "hello" },
+  ]);
+
+  // `id` is ignored; only `action_id` is valid.
+  const wrongField = await harness.request({
+    jsonrpc: "2.0",
+    id: 12,
+    method: "plugin.handle_action",
+    params: { id: "test-action-id" },
+  });
+  assert.deepEqual(wrongField, [
+    {
+      jsonrpc: "2.0",
+      id: 12,
+      error: {
+        code: -32001,
+        message: "plugin.handle_action requires params.action_id to be a non-empty string",
+        data: {
+          code: "plugin-invalid-action-id",
+          message: "plugin.handle_action requires params.action_id to be a non-empty string",
+        },
+      },
+    },
+  ]);
+});
+
+test("plugin.handle_action logs unhandled actions without explicit handler", async () => {
+  resetMenuRegistry();
+  const harness = createRuntimeHarness({ plugin: {} });
+
+  const messages = await harness.request({
+    jsonrpc: "2.0",
+    id: 13,
+    method: "plugin.handle_action",
+    params: { action_id: "missing-action" },
+  });
+
+  assert.deepEqual(messages, [
+    {
+      jsonrpc: "2.0",
+      method: "host.log",
+      params: {
+        level: "info",
+        target: "openvcs.plugin",
+        message: "plugin.handle_action ignored unhandled action_id 'missing-action'",
+      },
+    },
+    { jsonrpc: "2.0", id: 13, result: null },
+  ]);
+});
+
+test("bootstrapPluginModule resets menu registry before OnPluginStart", async () => {
+  resetMenuRegistry();
+  // Pre-populate state that should be cleared.
+  createMenu("leak-test", "Leak Test", { surface: "menubar" });
+  registerAction("leak-action", () => "leaked");
+
+  const stdin = new EventEmitter();
+  const chunks = [];
+  const stdout = {
+    write(chunk) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      return true;
+    },
+  };
+
+  await bootstrapPluginModule({
+    modulePath: "./plugin.js",
+    transport: { stdin, stdout },
+    async importPluginModule() {
+      return {
+        PluginDefinition: { plugin: {} },
+        OnPluginStart() {},
+      };
+    },
+  });
+
+  // Menu from before bootstrap must not be present.
+  assert.equal(getMenu("leak-test"), null);
+});