onbuzz 4.8.2 → 4.9.0

package/src/tools/composioTool.js

@@ -0,0 +1,307 @@
+/**
+ * Composio Tool — third-party integration hub (Gmail, Slack, GitHub,
+ * Linear, Notion, Drive, Sheets, Calendar, ~250 apps).
+ *
+ * Architecture: thin wrapper around the official `@composio/core` SDK
+ * (v0.6.7+). The SDK is in optionalDependencies so the rest of the
+ * runtime works even if it's not installed — agents without the
+ * `composio` capability never see this tool.
+ *
+ * Auth model: per-user. We map agentId → Composio userId. Composio
+ * holds the OAuth tokens server-side and auto-refreshes them. Our
+ * code never sees raw tokens.
+ *
+ * API key: `process.env.COMPOSIO_API_KEY`. Required to do anything;
+ * obtain at dashboard.composio.dev.
+ *
+ * Security note: Composio had a security incident in May 2026 that
+ * leaked ~5K GitHub OAuth tokens. Key rotation should be automatable
+ * on the operator's side (env-var refresh + restart). Keep this tool
+ * GATED behind an explicit `composio` capability — never default-on.
+ *
+ * Plural-canonical envelope (cross-tool convention):
+ *   { toolId: "composio", actions: [{ type: "<op>", ...fields }] }
+ * Singular {action,...} accepted via reverse-forgiveness.
+ */
+
+import { BaseTool } from './baseTool.js';
+
+const SUPPORTED_ACTIONS = [
+  'list-toolkits',      // discover available integrations
+  'list-tools',         // for a specific toolkit, list its action slugs + schemas
+  'connect',            // generate a Connect Link URL for the user to OAuth into a toolkit
+  'connection-status',  // check whether the current user has an active connection to a toolkit
+  'execute',            // invoke a Composio action with arguments
+];
+
+class ComposioTool extends BaseTool {
+  constructor(config = {}, logger = null) {
+    super(config, logger);
+    this.id = 'composio';
+    this.requiresProject = false;
+    this.isAsync = true;
+    this.timeout = config.timeout || 60_000;
+    this._sdkClient = null;          // lazy-loaded @composio/core instance
+    this._sdkUnavailableReason = null; // populated if dynamic import fails
+  }
+
+  getDescription() {
+    return `
+Composio Tool: third-party integration hub. Connects agents to ~250 apps
+(Gmail, Slack, GitHub, Linear, Notion, Drive, Sheets, Calendar, etc.)
+via Composio's hosted OAuth and unified action API.
+
+USAGE (plural canonical — same shape as other tools):
+\`\`\`json
+{
+  "toolId": "composio",
+  "actions": [
+    {"type": "execute", "toolkitSlug": "github", "actionSlug": "GITHUB_CREATE_AN_ISSUE",
+     "arguments": {"owner": "acme", "repo": "api", "title": "Bug X", "body": "..."}}
+  ]
+}
+\`\`\`
+
+ACTIONS:
+
+1. **list-toolkits** — discover integrations the org has enabled
+\`\`\`json
+{"toolId": "composio", "actions": [{"type": "list-toolkits"}]}
+\`\`\`
+Returns: { toolkits: [{slug, name, authConfigured, ...}] }
+
+2. **list-tools** — list a toolkit's available actions + their schemas
+\`\`\`json
+{"toolId": "composio", "actions": [{"type": "list-tools", "toolkitSlug": "github"}]}
+\`\`\`
+Returns: { tools: [{slug, displayName, description, inputSchema, outputSchema}] }
+
+3. **connect** — start an OAuth connection for the current user. Returns
+a Connect Link URL the user opens to complete the flow.
+\`\`\`json
+{"toolId": "composio", "actions": [{"type": "connect", "toolkitSlug": "github"}]}
+\`\`\`
+Returns: { connectLink: "https://connect.composio.dev/link/...", connectionId }
+
+4. **connection-status** — has the current user connected this toolkit?
+\`\`\`json
+{"toolId": "composio", "actions": [{"type": "connection-status", "toolkitSlug": "github"}]}
+\`\`\`
+Returns: { connected: true|false, status: "ACTIVE"|"INITIATED"|"FAILED", connectionId? }
+
+5. **execute** — invoke a Composio action
+\`\`\`json
+{
+  "toolId": "composio",
+  "actions": [{
+    "type": "execute",
+    "toolkitSlug": "slack",
+    "actionSlug": "SLACK_SEND_MESSAGE",
+    "arguments": {"channel": "#general", "text": "hello"}
+  }]
+}
+\`\`\`
+Returns: { success: true|false, output: <upstream result>, error? }
+
+NOTES:
+- Each agent is mapped to a distinct Composio userId (agentId is reused).
+  Tokens are isolated per-agent.
+- The org-level API key is read from \`COMPOSIO_API_KEY\` env var.
+- If the env var is missing OR the SDK isn't installed, every action
+  returns a structured error so the agent can recover gracefully.
+- Composio holds OAuth tokens server-side. We never see raw tokens.
+    `.trim();
+  }
+
+  getRequiredParameters() {
+    // Validation happens per-action in customValidateParameters.
+    return [];
+  }
+
+  customValidateParameters(params) {
+    const errors = [];
+    // Plural-canonical with singular fallback (reverse-forgiveness).
+    // The forgiveness handles {action,...} → {actions:[{type,...}]}.
+    let actions = Array.isArray(params?.actions) ? params.actions : null;
+    if (!actions && params?.action) {
+      const { action, parameters, ...rest } = params;
+      actions = [{ type: action, ...(parameters && typeof parameters === 'object' ? parameters : {}), ...rest }];
+    }
+    if (!actions || actions.length === 0) {
+      errors.push('action is required (or actions: [...] for batched calls)');
+      return { valid: false, errors };
+    }
+    for (let i = 0; i < actions.length; i++) {
+      const a = actions[i];
+      const tag = actions.length > 1 ? `actions[${i}]: ` : '';
+      const t = a?.type || a?.action;
+      if (!t) {
+        errors.push(`${tag}type is required`);
+        continue;
+      }
+      if (!SUPPORTED_ACTIONS.includes(t)) {
+        errors.push(`${tag}invalid type "${t}". Must be one of: ${SUPPORTED_ACTIONS.join(', ')}`);
+        continue;
+      }
+      switch (t) {
+        case 'list-tools':
+        case 'connect':
+        case 'connection-status':
+          if (!a.toolkitSlug) errors.push(`${tag}toolkitSlug is required for ${t}`);
+          break;
+        case 'execute':
+          if (!a.toolkitSlug) errors.push(`${tag}toolkitSlug is required for execute`);
+          if (!a.actionSlug)  errors.push(`${tag}actionSlug is required for execute`);
+          break;
+      }
+    }
+    return { valid: errors.length === 0, errors };
+  }
+
+  /**
+   * Lazy SDK loader. Catches missing-dependency / missing-API-key gracefully.
+   * Returns { client } on success or { error } on failure — never throws.
+   * Override-friendly: tests can stub `_loadSdk` to inject a mock client.
+   */
+  async _loadSdk() {
+    if (this._sdkClient) return { client: this._sdkClient };
+    if (this._sdkUnavailableReason) return { error: this._sdkUnavailableReason };
+
+    const apiKey = process.env.COMPOSIO_API_KEY;
+    if (!apiKey) {
+      const error = 'COMPOSIO_API_KEY env var is not set. Obtain at https://dashboard.composio.dev and set it in the Loxia process environment.';
+      this._sdkUnavailableReason = error;
+      return { error };
+    }
+
+    let Composio;
+    try {
+      const mod = await import('@composio/core');
+      Composio = mod.Composio || mod.default?.Composio || mod.default;
+    } catch (e) {
+      const error = `@composio/core SDK is not installed. Run \`npm install @composio/core\` (optionalDependencies). Detail: ${e.message}`;
+      this._sdkUnavailableReason = error;
+      return { error };
+    }
+
+    try {
+      this._sdkClient = new Composio({ apiKey });
+      return { client: this._sdkClient };
+    } catch (e) {
+      const error = `Composio SDK initialization failed: ${e.message}`;
+      this._sdkUnavailableReason = error;
+      return { error };
+    }
+  }
+
+  async execute(params, context = {}) {
+    // Reverse-forgiveness: accept both envelopes.
+    const actions = this._normalizeToActions(params);
+    if (actions.length === 0) {
+      return { success: false, error: 'composio requires `action` (singular) or `actions` (plural array).' };
+    }
+
+    const userId = context.agentId || 'default-user';
+    const { client, error: sdkErr } = await this._loadSdk();
+    if (sdkErr) {
+      return { success: false, error: sdkErr, hint: 'Set COMPOSIO_API_KEY and `npm install @composio/core`.' };
+    }
+
+    // Single-action: return its result directly (back-compat with other
+    // tools' single-action shape). Multi-action: return batched results.
+    if (actions.length === 1) {
+      return await this._dispatch(client, userId, actions[0]);
+    }
+    const results = [];
+    for (const a of actions) {
+      try { results.push(await this._dispatch(client, userId, a)); }
+      catch (err) { results.push({ success: false, action: a.type, error: err.message }); }
+    }
+    return {
+      success: results.every(r => r.success !== false),
+      batched: true,
+      actionCount: results.length,
+      results,
+    };
+  }
+
+  /** @private */
+  _normalizeToActions(params) {
+    if (!params || typeof params !== 'object') return [];
+    if (Array.isArray(params.actions)) {
+      return params.actions.map(a => {
+        if (a && !a.type && a.action) return { type: a.action, ...a };
+        return a;
+      });
+    }
+    if (params.action) {
+      const { action, parameters, ...rest } = params;
+      return [{ type: action, ...(parameters && typeof parameters === 'object' ? parameters : {}), ...rest }];
+    }
+    return [];
+  }
+
+  /** @private */
+  async _dispatch(client, userId, action) {
+    const type = action.type || action.action;
+    try {
+      switch (type) {
+        case 'list-toolkits': {
+          const toolkits = await client.toolkits?.list?.();
+          return { success: true, action: 'list-toolkits', toolkits: toolkits || [] };
+        }
+        case 'list-tools': {
+          const tools = await client.tools?.list?.({ toolkit: action.toolkitSlug, userId });
+          return { success: true, action: 'list-tools', toolkitSlug: action.toolkitSlug, tools: tools || [] };
+        }
+        case 'connect': {
+          const result = await client.connectedAccounts?.initiate?.({
+            userId,
+            toolkit: action.toolkitSlug,
+            ...(action.authConfigId ? { authConfigId: action.authConfigId } : {}),
+          });
+          return {
+            success: true,
+            action: 'connect',
+            connectLink: result?.redirectUrl || result?.connectLink || null,
+            connectionId: result?.id || result?.connectionId || null,
+            raw: result,
+          };
+        }
+        case 'connection-status': {
+          const conn = await client.connectedAccounts?.get?.({ userId, toolkit: action.toolkitSlug });
+          const connected = !!(conn && (conn.status === 'ACTIVE' || conn.connected === true));
+          return {
+            success: true,
+            action: 'connection-status',
+            toolkitSlug: action.toolkitSlug,
+            connected,
+            status: conn?.status || 'NOT_CONNECTED',
+            connectionId: conn?.id || null,
+          };
+        }
+        case 'execute': {
+          const result = await client.tools?.execute?.(action.actionSlug, {
+            userId,
+            arguments: action.arguments || {},
+          });
+          return {
+            success: result?.successful !== false,
+            action: 'execute',
+            actionSlug: action.actionSlug,
+            toolkitSlug: action.toolkitSlug,
+            output: result?.data ?? result?.output ?? result,
+            error: result?.error || null,
+          };
+        }
+        default:
+          return { success: false, error: `Unknown composio action: ${type}` };
+      }
+    } catch (err) {
+      this.logger?.error?.('[ComposioTool] action failed', { type, userId, error: err.message });
+      return { success: false, action: type, error: err.message };
+    }
+  }
+}
+
+export default ComposioTool;