@slashfi/agents-sdk 0.24.1 → 0.24.3

package/dist/cjs/agent-definitions/integrations.js

@@ -0,0 +1,1173 @@
+"use strict";
+/**
+ * Integrations Agent (@integrations)
+ *
+ * Built-in agent for managing third-party API integrations.
+ * Provides OAuth2 flows, provider config management, and API calling.
+ *
+ * Features:
+ * - Provider config management (setup/list/get)
+ * - OAuth2 authorization code flow (connect)
+ * - API calling with auto-injected auth (REST + GraphQL)
+ * - Agent-registry type for agent-to-agent federation
+ * - Pluggable IntegrationStore interface
+ *
+ * @example
+ * ```typescript
+ * import { createAgentRegistry, createIntegrationsAgent } from '@slashfi/agents-sdk';
+ *
+ * const registry = createAgentRegistry();
+ * registry.register(createIntegrationsAgent({
+ *   store: myIntegrationStore,
+ *   callbackBaseUrl: 'https://myapp.com/oauth/callback',
+ * }));
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInMemoryIntegrationStore = createInMemoryIntegrationStore;
+exports.getDefaultTokenBodyParams = getDefaultTokenBodyParams;
+exports.getDefaultRefreshBodyParams = getDefaultRefreshBodyParams;
+exports.exchangeCodeForToken = exchangeCodeForToken;
+exports.refreshAccessToken = refreshAccessToken;
+exports.createIntegrationsAgent = createIntegrationsAgent;
+const define_js_1 = require("../define.js");
+const secret_collection_js_1 = require("../secret-collection.js");
+// ============================================
+// In-Memory Integration Store
+// ============================================
+function createInMemoryIntegrationStore() {
+    const providers = new Map();
+    const connections = new Map(); // key: `${userId}:${providerId}`
+    function connKey(userId, providerId) {
+        return `${userId}:${providerId}`;
+    }
+    return {
+        async getProvider(providerId) {
+            return providers.get(providerId) ?? null;
+        },
+        async listProviders() {
+            return Array.from(providers.values());
+        },
+        async upsertProvider(config) {
+            providers.set(config.id, config);
+        },
+        async deleteProvider(providerId) {
+            return providers.delete(providerId);
+        },
+        async getConnection(userId, providerId) {
+            return connections.get(connKey(userId, providerId)) ?? null;
+        },
+        async listConnections(userId) {
+            return Array.from(connections.values()).filter((c) => c.userId === userId);
+        },
+        async upsertConnection(connection) {
+            connections.set(connKey(connection.userId, connection.providerId), connection);
+        },
+        async deleteConnection(userId, providerId) {
+            return connections.delete(connKey(userId, providerId));
+        },
+    };
+}
+// ============================================
+// Token Exchange Helpers
+// ============================================
+const DEFAULT_TOKEN_BODY_PARAMS = {
+    client_secret_post: [
+        "grant_type",
+        "code",
+        "redirect_uri",
+        "client_id",
+        "client_secret",
+    ],
+    client_secret_basic: ["grant_type", "code", "redirect_uri"],
+};
+const DEFAULT_REFRESH_BODY_PARAMS = {
+    client_secret_post: [
+        "grant_type",
+        "refresh_token",
+        "client_id",
+        "client_secret",
+    ],
+    client_secret_basic: ["grant_type", "refresh_token"],
+};
+function getDefaultTokenBodyParams(method) {
+    return DEFAULT_TOKEN_BODY_PARAMS[method];
+}
+function getDefaultRefreshBodyParams(method) {
+    return DEFAULT_REFRESH_BODY_PARAMS[method];
+}
+function buildBasicAuth(clientId, clientSecret) {
+    const encoded = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
+    return `Basic ${encoded}`;
+}
+function buildAuthHeaders(config, accessToken) {
+    if (!config.api)
+        return {};
+    const { auth } = config.api;
+    const headerName = auth.headerName ?? "Authorization";
+    const prefix = auth.prefix ?? "Bearer";
+    return auth.type === "bearer" || auth.type === "header"
+        ? { [headerName]: `${prefix} ${accessToken}` }
+        : { [headerName]: buildBasicAuth(accessToken, "") };
+}
+async function exchangeCodeForToken(config, code, redirectUri, clientId, clientSecret) {
+    if (!config.auth)
+        throw new Error(`Provider ${config.id} has no OAuth config`);
+    const oauth = config.auth;
+    const grantType = oauth.tokenGrantType ?? "authorization_code";
+    const bodyParams = oauth.tokenBodyParams ?? getDefaultTokenBodyParams(oauth.clientAuthMethod);
+    const allParams = {
+        grant_type: grantType,
+        code,
+        redirect_uri: redirectUri,
+        client_id: clientId,
+        client_secret: clientSecret,
+    };
+    const body = {};
+    for (const key of bodyParams) {
+        if (allParams[key])
+            body[key] = allParams[key];
+    }
+    const headers = {
+        "Content-Type": oauth.tokenContentType,
+        ...(oauth.tokenHeaders ?? {}),
+    };
+    if (oauth.clientAuthMethod === "client_secret_basic") {
+        headers.Authorization = buildBasicAuth(clientId, clientSecret);
+    }
+    const fetchBody = oauth.tokenContentType === "application/x-www-form-urlencoded"
+        ? new URLSearchParams(body).toString()
+        : JSON.stringify(body);
+    const response = await fetch(oauth.tokenUrl, {
+        method: "POST",
+        headers,
+        body: fetchBody,
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Token exchange failed (${response.status}): ${text}`);
+    }
+    const responseText = await response.text();
+    console.log("[token-exchange] Slack response:", responseText.substring(0, 500));
+    let data;
+    try {
+        data = JSON.parse(responseText);
+    }
+    catch (e) {
+        throw new Error(`Failed to parse JSON: ${responseText.substring(0, 200)}`);
+    }
+    return {
+        accessToken: String(data[oauth.accessTokenField ?? "access_token"] ?? ""),
+        refreshToken: data[oauth.refreshTokenField ?? "refresh_token"],
+        expiresIn: data[oauth.expiresInField ?? "expires_in"],
+        tokenType: data[oauth.tokenTypeField ?? "token_type"],
+    };
+}
+async function refreshAccessToken(config, refreshToken, clientId, clientSecret) {
+    if (!config.auth)
+        throw new Error(`Provider ${config.id} has no OAuth config`);
+    const oauth = config.auth;
+    const url = oauth.refreshUrl ?? oauth.tokenUrl;
+    const grantType = oauth.refreshGrantType ?? "refresh_token";
+    const method = oauth.refreshClientAuthMethod ?? oauth.clientAuthMethod;
+    const contentType = oauth.refreshContentType ?? oauth.tokenContentType;
+    const bodyParams = oauth.refreshBodyParams ?? getDefaultRefreshBodyParams(method);
+    const allParams = {
+        grant_type: grantType,
+        refresh_token: refreshToken,
+        client_id: clientId,
+        client_secret: clientSecret,
+    };
+    const body = {};
+    for (const key of bodyParams) {
+        if (allParams[key])
+            body[key] = allParams[key];
+    }
+    const headers = {
+        "Content-Type": contentType,
+        ...(oauth.refreshHeaders ?? oauth.tokenHeaders ?? {}),
+    };
+    if (method === "client_secret_basic") {
+        headers.Authorization = buildBasicAuth(clientId, clientSecret);
+    }
+    const fetchBody = contentType === "application/x-www-form-urlencoded"
+        ? new URLSearchParams(body).toString()
+        : JSON.stringify(body);
+    const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: fetchBody,
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Token refresh failed (${response.status}): ${text}`);
+    }
+    const responseText = await response.text();
+    console.log("[token-exchange] Slack response:", responseText.substring(0, 500));
+    let data;
+    try {
+        data = JSON.parse(responseText);
+    }
+    catch (e) {
+        throw new Error(`Failed to parse JSON: ${responseText.substring(0, 200)}`);
+    }
+    return {
+        accessToken: String(data[oauth.accessTokenField ?? "access_token"] ?? ""),
+        refreshToken: data[oauth.refreshTokenField ?? "refresh_token"],
+        expiresIn: data[oauth.expiresInField ?? "expires_in"],
+        tokenType: data[oauth.tokenTypeField ?? "token_type"],
+    };
+}
+// ============================================
+// API Call Execution
+// ============================================
+async function executeRestCall(config, input, accessToken) {
+    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);
+        }
+    }
+    const headers = {
+        ...buildAuthHeaders(config, accessToken),
+        ...(config.api?.defaultHeaders ?? {}),
+    };
+    if (input.body) {
+        headers["Content-Type"] = "application/json";
+    }
+    const response = await fetch(url.toString(), {
+        method: input.method,
+        headers,
+        body: input.body ? JSON.stringify(input.body) : undefined,
+    });
+    const text = await response.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { status: response.status, body: text };
+    }
+}
+async function executeGraphqlCall(config, input, accessToken) {
+    const headers = {
+        "Content-Type": "application/json",
+        ...buildAuthHeaders(config, accessToken),
+        ...(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,
+        body: JSON.stringify({ query: input.query, variables: input.variables }),
+    });
+    return response.json();
+}
+// ============================================
+// Credential Storage Helpers
+// ============================================
+const SYSTEM_OWNER = "__integrations__";
+// ============================================
+// Create Integrations Agent
+// ============================================
+function createIntegrationsAgent(options) {
+    const { store, callbackBaseUrl, secretStore } = options;
+    // ---- setup_integration ----
+    const setupTool = (0, define_js_1.defineTool)({
+        name: "setup_integration",
+        description: "Create or update an integration provider config. " +
+            "Registers a third-party API (REST, GraphQL, or agent-registry) " +
+            "with its OAuth and API configuration.",
+        visibility: "public",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: {
+                    type: "string",
+                    description: "Provider ID (e.g. 'linear', 'notion')",
+                },
+                name: { type: "string", description: "Display name" },
+                agentPath: {
+                    type: "string",
+                    description: "Agent path that handles this integration (e.g. '@remote-registry', '@databases'). Omit for simple REST/GraphQL integrations.",
+                },
+                scope: {
+                    type: "string",
+                    enum: ["user", "tenant"],
+                    description: "'user' for per-user tokens, 'tenant' for shared org-wide. Default: user",
+                },
+                api: {
+                    type: "object",
+                    description: "API config: baseUrl, auth type, default headers",
+                    properties: {
+                        baseUrl: { type: "string", description: "API base URL" },
+                        docsUrl: { type: "string", description: "API docs URL" },
+                        defaultHeaders: {
+                            type: "object",
+                            description: "Default headers for all requests",
+                            additionalProperties: { type: "string" },
+                        },
+                        auth: {
+                            type: "object",
+                            description: "Auth config",
+                            properties: {
+                                type: { type: "string", enum: ["bearer", "basic", "header"] },
+                                headerName: { type: "string" },
+                                prefix: { type: "string" },
+                            },
+                            required: ["type"],
+                        },
+                    },
+                    required: ["baseUrl", "auth"],
+                },
+                auth: {
+                    type: "object",
+                    description: "OAuth config (optional — omit for token-less integrations)",
+                    properties: {
+                        authUrl: { type: "string" },
+                        tokenUrl: { type: "string" },
+                        scopes: { type: "array", items: { type: "string" } },
+                        scopeSeparator: { type: "string" },
+                        clientAuthMethod: {
+                            type: "string",
+                            enum: ["client_secret_post", "client_secret_basic"],
+                        },
+                        tokenContentType: {
+                            type: "string",
+                            enum: ["application/x-www-form-urlencoded", "application/json"],
+                        },
+                        tokenGrantType: { type: "string" },
+                        tokenBodyParams: { type: "array", items: { type: "string" } },
+                        tokenHeaders: {
+                            type: "object",
+                            additionalProperties: { type: "string" },
+                        },
+                        authUrlExtraParams: {
+                            type: "object",
+                            additionalProperties: { type: "string" },
+                        },
+                        accessTokenField: { type: "string" },
+                        refreshTokenField: { type: "string" },
+                        expiresInField: { type: "string" },
+                        tokenTypeField: { type: "string" },
+                        refreshUrl: { type: "string" },
+                        refreshClientAuthMethod: {
+                            type: "string",
+                            enum: ["client_secret_post", "client_secret_basic"],
+                        },
+                        refreshContentType: {
+                            type: "string",
+                            enum: ["application/x-www-form-urlencoded", "application/json"],
+                        },
+                        refreshGrantType: { type: "string" },
+                        refreshBodyParams: { type: "array", items: { type: "string" } },
+                        refreshHeaders: {
+                            type: "object",
+                            additionalProperties: { type: "string" },
+                        },
+                    },
+                },
+                docs: {
+                    type: "object",
+                    description: "Documentation links",
+                    properties: {
+                        llmsTxt: { type: "string" },
+                        human: { type: "array", items: { type: "string" } },
+                    },
+                },
+                clientId: {
+                    secret: true,
+                    type: "string",
+                    description: "OAuth client ID for this provider. Stored encrypted.",
+                },
+                clientSecret: {
+                    secret: true,
+                    type: "string",
+                    description: "OAuth client secret for this provider. Stored encrypted.",
+                },
+            },
+            required: ["id", "name", "type", "api"],
+        },
+        execute: async (input, _ctx) => {
+            const config = {
+                id: input.id,
+                name: input.name,
+                agentPath: input.agentPath,
+                scope: input.scope,
+                docs: input.docs,
+                auth: input.auth,
+                api: input.api,
+            };
+            // Store client credentials encrypted and save secret IDs
+            const result = { success: true };
+            if (input.clientId) {
+                const secretId = await secretStore.store(input.clientId, SYSTEM_OWNER);
+                config._clientIdSecretId = secretId;
+                result.clientIdStored = true;
+            }
+            if (input.clientSecret) {
+                const secretId = await secretStore.store(input.clientSecret, SYSTEM_OWNER);
+                config._clientSecretSecretId = secretId;
+                result.clientSecretStored = true;
+            }
+            await store.upsertProvider(config);
+            // Delegate to agent's setup_integration tool via registry.call()
+            if (config.agentPath && options.registry) {
+                try {
+                    const setupResult = await options.registry.call({
+                        action: "execute_tool",
+                        path: config.agentPath,
+                        tool: "setup_integration",
+                        params: input.config ?? input,
+                        callerType: "system",
+                    });
+                    result.setupResult = setupResult?.result ?? setupResult;
+                }
+                catch (err) {
+                    result.setupError = err instanceof Error ? err.message : String(err);
+                }
+            }
+            result.provider = config;
+            return result;
+        },
+    });
+    // ---- discover_integrations ----
+    const discoverTool = (0, define_js_1.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",
+        inputSchema: {
+            type: "object",
+            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, _ctx) => {
+            const catalog = [];
+            // 1. Agent-backed integrations
+            if (options.registry) {
+                for (const agent of options.registry.list?.() ?? []) {
+                    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 = (0, define_js_1.defineTool)({
+        name: "list_integrations",
+        description: "List configured integration providers and user's connections.",
+        visibility: "public",
+        inputSchema: {
+            type: "object",
+            properties: {
+                userId: {
+                    type: "string",
+                    description: "User ID to check connections for (optional)",
+                },
+            },
+        },
+        execute: async (input, ctx) => {
+            const providers = await store.listProviders();
+            const userId = input.userId ?? ctx.callerId;
+            const connections = userId ? await store.listConnections(userId) : [];
+            // Build unified integrations list
+            const integrations = [];
+            // 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 + list_integrations tool)
+            if (options.registry) {
+                const agents = options.registry.list?.() ?? [];
+                for (const agent of agents) {
+                    const hasListTool = agent.tools?.some((t) => t.name === "list_integrations");
+                    if (hasListTool && 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 callResult = options.registry
+                                ? await options.registry.call({
+                                    action: "execute_tool",
+                                    path: agent.path,
+                                    tool: "list_integrations",
+                                    params: {},
+                                    callerType: "system",
+                                })
+                                : null;
+                            const result = callResult?.result ??
+                                callResult ?? { success: false };
+                            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).find(Array.isArray) ?? []);
+                                for (const item of items) {
+                                    integrations.push({
+                                        ...meta,
+                                        ...(typeof item === "object" && item !== null
+                                            ? item
+                                            : { 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,
+                    expiresAt: c.expiresAt,
+                })),
+            };
+        },
+    });
+    // ---- get_integration ----
+    const getTool = (0, define_js_1.defineTool)({
+        name: "get_integration",
+        description: "Get a specific integration provider config.",
+        visibility: "public",
+        inputSchema: {
+            type: "object",
+            properties: {
+                provider: { type: "string", description: "Provider ID" },
+            },
+            required: ["provider"],
+        },
+        execute: async (input, _ctx) => {
+            const config = await store.getProvider(input.provider);
+            if (!config)
+                return { error: `Provider '${input.provider}' not found` };
+            return { provider: config };
+        },
+    });
+    // ---- connect_integration ----
+    const connectTool = (0, define_js_1.defineTool)({
+        name: "connect_integration",
+        description: "Generate an OAuth authorization URL for a user to connect an integration. " +
+            "Returns the URL the user should visit to authorize.",
+        visibility: "public",
+        inputSchema: {
+            type: "object",
+            properties: {
+                provider: { type: "string", description: "Provider ID to connect" },
+                userId: {
+                    type: "string",
+                    description: "User ID (optional, defaults to caller)",
+                },
+                state: {
+                    type: "string",
+                    description: "Optional state param for the OAuth flow",
+                },
+            },
+            required: ["provider"],
+        },
+        execute: async (input, ctx) => {
+            const config = await store.getProvider(input.provider);
+            if (!config)
+                return { error: `Provider '${input.provider}' not found` };
+            // Delegate to agent's connect_integration tool via registry.call()
+            if (config.agentPath && options.registry) {
+                const connectResult = await options.registry.call({
+                    action: "execute_tool",
+                    path: config.agentPath,
+                    tool: "connect_integration",
+                    params: { ...input, registryId: config.id },
+                    callerType: "system",
+                });
+                return connectResult?.result ?? connectResult;
+            }
+            if (!config.auth)
+                return { error: `Provider '${input.provider}' has no OAuth config` };
+            if (!callbackBaseUrl)
+                return { error: "No callbackBaseUrl configured for OAuth flows" };
+            const oauth = config.auth;
+            const redirectUri = callbackBaseUrl;
+            const userId = input.userId ?? ctx.callerId;
+            // Resolve client ID from secret store
+            // Check both _clientIdSecretId (from setup_integration direct) and
+            // clientId field as secret:ref (from collect_secrets flow)
+            let clientId = null;
+            const cidSecretId = config._clientIdSecretId;
+            if (cidSecretId && secretStore) {
+                clientId = await secretStore.resolve(cidSecretId, SYSTEM_OWNER);
+            }
+            // Also check if auth config has clientId as a secret:ref
+            if (!clientId &&
+                oauth.clientId &&
+                typeof oauth.clientId === "string") {
+                if (oauth.clientId.startsWith("secret:") && secretStore) {
+                    const refId = oauth.clientId.slice("secret:".length);
+                    clientId = await secretStore.resolve(refId, SYSTEM_OWNER);
+                }
+                else if (!oauth.clientId.startsWith("secret:")) {
+                    clientId = oauth.clientId;
+                }
+            }
+            // Check top-level config too
+            if (!clientId && config.clientId) {
+                const cid = config.clientId;
+                if (typeof cid === "string" &&
+                    cid.startsWith("secret:") &&
+                    secretStore) {
+                    clientId = await secretStore.resolve(cid.slice("secret:".length), SYSTEM_OWNER);
+                }
+                else if (typeof cid === "string" && !cid.startsWith("secret:")) {
+                    clientId = cid;
+                }
+            }
+            if (!clientId) {
+                return {
+                    error: `No client credentials stored for '${config.id}'. Use setup_integration with clientId/clientSecret or collect_secrets.`,
+                };
+            }
+            const separator = oauth.scopeSeparator ?? " ";
+            const scopeStr = oauth.scopes.join(separator);
+            const params = new URLSearchParams({
+                client_id: clientId,
+                redirect_uri: redirectUri,
+                response_type: "code",
+                ...(scopeStr ? { scope: scopeStr } : {}),
+                state: input.state ??
+                    btoa(JSON.stringify({
+                        userId,
+                        providerId: config.id,
+                        redirectUrl: input.redirectUrl ?? "/",
+                    })),
+                ...(oauth.authUrlExtraParams ?? {}),
+            });
+            return {
+                authUrl: `${oauth.authUrl}?${params.toString()}`,
+                redirectUri,
+                provider: config.id,
+            };
+        },
+    });
+    // ---- call_integration ----
+    const callTool = (0, define_js_1.defineTool)({
+        name: "call_integration",
+        description: "Call a configured integration API. Supports REST, GraphQL, and agent-registry types. " +
+            "Automatically injects the user's access token.",
+        visibility: "public",
+        inputSchema: {
+            type: "object",
+            properties: {
+                provider: { type: "string", description: "Provider ID" },
+                type: {
+                    type: "string",
+                    enum: ["rest", "graphql"],
+                    description: "Call type (rest or graphql)",
+                },
+                // REST fields
+                method: {
+                    type: "string",
+                    enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+                },
+                path: { type: "string", description: "API path (for REST)" },
+                body: {
+                    type: "object",
+                    description: "Request body (for REST POST/PUT/PATCH)",
+                },
+                query: {
+                    type: "object",
+                    description: "Query params (for REST)",
+                    additionalProperties: { type: "string" },
+                },
+                // GraphQL fields
+                graphqlQuery: { type: "string", description: "GraphQL query string" },
+                variables: { type: "object", description: "GraphQL variables" },
+                // Agent-registry fields
+                agent: {
+                    type: "string",
+                    description: "Agent path (for agent-registry)",
+                },
+                tool: { type: "string", description: "Tool name (for agent-registry)" },
+                params: {
+                    type: "object",
+                    description: "Tool params (for agent-registry)",
+                },
+            },
+            required: ["provider", "type"],
+        },
+        execute: async (input, ctx) => {
+            const config = await store.getProvider(input.provider);
+            if (!config)
+                return { error: `Provider '${input.provider}' not found` };
+            const userId = ctx.callerId;
+            // Get access token
+            const connection = await store.getConnection(userId, input.provider);
+            if (!connection) {
+                return {
+                    error: `Not connected to '${input.provider}'. Use connect_integration first.`,
+                    hint: "connect_integration",
+                };
+            }
+            // Check if token needs refresh
+            let accessToken = connection.accessToken;
+            if (connection.expiresAt &&
+                connection.expiresAt < Date.now() &&
+                connection.refreshToken) {
+                try {
+                    const rCidId = config._clientIdSecretId;
+                    const rCsecId = config._clientSecretSecretId;
+                    if (!rCidId || !rCsecId) {
+                        throw new Error("No client credentials stored. Re-run setup_integration with clientId/clientSecret.");
+                    }
+                    const clientId = await secretStore.resolve(rCidId, SYSTEM_OWNER);
+                    const clientSecret = await secretStore.resolve(rCsecId, SYSTEM_OWNER);
+                    if (!clientId || !clientSecret) {
+                        throw new Error("Failed to resolve client credentials from secret store.");
+                    }
+                    const refreshed = await refreshAccessToken(config, connection.refreshToken, clientId, clientSecret);
+                    accessToken = refreshed.accessToken;
+                    // Update stored connection
+                    await store.upsertConnection({
+                        ...connection,
+                        accessToken: refreshed.accessToken,
+                        refreshToken: refreshed.refreshToken ?? connection.refreshToken,
+                        expiresAt: refreshed.expiresIn
+                            ? Date.now() + refreshed.expiresIn * 1000
+                            : connection.expiresAt,
+                    });
+                }
+                catch (err) {
+                    return {
+                        error: `Token refresh failed for '${input.provider}': ${err instanceof Error ? err.message : String(err)}`,
+                        hint: "connect_integration",
+                    };
+                }
+            }
+            // Execute the call based on type
+            switch (input.type) {
+                case "rest":
+                    return executeRestCall(config, {
+                        provider: input.provider,
+                        type: "rest",
+                        method: input.method ?? "GET",
+                        path: input.path ?? "/",
+                        body: input.body,
+                        query: input.query,
+                    }, accessToken);
+                case "graphql":
+                    return executeGraphqlCall(config, {
+                        provider: input.provider,
+                        type: "graphql",
+                        query: input.graphqlQuery ?? input.query ?? "",
+                        variables: input.variables,
+                    }, accessToken);
+                default:
+                    return {
+                        error: `Unknown call type: ${input.type}. Use 'rest' or 'graphql'.`,
+                    };
+            }
+        },
+    });
+    // ---- handle_callback (OAuth callback handler) ----
+    const callbackTool = (0, define_js_1.defineTool)({
+        name: "handle_oauth_callback",
+        description: "Handle an OAuth callback. Exchanges the authorization code for tokens and stores the connection. " +
+            "This is typically called by the HTTP server when the OAuth redirect hits the callback URL.",
+        visibility: "internal",
+        inputSchema: {
+            type: "object",
+            properties: {
+                provider: { type: "string", description: "Provider ID" },
+                code: {
+                    type: "string",
+                    description: "Authorization code from the OAuth redirect",
+                },
+                state: {
+                    type: "string",
+                    description: "State param from the OAuth redirect",
+                },
+            },
+            required: ["provider", "code"],
+        },
+        execute: async (input, ctx) => {
+            const config = await store.getProvider(input.provider);
+            if (!config)
+                return { error: `Provider '${input.provider}' not found` };
+            // Delegate to agent's connect_integration tool via registry.call()
+            if (config.agentPath && options.registry) {
+                const connectResult = await options.registry.call({
+                    action: "execute_tool",
+                    path: config.agentPath,
+                    tool: "connect_integration",
+                    params: { ...input, registryId: config.id },
+                    callerType: "system",
+                });
+                return connectResult?.result ?? connectResult;
+            }
+            if (!config.auth)
+                return { error: `Provider '${input.provider}' has no OAuth config` };
+            if (!callbackBaseUrl)
+                return { error: "No callbackBaseUrl configured" };
+            // Parse state to get userId
+            let userId = ctx.callerId;
+            if (input.state) {
+                try {
+                    const parsed = JSON.parse(atob(input.state));
+                    if (parsed.userId)
+                        userId = parsed.userId;
+                }
+                catch { }
+            }
+            // Resolve client credentials from secret store via config
+            const cbCidId = config._clientIdSecretId;
+            const cbCsecId = config._clientSecretSecretId;
+            if (!cbCidId || !cbCsecId) {
+                return { error: "No client credentials stored for this provider." };
+            }
+            const clientId = await secretStore.resolve(cbCidId, SYSTEM_OWNER);
+            const clientSecret = await secretStore.resolve(cbCsecId, SYSTEM_OWNER);
+            if (!clientId || !clientSecret) {
+                return { error: "Failed to resolve client credentials." };
+            }
+            const redirectUri = callbackBaseUrl;
+            const result = await exchangeCodeForToken(config, input.code, redirectUri, clientId, clientSecret);
+            const connection = {
+                userId,
+                providerId: config.id,
+                accessToken: result.accessToken,
+                refreshToken: result.refreshToken,
+                expiresAt: result.expiresIn
+                    ? Date.now() + result.expiresIn * 1000
+                    : undefined,
+                tokenType: result.tokenType,
+                scopes: config.auth.scopes,
+                connectedAt: Date.now(),
+            };
+            await store.upsertConnection(connection);
+            return {
+                success: true,
+                provider: config.id,
+                userId,
+                connectedAt: connection.connectedAt,
+                accessToken: result.accessToken,
+            };
+        },
+    });
+    // ---- collect_secrets ----
+    const collectSecretsTool = (0, define_js_1.defineTool)({
+        name: "collect_secrets",
+        description: "Collect secrets and missing fields for a tool via a secure form. " +
+            "Pass the target agent + tool + any params you already have. " +
+            "Returns a form spec with fields the user needs to fill in. " +
+            "Secrets bypass the LLM entirely. On form submission, the server auto-calls the target tool.",
+        visibility: "public",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent: {
+                    type: "string",
+                    description: "Target agent path (e.g. '@databases')",
+                },
+                tool: {
+                    type: "string",
+                    description: "Target tool name (e.g. 'add_connection')",
+                },
+                params: {
+                    type: "object",
+                    description: "Partial params already collected",
+                },
+                registry: {
+                    type: "string",
+                    description: "Remote registry URL. Omit for local.",
+                },
+                source: {
+                    type: "object",
+                    description: "Where to render the form. Determines form delivery method.",
+                    properties: {
+                        type: {
+                            type: "string",
+                            enum: ["slack", "web", "cli"],
+                            description: "Platform type",
+                        },
+                        workspace: {
+                            type: "string",
+                            description: "Slack workspace ID (for slack)",
+                        },
+                        channel: {
+                            type: "string",
+                            description: "Slack channel ID (for slack)",
+                        },
+                        threadTs: {
+                            type: "string",
+                            description: "Slack thread timestamp (for slack)",
+                        },
+                        redirectUrl: {
+                            type: "string",
+                            description: "URL to redirect after submission (for web)",
+                        },
+                    },
+                    required: ["type"],
+                },
+            },
+            required: ["agent", "tool"],
+        },
+        execute: async (input, ctx) => {
+            // Fetch tool schema from registry
+            let toolSchema = null;
+            const registryUrl = input.registry;
+            if (!registryUrl) {
+                return { error: "Registry URL required for now. Pass registry param." };
+            }
+            const res = await fetch(`${registryUrl}/mcp`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: 1,
+                    method: "tools/call",
+                    params: {
+                        name: "call_agent",
+                        arguments: {
+                            request: { action: "describe_tools", path: input.agent },
+                        },
+                    },
+                }),
+            });
+            const data = (await res.json());
+            const parsed = JSON.parse(data?.result?.content?.[0]?.text ?? "{}");
+            const tools = parsed?.tools ?? parsed?.result?.tools ?? [];
+            toolSchema = tools.find((t) => t.name === input.tool) ?? null;
+            if (!toolSchema?.inputSchema) {
+                return { error: `Tool '${input.tool}' not found on '${input.agent}'` };
+            }
+            const schema = toolSchema.inputSchema;
+            const properties = schema.properties ?? {};
+            const requiredFields = new Set(schema.required ?? []);
+            const providedParams = input.params ?? {};
+            // Compute fields: secret fields always, required fields if not provided
+            const fields = [];
+            for (const [name, def] of Object.entries(properties)) {
+                const isSecret = def.secret === true;
+                const isRequired = requiredFields.has(name);
+                const isProvided = name in providedParams;
+                if (isSecret || (isRequired && !isProvided)) {
+                    fields.push({
+                        name,
+                        type: def.type ?? "string",
+                        description: def.description ?? name,
+                        secret: isSecret,
+                        required: isRequired,
+                    });
+                }
+            }
+            if (fields.length === 0) {
+                return {
+                    message: "All fields provided. Call the tool directly.",
+                    canCallDirectly: true,
+                };
+            }
+            // Register pending collection
+            const token = (0, secret_collection_js_1.generateCollectionToken)();
+            secret_collection_js_1.pendingCollections.set(token, {
+                params: providedParams,
+                agent: input.agent,
+                tool: input.tool,
+                auth: {
+                    callerId: ctx.callerId,
+                    callerType: ctx.callerType,
+                    scopes: [],
+                    isRoot: false,
+                },
+                fields: fields.map((f) => ({
+                    name: f.name,
+                    description: f.description,
+                    secret: f.secret,
+                    required: f.required,
+                })),
+                createdAt: Date.now(),
+            });
+            // Build callback URL from callbackBaseUrl
+            const baseUrl = callbackBaseUrl
+                ?.replace(/\/oauth\/callback$/, "")
+                .replace(/\/integrations\/callback$/, "") ?? "";
+            return {
+                url: `${baseUrl}/secrets/form/${token}`,
+                message: `Open this link to securely enter credentials for ${input.tool} on ${input.agent}. They will be encrypted and never pass through the AI.`,
+                expiresIn: 600,
+            };
+        },
+    });
+    // ---- Facade: discover_integrations (aggregates from all agents) ----
+    const discoverFacadeTool = (0, define_js_1.defineTool)({
+        name: "discover_integrations",
+        description: "Discover all available integrations across all registered agents.",
+        visibility: "public",
+        inputSchema: { type: "object", properties: {} },
+        execute: async () => {
+            const agents = options.registry?.list?.() ?? [];
+            const results = [];
+            if (options.registry) {
+                for (const agent of agents) {
+                    const hasDiscoverTool = agent.tools?.some((t) => 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 = (0, define_js_1.defineTool)({
+        name: "list_integrations",
+        description: "List all installed integrations across all agents.",
+        visibility: "public",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent_path: { type: "string", description: "Filter by agent path" },
+            },
+        },
+        execute: async (input) => {
+            const agents = options.registry?.list?.() ?? [];
+            const results = [];
+            if (options.registry) {
+                const targetAgents = input.agent_path
+                    ? agents.filter((a) => a.path === input.agent_path)
+                    : agents;
+                for (const agent of targetAgents) {
+                    const hasListTool = agent.tools?.some((t) => 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 (0, define_js_1.defineAgent)({
+        path: "@integrations",
+        entrypoint: "You are the integrations agent. You manage third-party API integrations " +
+            "including OAuth connections, provider configs, and API calling.",
+        config: {
+            name: "Integrations",
+            description: "Third-party API integration management with OAuth2 support",
+            supportedActions: ["execute_tool", "describe_tools", "load"],
+        },
+        visibility: "public",
+        tools: [
+            setupTool,
+            discoverTool,
+            listTool,
+            getTool,
+            connectTool,
+            callTool,
+            callbackTool,
+            collectSecretsTool,
+            discoverFacadeTool,
+            listFacadeTool,
+        ],
+    });
+}
+//# sourceMappingURL=integrations.js.map