@openvcs/sdk 0.2.10 → 0.2.11

package/lib/runtime/menu.d.ts

@@ -1,8 +1,12 @@
 import type { MenubarItem } from '../types/menubar.js';
+import type { PluginDelegates } from '../types/plugin.js';
+import type { PluginRuntimeContext } from './contracts.js';
 type MenubarMenuOptions = {
     before?: string;
     after?: string;
 };
+/** Runs one registered action handler by id. */
+export declare function runRegisteredAction(actionId: string, ...args: unknown[]): Promise<boolean>;
 export interface MenuHandle {
     id: string;
     addItem(item: MenubarItem): void;
@@ -11,15 +15,28 @@ export interface MenuHandle {
     hideItem(actionId: string): void;
     showItem(actionId: string): void;
 }
+/** 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 when necessary. */
 export declare function getOrCreateMenu(menuId: string, label: string): MenuHandle | null;
+/** Creates a menu at a specific insertion point. */
 export declare function createMenu(menuId: string, label: string, options?: MenubarMenuOptions): MenuHandle | null;
+/** Adds one action item to a menu. */
 export declare function addMenuItem(menuId: string, item: MenubarItem): void;
+/** Adds one separator item to a menu. */
 export declare function addMenuSeparator(menuId: string, beforeAction?: string): void;
+/** Removes one menu entirely. */
 export declare function removeMenu(menuId: string): void;
+/** Hides one menu from the host UI. */
 export declare function hideMenu(menuId: string): void;
+/** Shows one previously hidden menu. */
 export declare function showMenu(menuId: string): void;
+/** Registers an action handler by id. */
 export declare function registerAction(id: string, handler: (...args: unknown[]) => unknown): void;
+/** Invokes a host command when the host exposes a direct invoke helper. */
 export declare function invoke<T = unknown>(cmd: string, args?: unknown): Promise<T>;
+/** Emits a user notification when the host exposes one. */
 export declare function notify(msg: string): void;
+/** Builds the SDK plugin delegates contributed by the menu registry. */
+export declare function createMenuPluginDelegates(): PluginDelegates<PluginRuntimeContext>;
 export {};

package/lib/runtime/menu.js

@@ -2,6 +2,7 @@
 // Copyright © 2025-2026 OpenVCS Contributors
 // SPDX-License-Identifier: GPL-3.0-or-later
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRegisteredAction = runRegisteredAction;
 exports.getMenu = getMenu;
 exports.getOrCreateMenu = getOrCreateMenu;
 exports.createMenu = createMenu;
@@ -13,56 +14,298 @@ exports.showMenu = showMenu;
 exports.registerAction = registerAction;
 exports.invoke = invoke;
 exports.notify = notify;
+exports.createMenuPluginDelegates = createMenuPluginDelegates;
+const menus = new Map();
+const menuOrder = [];
+const actionHandlers = new Map();
+let nextSyntheticId = 0;
+/** Returns the OpenVCS global, when the host exposes one. */
 function getOpenVCS() {
     return globalThis.OpenVCS;
 }
-function castMenuHandle(menu) {
-    if (!menu)
-        return null;
+/** Normalizes menu ids for stable map lookups. */
+function normalizeMenuId(menuId) {
+    return String(menuId || '').trim();
+}
+/** Allocates a stable synthetic id for a generated menu item. */
+function allocateSyntheticId(prefix) {
+    nextSyntheticId += 1;
+    return `${prefix}-${nextSyntheticId}`;
+}
+/** Returns a stored menu state or null if it does not exist. */
+function getStoredMenu(menuId) {
+    return menus.get(normalizeMenuId(menuId)) || null;
+}
+/** Inserts a menu id into the ordering list. */
+function placeMenuId(menuId, options) {
+    const id = normalizeMenuId(menuId);
+    const existingIndex = menuOrder.indexOf(id);
+    if (existingIndex >= 0) {
+        menuOrder.splice(existingIndex, 1);
+    }
+    const beforeId = normalizeMenuId(options?.before || '');
+    const afterId = normalizeMenuId(options?.after || '');
+    if (afterId) {
+        const afterIndex = menuOrder.indexOf(afterId);
+        if (afterIndex >= 0) {
+            menuOrder.splice(afterIndex + 1, 0, id);
+            return;
+        }
+    }
+    if (beforeId) {
+        const beforeIndex = menuOrder.indexOf(beforeId);
+        if (beforeIndex >= 0) {
+            menuOrder.splice(beforeIndex, 0, id);
+            return;
+        }
+    }
+    menuOrder.push(id);
+}
+/** Ensures a menu record exists for the provided id. */
+function ensureStoredMenu(menuId, label, options) {
+    const id = normalizeMenuId(menuId);
+    const safeLabel = String(label || '').trim() || id;
+    let menu = menus.get(id);
+    if (!menu) {
+        menu = { id, label: safeLabel, items: [] };
+        menus.set(id, menu);
+        placeMenuId(id, options);
+        return menu;
+    }
+    menu.label = safeLabel;
+    placeMenuId(id, options);
     return menu;
 }
+/** Finds one menu item by action id. */
+function findMenuItem(menu, actionId) {
+    const id = normalizeMenuId(actionId);
+    return menu.items.find((item) => item.action === id) || null;
+}
+/** Inserts a menu item relative to before/after anchors when provided. */
+function insertMenuItem(menu, item, before, after) {
+    const beforeId = normalizeMenuId(before || '');
+    const afterId = normalizeMenuId(after || '');
+    const insertAt = (index) => {
+        const existingIndex = menu.items.findIndex((entry) => entry.id === item.id || entry.action === item.action);
+        if (existingIndex >= 0) {
+            menu.items.splice(existingIndex, 1);
+        }
+        menu.items.splice(index, 0, item);
+    };
+    if (beforeId) {
+        const beforeIndex = menu.items.findIndex((entry) => entry.action === beforeId);
+        if (beforeIndex >= 0) {
+            insertAt(beforeIndex);
+            return;
+        }
+    }
+    if (afterId) {
+        const afterIndex = menu.items.findIndex((entry) => entry.action === afterId);
+        if (afterIndex >= 0) {
+            insertAt(afterIndex + 1);
+            return;
+        }
+    }
+    insertAt(menu.items.length);
+}
+/** Converts one stored menu item into a serializable plugin payload element. */
+function serializeMenuItem(item) {
+    if (item.hidden)
+        return null;
+    if (item.kind === 'separator') {
+        return {
+            type: 'text',
+            id: item.id,
+            content: item.content || '—',
+        };
+    }
+    if (item.kind === 'text') {
+        return {
+            type: 'text',
+            id: item.id,
+            content: item.content || item.label,
+        };
+    }
+    return {
+        type: 'button',
+        id: item.action || item.id,
+        label: item.label,
+    };
+}
+/** Serializes the current menu registry for the host runtime. */
+function serializeMenus() {
+    return menuOrder
+        .map((menuId, index) => {
+        const menu = menus.get(menuId);
+        if (!menu || menu.hidden)
+            return null;
+        return {
+            id: menu.id,
+            label: menu.label,
+            order: index + 1,
+            elements: menu.items
+                .map((item) => serializeMenuItem(item))
+                .filter((item) => Boolean(item)),
+        };
+    })
+        .filter((menu) => Boolean(menu));
+}
+/** Runs one registered action handler by id. */
+async function runRegisteredAction(actionId, ...args) {
+    const id = String(actionId || '').trim();
+    if (!id)
+        return false;
+    const handler = actionHandlers.get(id);
+    if (!handler)
+        return false;
+    await handler(...args);
+    return true;
+}
+/** Creates a stable, mutation-based handle for one menu id. */
+function createMenuHandle(menuId) {
+    const id = normalizeMenuId(menuId);
+    return {
+        id,
+        addItem(item) {
+            const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
+            const label = String(item?.label || '').trim();
+            const action = String(item?.action || '').trim();
+            if (!label || !action)
+                return;
+            const entry = {
+                kind: 'button',
+                id: action,
+                label,
+                title: item.title,
+                action,
+            };
+            insertMenuItem(menu, entry, item.before, item.after);
+            const openvcs = getOpenVCS();
+            if (!openvcs?.menus)
+                return;
+            openvcs.menus.getOrCreate(menu.id, menu.label);
+            openvcs.menus.addMenuItem(menu.id, item);
+        },
+        addSeparator(beforeAction) {
+            const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
+            const entry = {
+                kind: 'separator',
+                id: allocateSyntheticId(`${menu.id}-separator`),
+                label: 'Separator',
+                content: '—',
+            };
+            insertMenuItem(menu, entry, beforeAction);
+            const openvcs = getOpenVCS();
+            if (!openvcs?.menus)
+                return;
+            openvcs.menus.getOrCreate(menu.id, menu.label);
+            openvcs.menus.addMenuSeparator(menu.id, beforeAction);
+        },
+        removeItem(actionId) {
+            const menu = getStoredMenu(this.id);
+            if (!menu)
+                return;
+            const idToRemove = normalizeMenuId(actionId);
+            menu.items = menu.items.filter((item) => item.action !== idToRemove);
+            const openvcs = getOpenVCS();
+            if (openvcs?.menus) {
+                const handle = openvcs.menus.get(this.id);
+                handle?.removeItem(idToRemove);
+            }
+        },
+        hideItem(actionId) {
+            const menu = getStoredMenu(this.id);
+            if (!menu)
+                return;
+            const item = findMenuItem(menu, actionId);
+            if (item)
+                item.hidden = true;
+            const openvcs = getOpenVCS();
+            if (!openvcs?.menus)
+                return;
+            const handle = openvcs.menus.get(this.id);
+            handle?.hideItem(actionId);
+        },
+        showItem(actionId) {
+            const menu = getStoredMenu(this.id);
+            if (!menu)
+                return;
+            const item = findMenuItem(menu, actionId);
+            if (item)
+                item.hidden = false;
+            const openvcs = getOpenVCS();
+            if (!openvcs?.menus)
+                return;
+            const handle = openvcs.menus.get(this.id);
+            handle?.showItem(actionId);
+        },
+    };
+}
+/** Returns a menu by id, or null when it does not exist. */
 function getMenu(menuId) {
-    const openvcs = getOpenVCS();
-    if (!openvcs?.menus)
+    const stored = getStoredMenu(menuId);
+    if (!stored)
         return null;
-    return castMenuHandle(openvcs.menus.get(menuId));
+    return createMenuHandle(stored.id);
 }
+/** Returns a menu by id, creating it when necessary. */
 function getOrCreateMenu(menuId, label) {
-    const openvcs = getOpenVCS();
-    if (!openvcs?.menus)
-        return null;
-    return castMenuHandle(openvcs.menus.getOrCreate(menuId, label));
+    const stored = ensureStoredMenu(menuId, label);
+    return createMenuHandle(stored.id);
 }
+/** Creates a menu at a specific insertion point. */
 function createMenu(menuId, label, options) {
-    const openvcs = getOpenVCS();
-    if (!openvcs?.menus)
-        return null;
-    return castMenuHandle(openvcs.menus.create(menuId, label, options));
+    const stored = ensureStoredMenu(menuId, label, options);
+    return createMenuHandle(stored.id);
 }
+/** Adds one action item to a menu. */
 function addMenuItem(menuId, item) {
-    const openvcs = getOpenVCS();
-    openvcs?.menus?.addMenuItem(menuId, item);
+    const menu = getStoredMenu(menuId) || ensureStoredMenu(menuId, menuId);
+    const handle = createMenuHandle(menu.id);
+    handle.addItem(item);
 }
+/** Adds one separator item to a menu. */
 function addMenuSeparator(menuId, beforeAction) {
-    const openvcs = getOpenVCS();
-    openvcs?.menus?.addMenuSeparator(menuId, beforeAction);
+    const menu = getStoredMenu(menuId) || ensureStoredMenu(menuId, menuId);
+    const handle = createMenuHandle(menu.id);
+    handle.addSeparator(beforeAction);
 }
+/** Removes one menu entirely. */
 function removeMenu(menuId) {
+    const id = normalizeMenuId(menuId);
+    menus.delete(id);
+    const index = menuOrder.indexOf(id);
+    if (index >= 0)
+        menuOrder.splice(index, 1);
     const openvcs = getOpenVCS();
-    openvcs?.menus?.remove(menuId);
+    openvcs?.menus?.remove(id);
 }
+/** Hides one menu from the host UI. */
 function hideMenu(menuId) {
+    const menu = getStoredMenu(menuId);
+    if (menu)
+        menu.hidden = true;
     const openvcs = getOpenVCS();
-    openvcs?.menus?.hide(menuId);
+    openvcs?.menus?.hide(normalizeMenuId(menuId));
 }
+/** Shows one previously hidden menu. */
 function showMenu(menuId) {
+    const menu = getStoredMenu(menuId);
+    if (menu)
+        menu.hidden = false;
     const openvcs = getOpenVCS();
-    openvcs?.menus?.show(menuId);
+    openvcs?.menus?.show(normalizeMenuId(menuId));
 }
+/** Registers an action handler by id. */
 function registerAction(id, handler) {
+    const key = String(id || '').trim();
+    if (!key)
+        return;
+    actionHandlers.set(key, handler);
     const openvcs = getOpenVCS();
-    openvcs?.registerAction(id, handler);
+    openvcs?.registerAction(key, handler);
 }
+/** Invokes a host command when the host exposes a direct invoke helper. */
 function invoke(cmd, args) {
     const openvcs = getOpenVCS();
     if (!openvcs) {
@@ -70,7 +313,23 @@ function invoke(cmd, args) {
     }
     return openvcs.invoke(cmd, args);
 }
+/** Emits a user notification when the host exposes one. */
 function notify(msg) {
     const openvcs = getOpenVCS();
     openvcs?.notify(msg);
 }
+/** Builds the SDK plugin delegates contributed by the menu registry. */
+function createMenuPluginDelegates() {
+    return {
+        async 'plugin.get_menus'() {
+            return serializeMenus();
+        },
+        async 'plugin.handle_action'(params) {
+            const actionId = String(params?.action_id || '').trim();
+            if (!actionId)
+                return null;
+            await runRegisteredAction(actionId);
+            return null;
+        },
+    };
+}

package/lib/runtime/registration.js

@@ -5,10 +5,37 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRegisteredPluginRuntime = createRegisteredPluginRuntime;
 exports.bootstrapPluginModule = bootstrapPluginModule;
 const factory_1 = require("./factory");
+const menu_1 = require("./menu");
 /** Creates a runtime from one declarative plugin module definition. */
 function createRegisteredPluginRuntime(definition = {}) {
+    const menuDelegates = (0, menu_1.createMenuPluginDelegates)();
+    const explicitPluginDelegates = definition.plugin ?? {};
+    const explicitGetMenus = explicitPluginDelegates['plugin.get_menus'];
+    const explicitHandleAction = explicitPluginDelegates['plugin.handle_action'];
     const options = {
-        plugin: definition.plugin,
+        plugin: {
+            ...explicitPluginDelegates,
+            'plugin.get_menus': async (params, ctx) => {
+                const menus = await menuDelegates['plugin.get_menus']?.(params, ctx);
+                const explicitMenus = explicitGetMenus
+                    ? await explicitGetMenus(params, ctx)
+                    : [];
+                return [
+                    ...(Array.isArray(explicitMenus) ? explicitMenus : []),
+                    ...(Array.isArray(menus) ? menus : []),
+                ];
+            },
+            'plugin.handle_action': async (params, ctx) => {
+                const actionId = String(params?.action_id || '').trim();
+                if (actionId && (await (0, menu_1.runRegisteredAction)(actionId))) {
+                    return null;
+                }
+                if (explicitHandleAction) {
+                    return explicitHandleAction(params, ctx);
+                }
+                return null;
+            },
+        },
         vcs: definition.vcs,
         implements: definition.implements,
         logTarget: definition.logTarget,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvcs/sdk",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "OpenVCS SDK CLI for plugin scaffolding and .ovcsp tar.gz packaging",
   "license": "GPL-3.0-or-later",
   "homepage": "https://openvcs.app/",

package/src/lib/runtime/menu.ts

@@ -2,9 +2,18 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import type { MenubarItem } from '../types/menubar.js';
+import type {
+  PluginDelegates,
+  PluginHandleActionParams,
+  PluginMenuDefinition,
+} from '../types/plugin.js';
+
+import type { PluginRuntimeContext } from './contracts.js';
 
 type MenubarMenuOptions = { before?: string; after?: string };
 
+type MenuEntryKind = 'button' | 'text' | 'separator';
+
 type OpenVCSGlobal = typeof globalThis & {
   OpenVCS?: {
     menus?: {
@@ -23,10 +32,206 @@ type OpenVCSGlobal = typeof globalThis & {
   };
 };
 
+interface StoredMenuItem {
+  kind: MenuEntryKind;
+  id: string;
+  label: string;
+  title?: string;
+  content?: string;
+  action?: string;
+  hidden?: boolean;
+}
+
+interface StoredMenuState {
+  id: string;
+  label: string;
+  hidden?: boolean;
+  items: StoredMenuItem[];
+}
+
+interface SerializedMenuItem {
+  type: 'button' | 'text';
+  id: string;
+  label?: string;
+  content?: string;
+}
+
+interface SerializedMenuDefinition {
+  id: string;
+  label: string;
+  order: number;
+  elements: SerializedMenuItem[];
+}
+
+const menus = new Map<string, StoredMenuState>();
+const menuOrder: string[] = [];
+const actionHandlers = new Map<string, (...args: unknown[]) => unknown>();
+let nextSyntheticId = 0;
+
+/** Returns the OpenVCS global, when the host exposes one. */
 function getOpenVCS() {
   return (globalThis as OpenVCSGlobal).OpenVCS;
 }
 
+/** Normalizes menu ids for stable map lookups. */
+function normalizeMenuId(menuId: string): string {
+  return String(menuId || '').trim();
+}
+
+/** Allocates a stable synthetic id for a generated menu item. */
+function allocateSyntheticId(prefix: string): string {
+  nextSyntheticId += 1;
+  return `${prefix}-${nextSyntheticId}`;
+}
+
+/** Returns a stored menu state or null if it does not exist. */
+function getStoredMenu(menuId: string): StoredMenuState | null {
+  return menus.get(normalizeMenuId(menuId)) || null;
+}
+
+/** Inserts a menu id into the ordering list. */
+function placeMenuId(menuId: string, options?: MenubarMenuOptions): void {
+  const id = normalizeMenuId(menuId);
+  const existingIndex = menuOrder.indexOf(id);
+  if (existingIndex >= 0) {
+    menuOrder.splice(existingIndex, 1);
+  }
+
+  const beforeId = normalizeMenuId(options?.before || '');
+  const afterId = normalizeMenuId(options?.after || '');
+
+  if (afterId) {
+    const afterIndex = menuOrder.indexOf(afterId);
+    if (afterIndex >= 0) {
+      menuOrder.splice(afterIndex + 1, 0, id);
+      return;
+    }
+  }
+
+  if (beforeId) {
+    const beforeIndex = menuOrder.indexOf(beforeId);
+    if (beforeIndex >= 0) {
+      menuOrder.splice(beforeIndex, 0, id);
+      return;
+    }
+  }
+
+  menuOrder.push(id);
+}
+
+/** Ensures a menu record exists for the provided id. */
+function ensureStoredMenu(menuId: string, label: string, options?: MenubarMenuOptions): StoredMenuState {
+  const id = normalizeMenuId(menuId);
+  const safeLabel = String(label || '').trim() || id;
+  let menu = menus.get(id);
+
+  if (!menu) {
+    menu = { id, label: safeLabel, items: [] };
+    menus.set(id, menu);
+    placeMenuId(id, options);
+    return menu;
+  }
+
+  menu.label = safeLabel;
+  placeMenuId(id, options);
+  return menu;
+}
+
+/** Finds one menu item by action id. */
+function findMenuItem(menu: StoredMenuState, actionId: string): StoredMenuItem | null {
+  const id = normalizeMenuId(actionId);
+  return menu.items.find((item) => item.action === id) || null;
+}
+
+/** Inserts a menu item relative to before/after anchors when provided. */
+function insertMenuItem(menu: StoredMenuState, item: StoredMenuItem, before?: string, after?: string): void {
+  const beforeId = normalizeMenuId(before || '');
+  const afterId = normalizeMenuId(after || '');
+
+  const insertAt = (index: number) => {
+    const existingIndex = menu.items.findIndex((entry) => entry.id === item.id || entry.action === item.action);
+    if (existingIndex >= 0) {
+      menu.items.splice(existingIndex, 1);
+    }
+    menu.items.splice(index, 0, item);
+  };
+
+  if (beforeId) {
+    const beforeIndex = menu.items.findIndex((entry) => entry.action === beforeId);
+    if (beforeIndex >= 0) {
+      insertAt(beforeIndex);
+      return;
+    }
+  }
+
+  if (afterId) {
+    const afterIndex = menu.items.findIndex((entry) => entry.action === afterId);
+    if (afterIndex >= 0) {
+      insertAt(afterIndex + 1);
+      return;
+    }
+  }
+
+  insertAt(menu.items.length);
+}
+
+/** Converts one stored menu item into a serializable plugin payload element. */
+function serializeMenuItem(item: StoredMenuItem): SerializedMenuItem | null {
+  if (item.hidden) return null;
+
+  if (item.kind === 'separator') {
+    return {
+      type: 'text',
+      id: item.id,
+      content: item.content || '—',
+    };
+  }
+
+  if (item.kind === 'text') {
+    return {
+      type: 'text',
+      id: item.id,
+      content: item.content || item.label,
+    };
+  }
+
+  return {
+    type: 'button',
+    id: item.action || item.id,
+    label: item.label,
+  };
+}
+
+/** Serializes the current menu registry for the host runtime. */
+function serializeMenus(): SerializedMenuDefinition[] {
+  return menuOrder
+    .map((menuId, index) => {
+      const menu = menus.get(menuId);
+      if (!menu || menu.hidden) return null;
+      return {
+        id: menu.id,
+        label: menu.label,
+        order: index + 1,
+        elements: menu.items
+          .map((item) => serializeMenuItem(item))
+        .filter((item): item is SerializedMenuItem => Boolean(item)),
+      };
+    })
+    .filter((menu): menu is SerializedMenuDefinition => Boolean(menu));
+}
+
+/** Runs one registered action handler by id. */
+export async function runRegisteredAction(actionId: string, ...args: unknown[]): Promise<boolean> {
+  const id = String(actionId || '').trim();
+  if (!id) return false;
+
+  const handler = actionHandlers.get(id);
+  if (!handler) return false;
+
+  await handler(...args);
+  return true;
+}
+
 export interface MenuHandle {
   id: string;
   addItem(item: MenubarItem): void;
@@ -36,59 +241,157 @@ export interface MenuHandle {
   showItem(actionId: string): void;
 }
 
-function castMenuHandle(menu: unknown): MenuHandle | null {
-  if (!menu) return null;
-  return menu as MenuHandle;
+/** Creates a stable, mutation-based handle for one menu id. */
+function createMenuHandle(menuId: string): MenuHandle {
+  const id = normalizeMenuId(menuId);
+
+  return {
+    id,
+    addItem(item: MenubarItem) {
+      const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
+      const label = String(item?.label || '').trim();
+      const action = String(item?.action || '').trim();
+      if (!label || !action) return;
+
+      const entry: StoredMenuItem = {
+        kind: 'button',
+        id: action,
+        label,
+        title: item.title,
+        action,
+      };
+      insertMenuItem(menu, entry, item.before, item.after);
+
+      const openvcs = getOpenVCS();
+      if (!openvcs?.menus) return;
+      openvcs.menus.getOrCreate(menu.id, menu.label);
+      openvcs.menus.addMenuItem(menu.id, item);
+    },
+    addSeparator(beforeAction?: string) {
+      const menu = getStoredMenu(this.id) || ensureStoredMenu(this.id, this.id);
+      const entry: StoredMenuItem = {
+        kind: 'separator',
+        id: allocateSyntheticId(`${menu.id}-separator`),
+        label: 'Separator',
+        content: '—',
+      };
+      insertMenuItem(menu, entry, beforeAction);
+
+      const openvcs = getOpenVCS();
+      if (!openvcs?.menus) return;
+      openvcs.menus.getOrCreate(menu.id, menu.label);
+      openvcs.menus.addMenuSeparator(menu.id, beforeAction);
+    },
+    removeItem(actionId: string) {
+      const menu = getStoredMenu(this.id);
+      if (!menu) return;
+      const idToRemove = normalizeMenuId(actionId);
+      menu.items = menu.items.filter((item) => item.action !== idToRemove);
+
+      const openvcs = getOpenVCS();
+      if (openvcs?.menus) {
+        const handle = openvcs.menus.get(this.id) as MenuHandle | null;
+        handle?.removeItem(idToRemove);
+      }
+    },
+    hideItem(actionId: string) {
+      const menu = getStoredMenu(this.id);
+      if (!menu) return;
+      const item = findMenuItem(menu, actionId);
+      if (item) item.hidden = true;
+
+      const openvcs = getOpenVCS();
+      if (!openvcs?.menus) return;
+      const handle = openvcs.menus.get(this.id) as MenuHandle | null;
+      handle?.hideItem(actionId);
+    },
+    showItem(actionId: string) {
+      const menu = getStoredMenu(this.id);
+      if (!menu) return;
+      const item = findMenuItem(menu, actionId);
+      if (item) item.hidden = false;
+
+      const openvcs = getOpenVCS();
+      if (!openvcs?.menus) return;
+      const handle = openvcs.menus.get(this.id) as MenuHandle | null;
+      handle?.showItem(actionId);
+    },
+  };
 }
 
+/** Returns a menu by id, or null when it does not exist. */
 export function getMenu(menuId: string): MenuHandle | null {
-  const openvcs = getOpenVCS();
-  if (!openvcs?.menus) return null;
-  return castMenuHandle(openvcs.menus.get(menuId));
+  const stored = getStoredMenu(menuId);
+  if (!stored) return null;
+  return createMenuHandle(stored.id);
 }
 
+/** Returns a menu by id, creating it when necessary. */
 export function getOrCreateMenu(menuId: string, label: string): MenuHandle | null {
-  const openvcs = getOpenVCS();
-  if (!openvcs?.menus) return null;
-  return castMenuHandle(openvcs.menus.getOrCreate(menuId, label));
+  const stored = ensureStoredMenu(menuId, label);
+  return createMenuHandle(stored.id);
 }
 
+/** Creates a menu at a specific insertion point. */
 export function createMenu(menuId: string, label: string, options?: MenubarMenuOptions): MenuHandle | null {
-  const openvcs = getOpenVCS();
-  if (!openvcs?.menus) return null;
-  return castMenuHandle(openvcs.menus.create(menuId, label, options));
+  const stored = ensureStoredMenu(menuId, label, options);
+  return createMenuHandle(stored.id);
 }
 
+/** Adds one action item to a menu. */
 export function addMenuItem(menuId: string, item: MenubarItem): void {
-  const openvcs = getOpenVCS();
-  openvcs?.menus?.addMenuItem(menuId, item);
+  const menu = getStoredMenu(menuId) || ensureStoredMenu(menuId, menuId);
+  const handle = createMenuHandle(menu.id);
+  handle.addItem(item);
 }
 
+/** Adds one separator item to a menu. */
 export function addMenuSeparator(menuId: string, beforeAction?: string): void {
-  const openvcs = getOpenVCS();
-  openvcs?.menus?.addMenuSeparator(menuId, beforeAction);
+  const menu = getStoredMenu(menuId) || ensureStoredMenu(menuId, menuId);
+  const handle = createMenuHandle(menu.id);
+  handle.addSeparator(beforeAction);
 }
 
+/** Removes one menu entirely. */
 export function removeMenu(menuId: string): void {
+  const id = normalizeMenuId(menuId);
+  menus.delete(id);
+  const index = menuOrder.indexOf(id);
+  if (index >= 0) menuOrder.splice(index, 1);
+
   const openvcs = getOpenVCS();
-  openvcs?.menus?.remove(menuId);
+  openvcs?.menus?.remove(id);
 }
 
+/** Hides one menu from the host UI. */
 export function hideMenu(menuId: string): void {
+  const menu = getStoredMenu(menuId);
+  if (menu) menu.hidden = true;
+
   const openvcs = getOpenVCS();
-  openvcs?.menus?.hide(menuId);
+  openvcs?.menus?.hide(normalizeMenuId(menuId));
 }
 
+/** Shows one previously hidden menu. */
 export function showMenu(menuId: string): void {
+  const menu = getStoredMenu(menuId);
+  if (menu) menu.hidden = false;
+
   const openvcs = getOpenVCS();
-  openvcs?.menus?.show(menuId);
+  openvcs?.menus?.show(normalizeMenuId(menuId));
 }
 
+/** Registers an action handler by id. */
 export function registerAction(id: string, handler: (...args: unknown[]) => unknown): void {
+  const key = String(id || '').trim();
+  if (!key) return;
+  actionHandlers.set(key, handler);
+
   const openvcs = getOpenVCS();
-  openvcs?.registerAction(id, handler);
+  openvcs?.registerAction(key, handler);
 }
 
+/** Invokes a host command when the host exposes a direct invoke helper. */
 export function invoke<T = unknown>(cmd: string, args?: unknown): Promise<T> {
   const openvcs = getOpenVCS();
   if (!openvcs) {
@@ -97,7 +400,23 @@ export function invoke<T = unknown>(cmd: string, args?: unknown): Promise<T> {
   return openvcs.invoke(cmd, args);
 }
 
+/** Emits a user notification when the host exposes one. */
 export function notify(msg: string): void {
   const openvcs = getOpenVCS();
   openvcs?.notify(msg);
 }
+
+/** Builds the SDK plugin delegates contributed by the menu registry. */
+export function createMenuPluginDelegates(): PluginDelegates<PluginRuntimeContext> {
+  return {
+    async 'plugin.get_menus'(): Promise<PluginMenuDefinition[]> {
+      return serializeMenus() as unknown as PluginMenuDefinition[];
+    },
+    async 'plugin.handle_action'(params: PluginHandleActionParams): Promise<null> {
+      const actionId = String(params?.action_id || '').trim();
+      if (!actionId) return null;
+      await runRegisteredAction(actionId);
+      return null;
+    },
+  };
+}

package/src/lib/runtime/registration.ts

@@ -14,6 +14,10 @@ import type {
   PluginRuntimeTransport,
 } from './contracts';
 import { createPluginRuntime } from './factory';
+import {
+  createMenuPluginDelegates,
+  runRegisteredAction,
+} from './menu';
 
 /** Describes the plugin module startup hook invoked by the generated bootstrap. */
 export type OnPluginStartHandler = () => void | Promise<void>;
@@ -56,8 +60,35 @@ export interface BootstrapPluginModuleOptions {
 export function createRegisteredPluginRuntime(
   definition: PluginModuleDefinition = {},
 ): PluginRuntime {
+  const menuDelegates = createMenuPluginDelegates();
+  const explicitPluginDelegates = definition.plugin ?? {};
+  const explicitGetMenus = explicitPluginDelegates['plugin.get_menus'];
+  const explicitHandleAction = explicitPluginDelegates['plugin.handle_action'];
+
   const options: CreatePluginRuntimeOptions = {
-    plugin: definition.plugin,
+    plugin: {
+      ...explicitPluginDelegates,
+      'plugin.get_menus': async (params, ctx) => {
+        const menus = await menuDelegates['plugin.get_menus']?.(params, ctx);
+        const explicitMenus = explicitGetMenus
+          ? await explicitGetMenus(params, ctx)
+          : [];
+        return [
+          ...(Array.isArray(explicitMenus) ? explicitMenus : []),
+          ...(Array.isArray(menus) ? menus : []),
+        ];
+      },
+      'plugin.handle_action': async (params, ctx) => {
+        const actionId = String(params?.action_id || '').trim();
+        if (actionId && (await runRegisteredAction(actionId))) {
+          return null;
+        }
+        if (explicitHandleAction) {
+          return explicitHandleAction(params, ctx);
+        }
+        return null;
+      },
+    },
     vcs: definition.vcs,
     implements: definition.implements,
     logTarget: definition.logTarget,