@slashfi/agents-sdk 0.26.2 → 0.27.0

package/src/agent-definitions/config.ts

@@ -0,0 +1,318 @@
+/**
+ * Config Agent (@config)
+ *
+ * Built-in agent for managing consumer configuration — refs and registries.
+ * Replaces @integrations and the LLM-facing parts of @auth.
+ *
+ * Provides:
+ * - add_ref / remove_ref / list_refs for managing agent refs
+ * - add_registry for registering new registries
+ * - FsStore interface for pluggable filesystem storage (VCS-backed or local)
+ *
+ * @example
+ * ```typescript
+ * import { createAgentRegistry, createConfigAgent } from '@slashfi/agents-sdk';
+ *
+ * const registry = createAgentRegistry();
+ * registry.register(createConfigAgent({
+ *   store: myFsStore,
+ * }));
+ * ```
+ */
+
+import type { ConsumerConfig, RefEntry } from "../define-config.js";
+import { normalizeRef } from "../define-config.js";
+import { defineAgent, defineTool } from "../define.js";
+import type { AgentDefinition, ToolContext } from "../types.js";
+
+// ============================================
+// FsStore Interface
+// ============================================
+
+/**
+ * Filesystem store for reading/writing consumer configs.
+ * The storage engine (VCS, local fs, etc.) is abstracted away.
+ */
+export interface FsStore {
+  /** Read a file as UTF-8 string. Returns null if not found. */
+  readFile(path: string): Promise<string | null>;
+  /** Write a file with UTF-8 content. Creates parent dirs if needed. */
+  writeFile(path: string, content: string): Promise<void>;
+}
+
+// ============================================
+// Config Persistence
+// ============================================
+
+const CONFIG_PATH = "consumer-config.json";
+
+async function readConfig(store: FsStore): Promise<ConsumerConfig> {
+  const content = await store.readFile(CONFIG_PATH);
+  if (!content) return {};
+  try {
+    return JSON.parse(content) as ConsumerConfig;
+  } catch {
+    return {};
+  }
+}
+
+async function writeConfig(
+  store: FsStore,
+  config: ConsumerConfig,
+): Promise<void> {
+  await store.writeFile(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+// ============================================
+// Config Agent Options
+// ============================================
+
+export interface ConfigAgentOptions {
+  /** Filesystem store for persisting consumer config */
+  store: FsStore;
+
+  /**
+   * Resolve the FsStore for a specific user.
+   * When provided, refs are stored per-user.
+   * The callerId from ToolContext is passed.
+   */
+  resolveUserStore?: (callerId: string) => FsStore;
+}
+
+// ============================================
+// Create Config Agent
+// ============================================
+
+export function createConfigAgent(
+  options: ConfigAgentOptions,
+): AgentDefinition {
+  const { store, resolveUserStore } = options;
+
+  function getStore(ctx: ToolContext): FsStore {
+    if (resolveUserStore && ctx.callerId) {
+      return resolveUserStore(ctx.callerId);
+    }
+    return store;
+  }
+
+  // ---- add_ref ----
+  const addRefTool = defineTool({
+    name: "add_ref",
+    description:
+      "Add or update an agent ref in the consumer config. " +
+      "The ref is persisted to the config store.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        ref: {
+          type: "string",
+          description: 'Agent ref name (e.g. "notion", "linear")',
+        },
+        as: {
+          type: "string",
+          description: "Local alias (for multi-instance refs)",
+        },
+        url: {
+          type: "string",
+          description: "Direct URL to the agent",
+        },
+        config: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          description: "Per-instance config (secret URIs or literal values)",
+        },
+        registry: {
+          type: "string",
+          description:
+            'Registry to resolve from (e.g. "slash", "mcp", "https")',
+        },
+      },
+      required: ["ref"],
+    },
+    execute: async (
+      input: {
+        ref: string;
+        as?: string;
+        url?: string;
+        config?: Record<string, string>;
+        registry?: string;
+      },
+      ctx: ToolContext,
+    ) => {
+      const fs = getStore(ctx);
+      const currentConfig = await readConfig(fs);
+
+      const entry: RefEntry = {
+        ref: input.ref,
+        ...(input.as && { as: input.as }),
+        ...(input.url && { url: input.url }),
+        ...(input.config && { config: input.config }),
+        ...(input.registry && { registry: input.registry }),
+      };
+
+      // Upsert: find existing ref by name/alias, replace or append
+      const name = input.as ?? input.ref;
+      const refs = currentConfig.refs ?? [];
+      const existingIdx = refs.findIndex((r) => {
+        const normalized = normalizeRef(r);
+        return normalized.name === name;
+      });
+
+      if (existingIdx >= 0) {
+        refs[existingIdx] = entry;
+      } else {
+        refs.push(entry);
+      }
+
+      currentConfig.refs = refs;
+      await writeConfig(fs, currentConfig);
+
+      return {
+        added: true,
+        ref: input.ref,
+        name,
+      };
+    },
+  });
+
+  // ---- remove_ref ----
+  const removeRefTool = defineTool({
+    name: "remove_ref",
+    description: "Remove an agent ref from the consumer config by name or alias.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        name: {
+          type: "string",
+          description: "Ref name or alias to remove",
+        },
+      },
+      required: ["name"],
+    },
+    execute: async (
+      input: { name: string },
+      ctx: ToolContext,
+    ) => {
+      const fs = getStore(ctx);
+      const currentConfig = await readConfig(fs);
+      const refs = currentConfig.refs ?? [];
+
+      const before = refs.length;
+      currentConfig.refs = refs.filter((r) => {
+        const normalized = normalizeRef(r);
+        return normalized.name !== input.name;
+      });
+
+      if (currentConfig.refs.length === before) {
+        return { removed: false, error: `Ref "${input.name}" not found` };
+      }
+
+      await writeConfig(fs, currentConfig);
+      return { removed: true, name: input.name };
+    },
+  });
+
+  // ---- list_refs ----
+  const listRefsTool = defineTool({
+    name: "list_refs",
+    description:
+      "List all agent refs in the consumer config. " +
+      "Returns normalized refs with their names and config.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {},
+    },
+    execute: async (_input: unknown, ctx: ToolContext) => {
+      const fs = getStore(ctx);
+      const currentConfig = await readConfig(fs);
+      const refs = (currentConfig.refs ?? []).map(normalizeRef);
+      return { refs };
+    },
+  });
+
+  // ---- add_registry ----
+  const addRegistryTool = defineTool({
+    name: "add_registry",
+    description:
+      "Add or update a registry in the consumer config. " +
+      "Registries are where refs resolve from.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        name: {
+          type: "string",
+          description: 'Human-readable name (e.g. "slash", "internal")',
+        },
+        url: {
+          type: "string",
+          description: "Registry URL",
+        },
+        auth: {
+          type: "object",
+          description: "Auth config for the registry",
+          properties: {
+            type: {
+              type: "string",
+              enum: ["none", "bearer", "api-key", "jwt"],
+            },
+          },
+        },
+      },
+      required: ["url"],
+    },
+    execute: async (
+      input: {
+        name?: string;
+        url: string;
+        auth?: { type: string; [key: string]: unknown };
+      },
+      ctx: ToolContext,
+    ) => {
+      const fs = getStore(ctx);
+      const currentConfig = await readConfig(fs);
+
+      const registries = currentConfig.registries ?? [];
+      const entry = {
+        url: input.url,
+        ...(input.name && { name: input.name }),
+        ...(input.auth && { auth: input.auth as any }),
+      };
+
+      // Upsert by URL
+      const existingIdx = registries.findIndex((r) => {
+        const url = typeof r === "string" ? r : r.url;
+        return url === input.url;
+      });
+
+      if (existingIdx >= 0) {
+        registries[existingIdx] = entry;
+      } else {
+        registries.push(entry);
+      }
+
+      currentConfig.registries = registries;
+      await writeConfig(fs, currentConfig);
+
+      return {
+        added: true,
+        url: input.url,
+        name: input.name ?? new URL(input.url).hostname,
+      };
+    },
+  });
+
+  // ---- Define the agent ----
+  return defineAgent({
+    path: "@config",
+    entrypoint:
+      "Consumer config management. Use add_ref/remove_ref/list_refs to manage agent refs, " +
+      "and add_registry to configure registries.",
+    config: {
+      name: "Config",
+      description:
+        "Manage consumer config — add/remove/list agent refs and registries. " +
+        "Replaces @integrations for connecting to third-party services.",
+    },
+    tools: [addRefTool, removeRefTool, listRefsTool, addRegistryTool] as any,
+  });
+}

