corporateai 0.0.1

package/server/src/services/plugin-tool-registry.ts

@@ -0,0 +1,450 @@
+/**
+ * PluginToolRegistry — host-side registry for plugin-contributed agent tools.
+ *
+ * Responsibilities:
+ * - Store tool declarations (from plugin manifests) alongside routing metadata
+ *   so the host can resolve namespaced tool names to the owning plugin worker.
+ * - Namespace tools automatically: a tool `"search-issues"` from plugin
+ *   `"acme.linear"` is exposed to agents as `"acme.linear:search-issues"`.
+ * - Route `executeTool` calls to the correct plugin worker via the
+ *   `PluginWorkerManager`.
+ * - Provide tool discovery queries so agents can list available tools.
+ * - Clean up tool registrations when a plugin is unloaded or its worker stops.
+ *
+ * The registry is an in-memory structure — tool declarations are derived from
+ * the plugin manifest at load time and do not need persistence. When a plugin
+ * worker restarts, the host re-registers its manifest tools.
+ *
+ * @see PLUGIN_SPEC.md §11 — Agent Tools
+ * @see PLUGIN_SPEC.md §13.10 — `executeTool`
+ */
+
+import type {
+  PaperclipPluginManifestV1,
+  PluginToolDeclaration,
+} from "@corporateai/shared";
+import type { ToolRunContext, ToolResult, ExecuteToolParams } from "@corporateai/plugin-sdk";
+import type { PluginWorkerManager } from "./plugin-worker-manager.js";
+import { logger } from "../middleware/logger.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Separator between plugin ID and tool name in the namespaced tool identifier.
+ *
+ * Example: `"acme.linear:search-issues"`
+ */
+export const TOOL_NAMESPACE_SEPARATOR = ":";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A registered tool entry stored in the registry.
+ *
+ * Combines the manifest-level declaration with routing metadata so the host
+ * can resolve a namespaced tool name → plugin worker in O(1).
+ */
+export interface RegisteredTool {
+  /** The plugin key used for namespacing (e.g. `"acme.linear"`). */
+  pluginId: string;
+  /**
+   * The plugin's database UUID, used for worker routing and availability
+   * checks. Falls back to `pluginId` when not provided (e.g. in tests
+   * where `id === pluginKey`).
+   */
+  pluginDbId: string;
+  /** The tool's bare name (without namespace prefix). */
+  name: string;
+  /** Fully namespaced identifier: `"<pluginId>:<toolName>"`. */
+  namespacedName: string;
+  /** Human-readable display name. */
+  displayName: string;
+  /** Description provided to the agent so it knows when to use this tool. */
+  description: string;
+  /** JSON Schema describing the tool's input parameters. */
+  parametersSchema: Record<string, unknown>;
+}
+
+/**
+ * Filter criteria for listing available tools.
+ */
+export interface ToolListFilter {
+  /** Only return tools owned by this plugin. */
+  pluginId?: string;
+}
+
+/**
+ * Result of executing a tool, extending `ToolResult` with routing metadata.
+ */
+export interface ToolExecutionResult {
+  /** The plugin that handled the tool call. */
+  pluginId: string;
+  /** The bare tool name that was executed. */
+  toolName: string;
+  /** The result returned by the plugin's tool handler. */
+  result: ToolResult;
+}
+
+// ---------------------------------------------------------------------------
+// PluginToolRegistry interface
+// ---------------------------------------------------------------------------
+
+/**
+ * The host-side tool registry — held by the host process.
+ *
+ * Created once at server startup and shared across the application. Plugins
+ * register their tools when their worker starts, and unregister when the
+ * worker stops or the plugin is uninstalled.
+ */
+export interface PluginToolRegistry {
+  /**
+   * Register all tools declared in a plugin's manifest.
+   *
+   * Called when a plugin worker starts and its manifest is loaded. Any
+   * previously registered tools for the same plugin are replaced (idempotent).
+   *
+   * @param pluginId - The plugin's unique identifier (e.g. `"acme.linear"`)
+   * @param manifest - The plugin manifest containing the `tools` array
+   * @param pluginDbId - The plugin's database UUID, used for worker routing
+   *   and availability checks. If omitted, `pluginId` is used (backwards-compat).
+   */
+  registerPlugin(pluginId: string, manifest: PaperclipPluginManifestV1, pluginDbId?: string): void;
+
+  /**
+   * Remove all tool registrations for a plugin.
+   *
+   * Called when a plugin worker stops, crashes, or is uninstalled.
+   *
+   * @param pluginId - The plugin to clear
+   */
+  unregisterPlugin(pluginId: string): void;
+
+  /**
+   * Look up a registered tool by its namespaced name.
+   *
+   * @param namespacedName - Fully qualified name, e.g. `"acme.linear:search-issues"`
+   * @returns The registered tool entry, or `null` if not found
+   */
+  getTool(namespacedName: string): RegisteredTool | null;
+
+  /**
+   * Look up a registered tool by plugin ID and bare tool name.
+   *
+   * @param pluginId - The owning plugin
+   * @param toolName - The bare tool name (without namespace prefix)
+   * @returns The registered tool entry, or `null` if not found
+   */
+  getToolByPlugin(pluginId: string, toolName: string): RegisteredTool | null;
+
+  /**
+   * List all registered tools, optionally filtered.
+   *
+   * @param filter - Optional filter criteria
+   * @returns Array of registered tool entries
+   */
+  listTools(filter?: ToolListFilter): RegisteredTool[];
+
+  /**
+   * Parse a namespaced tool name into plugin ID and bare tool name.
+   *
+   * @param namespacedName - e.g. `"acme.linear:search-issues"`
+   * @returns `{ pluginId, toolName }` or `null` if the format is invalid
+   */
+  parseNamespacedName(namespacedName: string): { pluginId: string; toolName: string } | null;
+
+  /**
+   * Build a namespaced tool name from a plugin ID and bare tool name.
+   *
+   * @param pluginId - e.g. `"acme.linear"`
+   * @param toolName - e.g. `"search-issues"`
+   * @returns The namespaced name, e.g. `"acme.linear:search-issues"`
+   */
+  buildNamespacedName(pluginId: string, toolName: string): string;
+
+  /**
+   * Execute a tool by its namespaced name, routing to the correct plugin worker.
+   *
+   * Resolves the namespaced name to the owning plugin, validates the tool
+   * exists, and dispatches the `executeTool` RPC call to the worker.
+   *
+   * @param namespacedName - Fully qualified tool name (e.g. `"acme.linear:search-issues"`)
+   * @param parameters - The parsed parameters matching the tool's schema
+   * @param runContext - Agent run context
+   * @returns The execution result with routing metadata
+   * @throws {Error} if the tool is not found or the worker is not running
+   */
+  executeTool(
+    namespacedName: string,
+    parameters: unknown,
+    runContext: ToolRunContext,
+  ): Promise<ToolExecutionResult>;
+
+  /**
+   * Get the number of registered tools, optionally scoped to a plugin.
+   *
+   * @param pluginId - If provided, count only this plugin's tools
+   */
+  toolCount(pluginId?: string): number;
+}
+
+// ---------------------------------------------------------------------------
+// Factory: createPluginToolRegistry
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new `PluginToolRegistry`.
+ *
+ * The registry is backed by two in-memory maps:
+ * - `byNamespace`: namespaced name → `RegisteredTool` for O(1) lookups.
+ * - `byPlugin`: pluginId → Set of namespaced names for efficient per-plugin ops.
+ *
+ * @param workerManager - The worker manager used to dispatch `executeTool` RPC
+ *   calls to plugin workers. If not provided, `executeTool` will throw.
+ *
+ * @example
+ * ```ts
+ * const toolRegistry = createPluginToolRegistry(workerManager);
+ *
+ * // Register tools from a plugin manifest
+ * toolRegistry.registerPlugin("acme.linear", linearManifest);
+ *
+ * // List all available tools for agents
+ * const tools = toolRegistry.listTools();
+ * // → [{ namespacedName: "acme.linear:search-issues", ... }]
+ *
+ * // Execute a tool
+ * const result = await toolRegistry.executeTool(
+ *   "acme.linear:search-issues",
+ *   { query: "auth bug" },
+ *   { agentId: "agent-1", runId: "run-1", companyId: "co-1", projectId: "proj-1" },
+ * );
+ * ```
+ */
+export function createPluginToolRegistry(
+  workerManager?: PluginWorkerManager,
+): PluginToolRegistry {
+  const log = logger.child({ service: "plugin-tool-registry" });
+
+  // Primary index: namespaced name → tool entry
+  const byNamespace = new Map<string, RegisteredTool>();
+
+  // Secondary index: pluginId → set of namespaced names (for bulk operations)
+  const byPlugin = new Map<string, Set<string>>();
+
+  // -----------------------------------------------------------------------
+  // Internal helpers
+  // -----------------------------------------------------------------------
+
+  function buildName(pluginId: string, toolName: string): string {
+    return `${pluginId}${TOOL_NAMESPACE_SEPARATOR}${toolName}`;
+  }
+
+  function parseName(namespacedName: string): { pluginId: string; toolName: string } | null {
+    const sepIndex = namespacedName.lastIndexOf(TOOL_NAMESPACE_SEPARATOR);
+    if (sepIndex <= 0 || sepIndex >= namespacedName.length - 1) {
+      return null;
+    }
+    return {
+      pluginId: namespacedName.slice(0, sepIndex),
+      toolName: namespacedName.slice(sepIndex + 1),
+    };
+  }
+
+  function addTool(pluginId: string, decl: PluginToolDeclaration, pluginDbId: string): void {
+    const namespacedName = buildName(pluginId, decl.name);
+
+    const entry: RegisteredTool = {
+      pluginId,
+      pluginDbId,
+      name: decl.name,
+      namespacedName,
+      displayName: decl.displayName,
+      description: decl.description,
+      parametersSchema: decl.parametersSchema,
+    };
+
+    byNamespace.set(namespacedName, entry);
+
+    let pluginTools = byPlugin.get(pluginId);
+    if (!pluginTools) {
+      pluginTools = new Set();
+      byPlugin.set(pluginId, pluginTools);
+    }
+    pluginTools.add(namespacedName);
+  }
+
+  function removePluginTools(pluginId: string): number {
+    const pluginTools = byPlugin.get(pluginId);
+    if (!pluginTools) return 0;
+
+    const count = pluginTools.size;
+    for (const name of pluginTools) {
+      byNamespace.delete(name);
+    }
+    byPlugin.delete(pluginId);
+
+    return count;
+  }
+
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+
+  return {
+    registerPlugin(pluginId: string, manifest: PaperclipPluginManifestV1, pluginDbId?: string): void {
+      const dbId = pluginDbId ?? pluginId;
+
+      // Remove any previously registered tools for this plugin (idempotent)
+      const previousCount = removePluginTools(pluginId);
+      if (previousCount > 0) {
+        log.debug(
+          { pluginId, previousCount },
+          "cleared previous tool registrations before re-registering",
+        );
+      }
+
+      const tools = manifest.tools ?? [];
+      if (tools.length === 0) {
+        log.debug({ pluginId }, "plugin declares no tools");
+        return;
+      }
+
+      for (const decl of tools) {
+        addTool(pluginId, decl, dbId);
+      }
+
+      log.info(
+        {
+          pluginId,
+          toolCount: tools.length,
+          tools: tools.map((t) => buildName(pluginId, t.name)),
+        },
+        `registered ${tools.length} tool(s) for plugin`,
+      );
+    },
+
+    unregisterPlugin(pluginId: string): void {
+      const removed = removePluginTools(pluginId);
+      if (removed > 0) {
+        log.info(
+          { pluginId, removedCount: removed },
+          `unregistered ${removed} tool(s) for plugin`,
+        );
+      }
+    },
+
+    getTool(namespacedName: string): RegisteredTool | null {
+      return byNamespace.get(namespacedName) ?? null;
+    },
+
+    getToolByPlugin(pluginId: string, toolName: string): RegisteredTool | null {
+      const namespacedName = buildName(pluginId, toolName);
+      return byNamespace.get(namespacedName) ?? null;
+    },
+
+    listTools(filter?: ToolListFilter): RegisteredTool[] {
+      if (filter?.pluginId) {
+        const pluginTools = byPlugin.get(filter.pluginId);
+        if (!pluginTools) return [];
+        const result: RegisteredTool[] = [];
+        for (const name of pluginTools) {
+          const tool = byNamespace.get(name);
+          if (tool) result.push(tool);
+        }
+        return result;
+      }
+
+      return Array.from(byNamespace.values());
+    },
+
+    parseNamespacedName(namespacedName: string): { pluginId: string; toolName: string } | null {
+      return parseName(namespacedName);
+    },
+
+    buildNamespacedName(pluginId: string, toolName: string): string {
+      return buildName(pluginId, toolName);
+    },
+
+    async executeTool(
+      namespacedName: string,
+      parameters: unknown,
+      runContext: ToolRunContext,
+    ): Promise<ToolExecutionResult> {
+      // 1. Resolve the namespaced name
+      const parsed = parseName(namespacedName);
+      if (!parsed) {
+        throw new Error(
+          `Invalid tool name "${namespacedName}". Expected format: "<pluginId>${TOOL_NAMESPACE_SEPARATOR}<toolName>"`,
+        );
+      }
+
+      const { pluginId, toolName } = parsed;
+
+      // 2. Verify the tool is registered
+      const tool = byNamespace.get(namespacedName);
+      if (!tool) {
+        throw new Error(
+          `Tool "${namespacedName}" is not registered. ` +
+          `The plugin may not be installed or its worker may not be running.`,
+        );
+      }
+
+      // 3. Verify the worker manager is available
+      if (!workerManager) {
+        throw new Error(
+          `Cannot execute tool "${namespacedName}" — no worker manager configured. ` +
+          `Tool execution requires a PluginWorkerManager.`,
+        );
+      }
+
+      // 4. Verify the plugin worker is running (use DB UUID for worker lookup)
+      const dbId = tool.pluginDbId;
+      if (!workerManager.isRunning(dbId)) {
+        throw new Error(
+          `Cannot execute tool "${namespacedName}" — ` +
+          `worker for plugin "${pluginId}" is not running.`,
+        );
+      }
+
+      // 5. Dispatch the executeTool RPC call to the worker
+      log.debug(
+        { pluginId, pluginDbId: dbId, toolName, namespacedName, agentId: runContext.agentId, runId: runContext.runId },
+        "executing tool via plugin worker",
+      );
+
+      const rpcParams: ExecuteToolParams = {
+        toolName,
+        parameters,
+        runContext,
+      };
+
+      const result = await workerManager.call(dbId, "executeTool", rpcParams);
+
+      log.debug(
+        {
+          pluginId,
+          toolName,
+          namespacedName,
+          hasContent: !!result.content,
+          hasData: result.data !== undefined,
+          hasError: !!result.error,
+        },
+        "tool execution completed",
+      );
+
+      return { pluginId, toolName, result };
+    },
+
+    toolCount(pluginId?: string): number {
+      if (pluginId !== undefined) {
+        return byPlugin.get(pluginId)?.size ?? 0;
+      }
+      return byNamespace.size;
+    },
+  };
+}
+