@slashfi/agents-sdk 0.7.0 → 0.9.0

package/src/agent-definitions/integrations.ts

@@ -18,13 +18,13 @@
  * const registry = createAgentRegistry();
  * registry.register(createIntegrationsAgent({
  *   store: myIntegrationStore,
- *   callbackBaseUrl: 'https://myapp.com/integrations/callback',
+ *   callbackBaseUrl: 'https://myapp.com/oauth/callback',
  * }));
  * ```
  */
 
 import { defineAgent, defineTool } from "../define.js";
-import { pendingCollections, generateCollectionToken } from "../server.js";
+import { pendingCollections, generateCollectionToken } from "../secret-collection.js";
 import type { AgentDefinition, ToolContext, ToolDefinition } from "../types.js";
 
 // ============================================
@@ -99,7 +99,11 @@ export interface IntegrationApiConfig {
 export interface ProviderConfig {
   id: string;
   name: string;
-  type: "rest" | "graphql" | "agent-registry";
+  /**
+   * Agent path that handles this integration type.
+   * @integrations dispatches setup/connect/call to that agent's integrationMethods.
+   */
+  agentPath: string;
   /**
    * Scope of the integration:
    * - 'user': per-user tokens (Slack, Notion, Linear)
@@ -108,7 +112,7 @@ export interface ProviderConfig {
   scope?: "user" | "tenant";
   docs?: { llmsTxt?: string; human?: string[] };
   auth?: IntegrationOAuthConfig;
-  api: IntegrationApiConfig;
+  api?: IntegrationApiConfig;
 }
 
 // ============================================
@@ -131,18 +135,9 @@ export interface GraphqlCallInput {
   variables?: Record<string, unknown>;
 }
 
-export interface AgentRegistryCallInput {
-  provider: string;
-  type: "agent-registry";
-  agent: string;
-  tool: string;
-  params?: Record<string, unknown>;
-}
-
 export type IntegrationCallInput =
   | RestCallInput
-  | GraphqlCallInput
-  | AgentRegistryCallInput;
+  | GraphqlCallInput;
 
 // ============================================
 // User Connection (stored token)
@@ -273,6 +268,7 @@ function buildAuthHeaders(
   config: ProviderConfig,
   accessToken: string,
 ): Record<string, string> {
+  if (!config.api) return {};
   const { auth } = config.api;
   const headerName = auth.headerName ?? "Authorization";
   const prefix = auth.prefix ?? "Bearer";
@@ -433,7 +429,7 @@ async function executeRestCall(
   input: RestCallInput,
   accessToken: string,
 ): Promise<unknown> {
-  const url = new URL(input.path, config.api.baseUrl);
+  const url = new URL(input.path, config.api?.baseUrl);
   if (input.query) {
     for (const [k, v] of Object.entries(input.query)) {
       url.searchParams.set(k, v);
@@ -442,7 +438,7 @@ async function executeRestCall(
 
   const headers: Record<string, string> = {
     ...buildAuthHeaders(config, accessToken),
-    ...(config.api.defaultHeaders ?? {}),
+    ...(config.api?.defaultHeaders ?? {}),
   };
 
   if (input.body) {
@@ -471,9 +467,10 @@ async function executeGraphqlCall(
   const headers: Record<string, string> = {
     "Content-Type": "application/json",
     ...buildAuthHeaders(config, accessToken),
-    ...(config.api.defaultHeaders ?? {}),
+    ...(config.api?.defaultHeaders ?? {}),
   };
 
+  if (!config.api?.baseUrl) throw new Error("No baseUrl configured for this provider");
   const response = await fetch(config.api.baseUrl, {
     method: "POST",
     headers,
@@ -491,6 +488,23 @@ export interface IntegrationsAgentOptions {
   /** Integration store backend */
   store: IntegrationStore;
 
+  /**
+   * Callback to list all registered agents.
+   * Used by list_integrations to discover agents with integrationMethods.
+   * Typically wired to registry.list().
+   */
+  getAgents?: () => AgentDefinition[];
+
+  /** Registry instance for calling other agents' internal tools */
+  registry?: {
+    call(request: any): Promise<any>;
+  };
+
+  /** Integrations store for tracking installed integrations */
+  integrationsStore?: {
+    create(input: { agentPath: string; config: Record<string, unknown>; installedBy?: string; tenantId?: string }): Promise<any>;
+  };
+
   /** Secret store for storing/resolving client credentials and tokens */
   secretStore: {
     store(value: string, ownerId: string): Promise<string>;
@@ -500,7 +514,7 @@ export interface IntegrationsAgentOptions {
 
   /**
    * Base URL for OAuth callbacks.
-   * The callback URL will be: `${callbackBaseUrl}/${providerId}`
+   * The OAuth redirect_uri. Provider is encoded in the state param.
    */
   callbackBaseUrl?: string;
 }
@@ -521,7 +535,7 @@ const SYSTEM_OWNER = "__integrations__";
 export function createIntegrationsAgent(
   options: IntegrationsAgentOptions,
 ): AgentDefinition {
-  const { store, callbackBaseUrl, secretStore } = options;
+  const { store, callbackBaseUrl, secretStore, getAgents, integrationsStore } = options;
 
   // ---- setup_integration ----
   const setupTool = defineTool({
@@ -539,10 +553,9 @@ export function createIntegrationsAgent(
           description: "Provider ID (e.g. 'linear', 'notion')",
         },
         name: { type: "string", description: "Display name" },
-        type: {
+        agentPath: {
           type: "string",
-          enum: ["rest", "graphql", "agent-registry"],
-          description: "Integration type",
+          description: "Agent path that handles this integration (e.g. '@remote-registry', '@databases'). Omit for simple REST/GraphQL integrations.",
         },
         scope: {
           type: "string",
@@ -647,7 +660,7 @@ export function createIntegrationsAgent(
       const config: ProviderConfig = {
         id: input.id,
         name: input.name,
-        type: input.type,
+        agentPath: input.agentPath,
         scope: input.scope,
         docs: input.docs,
         auth: input.auth,
@@ -667,11 +680,121 @@ export function createIntegrationsAgent(
       }
 
       await store.upsertProvider(config);
+
+      // Also track in integrations table
+      if (integrationsStore) {
+        try {
+          await integrationsStore.create({
+            agentPath: config.agentPath ?? `@${config.id}`,
+            config: { providerId: config.id, ...input },
+            installedBy: _ctx.callerId,
+          });
+        } catch {}
+      }
+
       result.provider = config;
       return result;
     },
   });
 
+
+  // ---- discover_integrations ----
+  const discoverTool = defineTool({
+    name: "discover_integrations",
+    description:
+      "Discover available integration types that can be set up. " +
+      "Returns a catalog of integrations with their setup/connect schemas " +
+      "so you know what parameters to pass to setup_integration.",
+    visibility: "public" as const,
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        query: {
+          type: "string",
+          description: "Search query to filter integrations by name or description",
+        },
+        category: {
+          type: "string",
+          description: "Filter by category (e.g. 'infrastructure', 'communication')",
+        },
+      },
+    },
+    execute: async (
+      input: { query?: string; category?: string },
+      _ctx: ToolContext,
+    ) => {
+      const catalog: Array<{
+        provider: string;
+        agentPath?: string;
+        displayName: string;
+        icon?: string;
+        category?: string;
+        description?: string;
+        setupSchema?: Record<string, unknown>;
+        connectSchema?: Record<string, unknown>;
+        hasOAuth?: boolean;
+      }> = [];
+
+      // 1. Agent-backed integrations
+      if (getAgents) {
+        for (const agent of getAgents()) {
+          if (agent.config?.integration) {
+            const ic = agent.config.integration;
+            catalog.push({
+              provider: ic.provider,
+              agentPath: agent.path,
+              displayName: ic.displayName,
+              icon: ic.icon,
+              category: ic.category,
+              description: ic.description,
+              setupSchema: ic.setupSchema,
+              connectSchema: ic.connectSchema,
+            });
+          }
+        }
+      }
+
+      // 2. DB-stored providers (legacy OAuth)
+      const providers = await store.listProviders();
+      for (const p of providers) {
+        // Skip if already in catalog from agent scan
+        if (catalog.some((c) => c.provider === p.id)) continue;
+        catalog.push({
+          provider: p.id,
+          displayName: p.name,
+          agentPath: p.agentPath,
+          hasOAuth: !!p.auth,
+          connectSchema: p.auth
+            ? {
+                type: "object",
+                description: "OAuth flow — use connect_integration to start",
+                properties: {
+                  provider: { type: "string", const: p.id },
+                },
+              }
+            : undefined,
+        });
+      }
+
+      // 3. Filter
+      let results = catalog;
+      if (input.query) {
+        const q = input.query.toLowerCase();
+        results = results.filter(
+          (r) =>
+            r.provider.toLowerCase().includes(q) ||
+            r.displayName.toLowerCase().includes(q) ||
+            (r.description?.toLowerCase().includes(q) ?? false),
+        );
+      }
+      if (input.category) {
+        results = results.filter((r) => r.category === input.category);
+      }
+
+      return { integrations: results };
+    },
+  });
+
   // ---- list_integrations ----
   const listTool = defineTool({
     name: "list_integrations",
@@ -692,15 +815,64 @@ export function createIntegrationsAgent(
       const userId = input.userId ?? ctx.callerId;
       const connections = userId ? await store.listConnections(userId) : [];
 
-      return {
-        providers: providers.map((p) => ({
+      // Build unified integrations list
+      const integrations: Array<Record<string, unknown>> = [];
+
+      // 1. DB-stored providers (legacy OAuth integrations)
+      for (const p of providers) {
+        integrations.push({
           id: p.id,
           name: p.name,
-          type: p.type,
+          provider: p.id,
+          agentPath: p.agentPath,
           scope: p.scope ?? "user",
           hasOAuth: !!p.auth,
           connected: connections.some((c) => c.providerId === p.id),
-        })),
+        });
+      }
+
+      // 2. Agent-backed integrations (agents with config.integration + integrationMethods)
+      if (getAgents) {
+        const agents = getAgents();
+        for (const agent of agents) {
+          if (agent.integrationMethods?.list && agent.config?.integration) {
+            const meta = {
+              provider: agent.config.integration.provider,
+              agentPath: agent.path,
+              displayName: agent.config.integration.displayName,
+              icon: agent.config.integration.icon,
+              category: agent.config.integration.category,
+              description: agent.config.integration.description,
+            };
+            try {
+              const result = await agent.integrationMethods.list({}, { ...ctx, provider: agent.config.integration.provider });
+              if (result.success && result.data) {
+                // Flatten: if data has an array field, each item becomes an integration
+                const items = Array.isArray(result.data)
+                  ? result.data
+                  : Object.values(result.data as Record<string, unknown>).find(Array.isArray) as unknown[] ?? [];
+                for (const item of items) {
+                  integrations.push({
+                    ...meta,
+                    ...(typeof item === "object" && item !== null ? item as Record<string, unknown> : { value: item }),
+                  });
+                }
+                // If no items found but agent exists, include it as a provider entry
+                if (items.length === 0) {
+                  integrations.push({ ...meta, id: meta.provider });
+                }
+              } else {
+                integrations.push({ ...meta, id: meta.provider });
+              }
+            } catch {
+              integrations.push({ ...meta, id: meta.provider });
+            }
+          }
+        }
+      }
+
+      return {
+        integrations,
         connections: connections.map((c) => ({
           providerId: c.providerId,
           connectedAt: c.connectedAt,
@@ -763,7 +935,7 @@ export function createIntegrationsAgent(
         return { error: "No callbackBaseUrl configured for OAuth flows" };
 
       const oauth = config.auth;
-      const redirectUri = `${callbackBaseUrl}/${config.id}`;
+      const redirectUri = callbackBaseUrl;
       const userId = input.userId ?? ctx.callerId;
 
       // Resolve client ID from secret store
@@ -806,7 +978,7 @@ export function createIntegrationsAgent(
         redirect_uri: redirectUri,
         response_type: "code",
         ...(scopeStr ? { scope: scopeStr } : {}),
-        state: input.state ?? JSON.stringify({ userId, providerId: config.id, redirectUrl: input.redirectUrl ?? "/" }),
+        state: input.state ?? btoa(JSON.stringify({ userId, providerId: config.id, redirectUrl: input.redirectUrl ?? "/" })),
         ...(oauth.authUrlExtraParams ?? {}),
       });
 
@@ -831,8 +1003,8 @@ export function createIntegrationsAgent(
         provider: { type: "string", description: "Provider ID" },
         type: {
           type: "string",
-          enum: ["rest", "graphql", "agent-registry"],
-          description: "Call type",
+          enum: ["rest", "graphql"],
+          description: "Call type (rest or graphql)",
         },
         // REST fields
         method: {
@@ -924,7 +1096,7 @@ export function createIntegrationsAgent(
         }
       }
 
-      // Execute the call
+      // Execute the call based on type
       switch (input.type) {
         case "rest":
           return executeRestCall(
@@ -952,27 +1124,8 @@ export function createIntegrationsAgent(
             accessToken,
           );
 
-        case "agent-registry": {
-          // For agent-registry, forward the call to the remote agent server
-          const baseUrl = config.api.baseUrl;
-          const response = await fetch(`${baseUrl}/call`, {
-            method: "POST",
-            headers: {
-              "Content-Type": "application/json",
-              ...buildAuthHeaders(config, accessToken),
-            },
-            body: JSON.stringify({
-              action: "execute_tool",
-              path: input.agent,
-              tool: input.tool,
-              params: input.params ?? {},
-            }),
-          });
-          return response.json();
-        }
-
         default:
-          return { error: `Unknown integration type: ${input.type}` };
+          return { error: `Unknown call type: ${input.type}. Use 'rest' or 'graphql'.` };
       }
     },
   });
@@ -1013,7 +1166,7 @@ export function createIntegrationsAgent(
       let userId = ctx.callerId;
       if (input.state) {
         try {
-          const parsed = JSON.parse(input.state);
+          const parsed = JSON.parse(atob(input.state));
           if (parsed.userId) userId = parsed.userId;
         } catch {}
       }
@@ -1030,7 +1183,7 @@ export function createIntegrationsAgent(
         return { error: "Failed to resolve client credentials." };
       }
 
-      const redirectUri = `${callbackBaseUrl}/${config.id}`;
+      const redirectUri = callbackBaseUrl;
       const result = await exchangeCodeForToken(
         config,
         input.code,
@@ -1059,6 +1212,7 @@ export function createIntegrationsAgent(
         provider: config.id,
         userId,
         connectedAt: connection.connectedAt,
+        accessToken: result.accessToken,
       };
     },
   });
@@ -1175,7 +1329,7 @@ export function createIntegrationsAgent(
       });
 
       // Build callback URL from callbackBaseUrl
-      const baseUrl = callbackBaseUrl?.replace(/\/integrations\/callback$/, "") ?? "";
+      const baseUrl = callbackBaseUrl?.replace(/\/oauth\/callback$/, "").replace(/\/integrations\/callback$/, "") ?? "";
 
       return {
         url: `${baseUrl}/secrets/form/${token}`,
@@ -1185,6 +1339,81 @@ export function createIntegrationsAgent(
     },
   });
 
+
+  // ---- Facade: discover_integrations (aggregates from all agents) ----
+  const discoverFacadeTool = defineTool({
+    name: "discover_integrations",
+    description: "Discover all available integrations across all registered agents.",
+    visibility: "public" as const,
+    inputSchema: { type: "object" as const, properties: {} },
+    execute: async () => {
+      const agents = getAgents?.() ?? [];
+      const results: any[] = [];
+      if (options.registry) {
+        for (const agent of agents) {
+          const hasDiscoverTool = agent.tools?.some((t: any) => t.name === 'discover_integrations');
+          if (hasDiscoverTool) {
+            try {
+              const res = await options.registry.call({
+                action: 'execute_tool',
+                path: agent.path,
+                tool: 'discover_integrations',
+                params: {},
+                callerId: '@integrations',
+                callerType: 'system',
+              });
+              if (res?.result && Array.isArray(res.result)) {
+                results.push(...res.result);
+              }
+            } catch {}
+          }
+        }
+      }
+      return results;
+    },
+  });
+
+  // ---- Facade: list_integrations (aggregates from all agents) ----
+  const listFacadeTool = defineTool({
+    name: "list_integrations",
+    description: "List all installed integrations across all agents.",
+    visibility: "public" as const,
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        agent_path: { type: "string", description: "Filter by agent path" },
+      },
+    },
+    execute: async (input: { agent_path?: string }) => {
+      const agents = getAgents?.() ?? [];
+      const results: any[] = [];
+      if (options.registry) {
+        const targetAgents = input.agent_path
+          ? agents.filter((a: any) => a.path === input.agent_path)
+          : agents;
+        for (const agent of targetAgents) {
+          const hasListTool = agent.tools?.some((t: any) => t.name === 'list_integrations');
+          if (hasListTool) {
+            try {
+              const res = await options.registry.call({
+                action: 'execute_tool',
+                path: agent.path,
+                tool: 'list_integrations',
+                params: {},
+                callerId: '@integrations',
+                callerType: 'system',
+              });
+              if (res?.result && Array.isArray(res.result)) {
+                results.push(...res.result);
+              }
+            } catch {}
+          }
+        }
+      }
+      return results;
+    },
+  });
+
   return defineAgent({
     path: "@integrations",
     entrypoint:
@@ -1198,12 +1427,15 @@ export function createIntegrationsAgent(
     visibility: "public",
     tools: [
       setupTool,
+      discoverTool,
       listTool,
       getTool,
       connectTool,
       callTool,
       callbackTool,
       collectSecretsTool,
+      discoverFacadeTool,
+      listFacadeTool,
     ] as ToolDefinition[],
   });
 }