@slashfi/agents-sdk 0.8.0 → 0.9.0

package/src/agent-definitions/integrations.ts

@@ -24,7 +24,7 @@
  */
 
 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";
 
 // ============================================
@@ -488,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>;
@@ -518,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({
@@ -663,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",
@@ -688,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,
+          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,
@@ -1036,6 +1212,7 @@ export function createIntegrationsAgent(
         provider: config.id,
         userId,
         connectedAt: connection.connectedAt,
+        accessToken: result.accessToken,
       };
     },
   });
@@ -1162,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:
@@ -1175,12 +1427,15 @@ export function createIntegrationsAgent(
     visibility: "public",
     tools: [
       setupTool,
+      discoverTool,
       listTool,
       getTool,
       connectTool,
       callTool,
       callbackTool,
       collectSecretsTool,
+      discoverFacadeTool,
+      listFacadeTool,
     ] as ToolDefinition[],
   });
 }

package/src/index.ts

@@ -97,8 +97,19 @@ export { createAgentRegistry } from "./registry.js";
 export type { AgentRegistry, AgentRegistryOptions } from "./registry.js";
 
 // Server
-export { createAgentServer } from "./server.js";
-export type { AgentServer, AgentServerOptions } from "./server.js";
+export { createAgentServer, detectAuth, resolveAuth, canSeeAgent } from "./server.js";
+export type { AgentServer, AgentServerOptions, AuthConfig, ResolvedAuth } from "./server.js";
+
+// Secret Collection
+export {
+  pendingCollections,
+  generateCollectionToken,
+  cleanupExpiredCollections,
+} from "./secret-collection.js";
+export type {
+  PendingCollection,
+  PendingCollectionField,
+} from "./secret-collection.js";
 
 // Auth
 export {
@@ -134,8 +145,8 @@ export type {
 export { encryptSecret, decryptSecret } from "./crypto.js";
 
 // JWT
-export { signJwt, verifyJwt } from "./jwt.js";
-export type { JwtPayload } from "./jwt.js";
+export { signJwt, verifyJwt, signJwtES256, verifyJwtLocal, verifyJwtFromIssuer, generateSigningKey, exportSigningKey, importSigningKey, buildJwks } from "./jwt.js";
+export type { JwtPayload, AgentJwtPayload, SigningKey, ExportedKeyPair } from "./jwt.js";
 
 // Postgres Secret Store
 
@@ -179,3 +190,6 @@ export type {
   UserStore,
   UsersAgentOptions,
 } from "./agent-definitions/users.js";
+export * from "./integrations-store.js";
+export * from "./integration-interface.js";
+export type { ContextFactory } from "./registry.js";

package/src/integration-interface.ts

@@ -0,0 +1,118 @@
+/**
+ * Integration interface — standard tools that integration agents implement.
+ *
+ * Any agent that acts as an integration source should implement these tools.
+ * They are all internal visibility and only callable by @integrations.
+ */
+
+import { defineTool } from './define.js';
+import type { IntegrationsStore } from './integrations-store.js';
+import type { ToolDefinition, ToolContext } from './types.js';
+
+export interface IntegrationDefinition {
+  id: string;
+  agentPath: string;
+  name: string;
+  description: string;
+  type: 'oauth' | 'credentials' | 'config';
+  configSchema?: Record<string, unknown>;
+}
+
+export interface IntegrationInterfaceConfig {
+  agentPath: string;
+  store: IntegrationsStore;
+  discover: () => Promise<IntegrationDefinition[]>;
+  setup: (config: Record<string, unknown>, ctx: ToolContext) => Promise<{ success: boolean; integrationId?: string; oauthUrl?: string; error?: string }>;
+  connect?: (integrationId: string, ctx: ToolContext) => Promise<{ success: boolean; error?: string }>;
+}
+
+/**
+ * Create the standard _integration tools for an agent.
+ * Returns an array of ToolDefinitions to include in the agent's tools.
+ */
+export function createIntegrationTools(config: IntegrationInterfaceConfig): ToolDefinition<ToolContext>[] {
+  const { agentPath, store, discover, setup, connect } = config;
+
+  const discoverTool = defineTool({
+    name: 'discover_integrations',
+    description: `Discover available integrations for ${agentPath}.`,
+    visibility: 'internal' as const,
+    inputSchema: {
+      type: 'object' as const,
+      properties: {},
+    },
+    execute: async () => {
+      const available = await discover();
+      return available;
+    },
+  });
+
+  const setupTool = defineTool({
+    name: 'setup_integration',
+    description: `Set up a new integration for ${agentPath}.`,
+    visibility: 'internal' as const,
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        config: { type: 'object', description: 'Integration configuration' },
+      },
+      required: ['config'],
+    },
+    execute: async (input: { config: Record<string, unknown> }, ctx: ToolContext) => {
+      const result = await setup(input.config, ctx);
+      if (result.success && !result.oauthUrl) {
+        // Direct setup (no OAuth needed) — create integration row
+        const integration = await store.create({
+          agentPath,
+          config: input.config,
+          installedBy: ctx.callerId,
+        });
+        return { success: true, integrationId: integration.id };
+      }
+      return result;
+    },
+  });
+
+  const connectTool = defineTool({
+    name: 'connect_integration',
+    description: `Test or authorize a ${agentPath} integration connection.`,
+    visibility: 'internal' as const,
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        integration_id: { type: 'string', description: 'Integration ID to connect' },
+      },
+      required: ['integration_id'],
+    },
+    execute: async (input: { integration_id: string }, ctx: ToolContext) => {
+      if (connect) {
+        const result = await connect(input.integration_id, ctx);
+        if (result.success) {
+          await store.update(input.integration_id, { status: 'active' });
+        } else {
+          await store.update(input.integration_id, { status: 'error' });
+        }
+        return result;
+      }
+      return { success: true };
+    },
+  });
+
+  const listTool = defineTool({
+    name: 'list_integrations',
+    description: `List installed integrations for ${agentPath}.`,
+    visibility: 'internal' as const,
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        tenant_id: { type: 'string', description: 'Filter by tenant' },
+      },
+    },
+    execute: async (input: { tenant_id?: string }) => {
+      const integrations = await store.listByAgent(agentPath, input.tenant_id);
+      return integrations;
+    },
+  });
+
+  return [discoverTool, setupTool, connectTool, listTool] as ToolDefinition<ToolContext>[];
+}