package/src/codegen.ts

@@ -31,6 +31,7 @@
 import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import type { JsonSchema } from "./types.js";
+import { discoverOAuthMetadata, type OAuthServerMetadata } from "./mcp-client.js";
 
 // ============================================
 // Types
@@ -108,6 +109,9 @@ export interface CodegenResult {
 
   /** All generated file paths */
   files: string[];
+
+  /** OAuth server metadata (if discovered via .well-known/oauth-authorization-server) */
+  oauth?: OAuthServerMetadata;
 }
 
 // ============================================
@@ -614,6 +618,23 @@ function createSseTransport(source: {
 // Source Parsing
 // ============================================
 
+/**
+ * Extract the base URL from a server source (for OAuth discovery).
+ * Returns null for stdio/command-based sources.
+ */
+function resolveServerUrl(source: ServerSource): string | null {
+  if (typeof source === "string") {
+    if (source.startsWith("http://") || source.startsWith("https://")) {
+      return source.replace(/\/sse$/, "");
+    }
+    return null;
+  }
+  if ("url" in source) {
+    return source.url.replace(/\/sse$/, "");
+  }
+  return null;
+}
+
 function parseServerSource(source: ServerSource): McpTransport {
   if (typeof source === "string") {
     // URL -> HTTP or SSE transport
@@ -1113,6 +1134,7 @@ export interface CodegenManifest {
   serverSource: ServerSource;
   serverInfo: McpServerInfo;
   tools: { name: string; description?: string }[];
+  oauth?: OAuthServerMetadata;
   generatedAt: string;
 }
 
@@ -1121,12 +1143,14 @@ function generateManifest(
   serverInfo: McpServerInfo,
   tools: McpToolDefinition[],
   agentPath: string,
+  oauth?: OAuthServerMetadata | null,
 ): string {
   const manifest: CodegenManifest = {
     agentPath,
     serverSource,
     serverInfo,
     tools: tools.map((t) => ({ name: t.name, description: t.description })),
+    ...(oauth ? { oauth } : {}),
     generatedAt: new Date().toISOString(),
   };
   return JSON.stringify(manifest, null, 2) + "\n";
@@ -1204,6 +1228,13 @@ export async function codegen(options: CodegenOptions): Promise<CodegenResult> {
     );
   }
 
+  // 3.5. Discover OAuth metadata (for URL-based servers)
+  let oauth: OAuthServerMetadata | null = null;
+  const serverUrl = resolveServerUrl(options.server);
+  if (serverUrl) {
+    oauth = await discoverOAuthMetadata(serverUrl);
+  }
+
   // 4. Derive agent path
   const agentPath =
     options.agentPath ??
@@ -1253,7 +1284,7 @@ export async function codegen(options: CodegenOptions): Promise<CodegenResult> {
   }
 
   // 11. Generate manifest (for `agents-sdk use`)
-  const manifest = generateManifest(options.server, serverInfo, tools, agentPath);
+  const manifest = generateManifest(options.server, serverInfo, tools, agentPath, oauth);
   writeFileSync(join(outDir, ".codegen-manifest.json"), manifest);
   files.push(".codegen-manifest.json");
 
@@ -1263,6 +1294,7 @@ export async function codegen(options: CodegenOptions): Promise<CodegenResult> {
     toolCount: tools.length,
     toolFiles,
     files,
+    ...(oauth ? { oauth } : {}),
   };
 }
 

package/src/index.ts

@@ -211,7 +211,8 @@ export type {
 
 // Postgres Secret Store
 
-// Integrations
+// Integrations (DEPRECATED — use createConfigAgent + refs instead)
+/** @deprecated Use createConfigAgent instead */
 export {
   createIntegrationsAgent,
   createInMemoryIntegrationStore,
@@ -280,7 +281,11 @@ export type {
   ResolvedConfig,
 } from "./define-config.js";
 
-export { createRegistryConsumer } from "./registry-consumer.js";
+export {
+  createRegistryConsumer,
+  REGISTRY_TYPE_MCP,
+  REGISTRY_TYPE_HTTPS,
+} from "./registry-consumer.js";
 export type {
   RegistryConsumer,
   RegistryConsumerOptions,
@@ -289,6 +294,25 @@ export type {
   SecretResolver,
 } from "./registry-consumer.js";
 
+// PKCE
+export {
+  generateCodeVerifier,
+  generateCodeChallenge,
+  generatePkcePair,
+} from "./pkce.js";
+
+// MCP Client Auth (OAuth utilities for connecting to MCP servers/registries)
+export {
+  discoverOAuthMetadata,
+  dynamicClientRegistration,
+  buildOAuthAuthorizeUrl,
+  exchangeCodeForTokens,
+  refreshAccessToken as refreshMcpAccessToken,
+} from "./mcp-client.js";
+export type {
+  OAuthServerMetadata,
+} from "./mcp-client.js";
+
 // Codegen
 export { codegen, useAgent, listAgentTools } from "./codegen.js";
 export type {
@@ -375,8 +399,16 @@ export type { ValidationResult } from "./validate.js";
 export {
   createBM25Index,
 } from "./bm25.js";
+
 export type {
   BM25Options,
   BM25Document,
   BM25Result,
 } from "./bm25.js";
+
+// Config Agent
+export { createConfigAgent } from "./agent-definitions/config.js";
+export type {
+  ConfigAgentOptions,
+  FsStore,
+} from "./agent-definitions/config.js";

package/src/mcp-client.ts

@@ -0,0 +1,230 @@
+/**
+ * MCP Client Auth — OAuth utilities for connecting to MCP servers.
+ *
+ * Standalone utilities for:
+ * - OAuth Authorization Server discovery (.well-known/oauth-authorization-server, RFC 8414)
+ * - Dynamic client registration (RFC 7591)
+ * - PKCE OAuth authorization URL construction
+ * - Authorization code → token exchange (with PKCE)
+ * - Token refresh
+ *
+ * These are used by registry-consumer.ts when connecting to MCP servers
+ * or registries that require OAuth. The MCP transport itself is handled
+ * by registry-consumer — this module only provides auth primitives.
+ */
+
+import { generatePkcePair } from "./pkce.js";
+
+// ============================================
+// Types
+// ============================================
+
+/** OAuth Authorization Server Metadata (RFC 8414) */
+export interface OAuthServerMetadata {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  registration_endpoint?: string;
+  scopes_supported?: string[];
+  response_types_supported?: string[];
+  grant_types_supported?: string[];
+  code_challenge_methods_supported?: string[];
+  token_endpoint_auth_methods_supported?: string[];
+}
+
+// ============================================
+// OAuth Discovery
+// ============================================
+
+/**
+ * Discover OAuth authorization server metadata.
+ * Probes .well-known/oauth-authorization-server (RFC 8414).
+ * Returns null if the server doesn't support OAuth.
+ */
+export async function discoverOAuthMetadata(
+  serverUrl: string,
+  fetchFn: typeof globalThis.fetch = globalThis.fetch,
+): Promise<OAuthServerMetadata | null> {
+  const url = `${serverUrl.replace(/\/$/, "")}/.well-known/oauth-authorization-server`;
+  try {
+    const res = await fetchFn(url);
+    if (!res.ok) return null;
+    return (await res.json()) as OAuthServerMetadata;
+  } catch {
+    return null;
+  }
+}
+
+// ============================================
+// Dynamic Client Registration
+// ============================================
+
+/**
+ * Dynamically register a client with an OAuth server.
+ * RFC 7591 — used when the MCP server supports dynamic registration.
+ */
+export async function dynamicClientRegistration(
+  registrationEndpoint: string,
+  params: {
+    clientName: string;
+    redirectUris?: string[];
+    grantTypes?: string[];
+    tokenEndpointAuthMethod?: string;
+  },
+  fetchFn: typeof globalThis.fetch = globalThis.fetch,
+): Promise<{ clientId: string; clientSecret?: string }> {
+  const res = await fetchFn(registrationEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_name: params.clientName,
+      redirect_uris: params.redirectUris,
+      grant_types: params.grantTypes ?? ["authorization_code"],
+      token_endpoint_auth_method:
+        params.tokenEndpointAuthMethod ?? "none",
+    }),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "unknown");
+    throw new Error(
+      `Dynamic client registration failed: ${res.status} ${text}`,
+    );
+  }
+  const data = (await res.json()) as Record<string, unknown>;
+  return {
+    clientId: data.client_id as string,
+    clientSecret: data.client_secret as string | undefined,
+  };
+}
+
+// ============================================
+// Authorization URL
+// ============================================
+
+/**
+ * Build an OAuth authorization URL with PKCE.
+ * Returns the URL + the code_verifier (to be stored server-side).
+ */
+export async function buildOAuthAuthorizeUrl(params: {
+  authorizationEndpoint: string;
+  clientId: string;
+  redirectUri: string;
+  scopes?: string[];
+  state?: string;
+}): Promise<{
+  url: string;
+  codeVerifier: string;
+}> {
+  const pkce = await generatePkcePair();
+  const url = new URL(params.authorizationEndpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", params.clientId);
+  url.searchParams.set("redirect_uri", params.redirectUri);
+  url.searchParams.set("code_challenge", pkce.codeChallenge);
+  url.searchParams.set("code_challenge_method", pkce.codeChallengeMethod);
+  if (params.scopes?.length) {
+    url.searchParams.set("scope", params.scopes.join(" "));
+  }
+  if (params.state) {
+    url.searchParams.set("state", params.state);
+  }
+  return { url: url.toString(), codeVerifier: pkce.codeVerifier };
+}
+
+// ============================================
+// Token Exchange
+// ============================================
+
+/**
+ * Exchange an authorization code for tokens (with PKCE).
+ */
+export async function exchangeCodeForTokens(
+  tokenEndpoint: string,
+  params: {
+    code: string;
+    codeVerifier: string;
+    clientId: string;
+    clientSecret?: string;
+    redirectUri: string;
+  },
+  fetchFn: typeof globalThis.fetch = globalThis.fetch,
+): Promise<{
+  accessToken: string;
+  refreshToken?: string;
+  expiresIn?: number;
+  tokenType?: string;
+}> {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: params.code,
+    code_verifier: params.codeVerifier,
+    client_id: params.clientId,
+    redirect_uri: params.redirectUri,
+  });
+  if (params.clientSecret) {
+    body.set("client_secret", params.clientSecret);
+  }
+
+  const res = await fetchFn(tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "unknown");
+    throw new Error(`Token exchange failed: ${res.status} ${text}`);
+  }
+  const data = (await res.json()) as Record<string, unknown>;
+  return {
+    accessToken: data.access_token as string,
+    refreshToken: data.refresh_token as string | undefined,
+    expiresIn: data.expires_in as number | undefined,
+    tokenType: data.token_type as string | undefined,
+  };
+}
+
+// ============================================
+// Token Refresh
+// ============================================
+
+/**
+ * Refresh an access token.
+ */
+export async function refreshAccessToken(
+  tokenEndpoint: string,
+  params: {
+    refreshToken: string;
+    clientId: string;
+    clientSecret?: string;
+  },
+  fetchFn: typeof globalThis.fetch = globalThis.fetch,
+): Promise<{
+  accessToken: string;
+  refreshToken?: string;
+  expiresIn?: number;
+}> {
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: params.refreshToken,
+    client_id: params.clientId,
+  });
+  if (params.clientSecret) {
+    body.set("client_secret", params.clientSecret);
+  }
+
+  const res = await fetchFn(tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "unknown");
+    throw new Error(`Token refresh failed: ${res.status} ${text}`);
+  }
+  const data = (await res.json()) as Record<string, unknown>;
+  return {
+    accessToken: data.access_token as string,
+    refreshToken: data.refresh_token as string | undefined,
+    expiresIn: data.expires_in as number | undefined,
+  };
+}