package/src/integrations-store.ts

@@ -0,0 +1,84 @@
+/**
+ * IntegrationsStore — persistence interface for installed integrations.
+ *
+ * Each integration is an agent that's been configured and connected.
+ * The store tracks what's installed, its config, and status.
+ */
+
+export interface Integration {
+  id: string;
+  agentPath: string;
+  tenantId?: string;
+  status: 'active' | 'disabled' | 'error';
+  config: Record<string, unknown>;
+  installedBy?: string;
+  installedAt: number;
+  updatedAt: number;
+}
+
+export interface CreateIntegrationInput {
+  agentPath: string;
+  tenantId?: string;
+  config: Record<string, unknown>;
+  installedBy?: string;
+}
+
+export interface IntegrationsStore {
+  create(input: CreateIntegrationInput): Promise<Integration>;
+  get(id: string): Promise<Integration | null>;
+  list(tenantId?: string): Promise<Integration[]>;
+  listByAgent(agentPath: string, tenantId?: string): Promise<Integration[]>;
+  update(id: string, updates: Partial<Pick<Integration, 'status' | 'config' | 'updatedAt'>>): Promise<Integration | null>;
+  delete(id: string): Promise<boolean>;
+}
+
+/** In-memory implementation for testing / lightweight use */
+export function createInMemoryIntegrationsStore(): IntegrationsStore {
+  const integrations = new Map<string, Integration>();
+
+  return {
+    async create(input) {
+      const id = `int_${Math.random().toString(36).slice(2, 14)}`;
+      const now = Date.now();
+      const integration: Integration = {
+        id,
+        agentPath: input.agentPath,
+        tenantId: input.tenantId,
+        status: 'active',
+        config: input.config,
+        installedBy: input.installedBy,
+        installedAt: now,
+        updatedAt: now,
+      };
+      integrations.set(id, integration);
+      return integration;
+    },
+
+    async get(id) {
+      return integrations.get(id) ?? null;
+    },
+
+    async list(tenantId?) {
+      const all = Array.from(integrations.values());
+      return tenantId ? all.filter(i => i.tenantId === tenantId) : all;
+    },
+
+    async listByAgent(agentPath, tenantId?) {
+      return Array.from(integrations.values()).filter(
+        i => i.agentPath === agentPath && (!tenantId || i.tenantId === tenantId)
+      );
+    },
+
+    async update(id, updates) {
+      const existing = integrations.get(id);
+      if (!existing) return null;
+      const updated = { ...existing, ...updates, updatedAt: Date.now() };
+      integrations.set(id, updated);
+      return updated;
+    },
+
+    async delete(id) {
+      return integrations.delete(id);
+    },
+  };
+}