@slashfi/agents-sdk 0.16.0 → 0.18.0

package/src/test-utils/mock-oidc-server.ts

@@ -0,0 +1,123 @@
+/**
+ * Mock OIDC Provider for testing.
+ *
+ * A minimal OpenID Connect provider that runs locally.
+ * Supports the authorization code flow with no user interaction.
+ *
+ * Usage:
+ *   const server = await startMockOIDC({ port: 0 });
+ *   // server.url = 'http://localhost:XXXXX'
+ *   // server.issuer = server.url
+ *   // Configure your app to use server.url as the OIDC provider
+ *   await server.stop();
+ */
+
+const TEST_USER = {
+  sub: "test-user-001",
+  email: "test@example.com",
+  name: "Test User",
+  picture: "https://example.com/avatar.png",
+  "https://slack.com/team_id": "T_TEST",
+  "https://slack.com/team_name": "Test Workspace",
+};
+
+const TEST_CLIENT_ID = "test-client-id";
+const TEST_CLIENT_SECRET = "test-client-secret";
+const VALID_CODE = "test-auth-code-12345";
+const ACCESS_TOKEN = `test-access-token-${Date.now()}`;
+
+export interface MockOIDCServer {
+  url: string;
+  port: number;
+  issuer: string;
+  clientId: string;
+  clientSecret: string;
+  testUser: typeof TEST_USER;
+  accessToken: string;
+  stop: () => Promise<void>;
+}
+
+export async function startMockOIDC(
+  opts: { port?: number } = {},
+): Promise<MockOIDCServer> {
+  const server: ReturnType<typeof Bun.serve> = Bun.serve({
+    port: opts.port ?? 0,
+    fetch(req): Response | Promise<Response> {
+      const url = new URL(req.url);
+
+      // Discovery
+      if (url.pathname === "/.well-known/openid-configuration") {
+        const base: string = `http://localhost:${server.port}`;
+        return Response.json({
+          issuer: base,
+          authorization_endpoint: `${base}/authorize`,
+          token_endpoint: `${base}/token`,
+          userinfo_endpoint: `${base}/userinfo`,
+          jwks_uri: `${base}/jwks`,
+          response_types_supported: ["code"],
+          subject_types_supported: ["public"],
+          id_token_signing_alg_values_supported: ["RS256"],
+          scopes_supported: ["openid", "email", "profile"],
+        });
+      }
+
+      // Authorize - immediately redirect back with code
+      if (url.pathname === "/authorize") {
+        const redirectUri = url.searchParams.get("redirect_uri")!;
+        const state = url.searchParams.get("state") ?? "";
+        const sep = redirectUri.includes("?") ? "&" : "?";
+        return Response.redirect(
+          `${redirectUri}${sep}code=${VALID_CODE}&state=${state}`,
+          302,
+        );
+      }
+
+      // Token exchange
+      if (url.pathname === "/token" && req.method === "POST") {
+        return Response.json({
+          access_token: ACCESS_TOKEN,
+          token_type: "bearer",
+          expires_in: 3600,
+          scope: "openid email profile",
+          id_token: "fake.id.token",
+        });
+      }
+
+      // UserInfo
+      if (url.pathname === "/userinfo") {
+        const auth = req.headers.get("authorization");
+        if (auth !== `Bearer ${ACCESS_TOKEN}`) {
+          return new Response("Unauthorized", { status: 401 });
+        }
+        return Response.json({ ok: true, ...TEST_USER });
+      }
+
+      // Also support Slack-style openid.connect.userInfo
+      if (url.pathname === "/api/openid.connect.userInfo") {
+        return Response.json({ ok: true, ...TEST_USER });
+      }
+
+      // JWKS (empty - we don't validate JWTs in tests)
+      if (url.pathname === "/jwks") {
+        return Response.json({ keys: [] });
+      }
+
+      return new Response("Not found", { status: 404 });
+    },
+  });
+
+  const base = `http://localhost:${server.port}`;
+
+  return {
+    url: base,
+    port: server.port as number,
+    issuer: base,
+    clientId: TEST_CLIENT_ID,
+    clientSecret: TEST_CLIENT_SECRET,
+    testUser: TEST_USER,
+    accessToken: ACCESS_TOKEN,
+    stop: async () => {
+      server.stop();
+    },
+  };
+}

package/src/types.ts

@@ -4,6 +4,15 @@
  * Defines the fundamental types for agent definitions, tools, and contexts.
  */
 
+import type { EventCallback, EventType } from "./events.js";
+
+/** Internal listener entry stored on agents/tools */
+export interface ListenerEntry {
+  eventType: EventType;
+  callback: EventCallback<EventType>;
+  toolScope?: string;
+}
+
 // ============================================
 // JSON Schema
 // ============================================
@@ -28,7 +37,6 @@ export type JsonSchema = {
   [key: string]: unknown;
 };
 
-
 // ============================================
 // Integration Config
 // ============================================
@@ -67,19 +75,32 @@ export interface IntegrationMethodContext extends ToolContext {
  */
 export interface IntegrationMethods {
   /** Configure/initialize the integration (e.g., add a DB connection, set API key) */
-  setup(params: Record<string, unknown>, ctx: IntegrationMethodContext): Promise<IntegrationMethodResult>;
+  setup(
+    params: Record<string, unknown>,
+    ctx: IntegrationMethodContext,
+  ): Promise<IntegrationMethodResult>;
   /** List configured instances (e.g., list DB connections, list repos) */
-  list(params: Record<string, unknown>, ctx: IntegrationMethodContext): Promise<IntegrationMethodResult>;
+  list(
+    params: Record<string, unknown>,
+    ctx: IntegrationMethodContext,
+  ): Promise<IntegrationMethodResult>;
   /** Establish connection or authenticate (e.g., test DB connectivity, OAuth flow) */
-  connect(params: Record<string, unknown>, ctx: IntegrationMethodContext): Promise<IntegrationMethodResult>;
+  connect(
+    params: Record<string, unknown>,
+    ctx: IntegrationMethodContext,
+  ): Promise<IntegrationMethodResult>;
   /** Get details of a specific instance */
-  get(params: Record<string, unknown>, ctx: IntegrationMethodContext): Promise<IntegrationMethodResult>;
+  get(
+    params: Record<string, unknown>,
+    ctx: IntegrationMethodContext,
+  ): Promise<IntegrationMethodResult>;
   /** Modify an existing configuration */
-  update(params: Record<string, unknown>, ctx: IntegrationMethodContext): Promise<IntegrationMethodResult>;
+  update(
+    params: Record<string, unknown>,
+    ctx: IntegrationMethodContext,
+  ): Promise<IntegrationMethodResult>;
 }
 
-
-
 /** Hooks for agents that implement the integrations interface. */
 export interface IntegrationHooks {
   /** Provider metadata */
@@ -90,17 +111,35 @@ export interface IntegrationHooks {
   description?: string;
 
   /** Set up this integration (discover, configure, establish trust) */
-  setup?(params: Record<string, unknown>, ctx: ToolContext): Promise<IntegrationMethodResult>;
+  setup?(
+    params: Record<string, unknown>,
+    ctx: ToolContext,
+  ): Promise<IntegrationMethodResult>;
   /** Connect a user to this integration (OAuth, identity linking) */
-  connect?(params: Record<string, unknown>, ctx: ToolContext): Promise<IntegrationMethodResult>;
+  connect?(
+    params: Record<string, unknown>,
+    ctx: ToolContext,
+  ): Promise<IntegrationMethodResult>;
   /** Discover available instances of this integration */
-  discover?(params: Record<string, unknown>, ctx: ToolContext): Promise<IntegrationMethodResult>;
+  discover?(
+    params: Record<string, unknown>,
+    ctx: ToolContext,
+  ): Promise<IntegrationMethodResult>;
   /** List connected instances */
-  list?(params: Record<string, unknown>, ctx: ToolContext): Promise<IntegrationMethodResult>;
+  list?(
+    params: Record<string, unknown>,
+    ctx: ToolContext,
+  ): Promise<IntegrationMethodResult>;
   /** Get details of a specific instance */
-  get?(params: Record<string, unknown>, ctx: ToolContext): Promise<IntegrationMethodResult>;
+  get?(
+    params: Record<string, unknown>,
+    ctx: ToolContext,
+  ): Promise<IntegrationMethodResult>;
   /** Update an existing instance config */
-  update?(params: Record<string, unknown>, ctx: ToolContext): Promise<IntegrationMethodResult>;
+  update?(
+    params: Record<string, unknown>,
+    ctx: ToolContext,
+  ): Promise<IntegrationMethodResult>;
 }
 export interface IntegrationConfig {
   /** Provider identifier (e.g., "databases", "slack", "github") */
@@ -125,6 +164,100 @@ export interface IntegrationConfig {
   connectSchema?: Record<string, unknown>;
 }
 
+// ============================================
+// Security Scheme
+// ============================================
+
+/**
+ * OAuth 2.0 Authorization Code flow configuration.
+ * Used by agents that wrap APIs requiring user-authorized access
+ * (e.g. Notion, Slack, GitHub, Linear, Google).
+ */
+export interface OAuth2SecurityScheme {
+  type: "oauth2";
+  flows: {
+    authorizationCode: {
+      /** URL to redirect users for authorization */
+      authorizationUrl: string;
+      /** URL to exchange authorization code for tokens */
+      tokenUrl: string;
+      /** URL for token refresh (defaults to tokenUrl) */
+      refreshUrl?: string;
+      /** Available scopes: key = scope name, value = description */
+      scopes?: Record<string, string>;
+      /** How client credentials are sent */
+      clientAuth?: "client_secret_post" | "client_secret_basic";
+    };
+  };
+}
+
+/**
+ * API key authentication.
+ * Used by agents that wrap APIs using a single key
+ * (e.g. OpenAI, Anthropic, Stripe, Datadog).
+ */
+export interface ApiKeySecurityScheme {
+  type: "apiKey";
+  /** Where the key is sent */
+  in: "header" | "query";
+  /** Header or query parameter name (e.g. "X-API-Key", "Authorization") */
+  name: string;
+  /** Optional prefix (e.g. "Bearer" for Authorization header) */
+  prefix?: string;
+}
+
+/**
+ * HTTP authentication (Bearer token, Basic auth).
+ */
+export interface HttpSecurityScheme {
+  type: "http";
+  scheme: "bearer" | "basic";
+}
+
+/**
+ * No authentication required.
+ */
+export interface NoneSecurityScheme {
+  type: "none";
+}
+
+/**
+ * Security scheme for an agent — describes what authentication the
+ * agent's target API requires from consumers.
+ *
+ * Borrowed from OpenAPI Security Scheme Object, simplified for agents.
+ * The system uses this to:
+ * - Know what credentials a tenant admin needs to provide (OAuth app creds)
+ * - Know what flow a user needs to complete (OAuth exchange)
+ * - Know how to send credentials when calling the API
+ *
+ * @example
+ * ```typescript
+ * // OAuth 2.0 (Notion, Slack, GitHub)
+ * security: {
+ *   type: 'oauth2',
+ *   flows: {
+ *     authorizationCode: {
+ *       authorizationUrl: 'https://api.notion.com/v1/oauth/authorize',
+ *       tokenUrl: 'https://api.notion.com/v1/oauth/token',
+ *       clientAuth: 'client_secret_basic',
+ *     }
+ *   }
+ * }
+ *
+ * // API Key (OpenAI, Stripe)
+ * security: { type: 'apiKey', in: 'header', name: 'Authorization', prefix: 'Bearer' }
+ *
+ * // No auth (public API)
+ * security: { type: 'none' }
+ * ```
+ */
+export type SecurityScheme =
+  | OAuth2SecurityScheme
+  | ApiKeySecurityScheme
+  | HttpSecurityScheme
+  | NoneSecurityScheme;
+
 // ============================================
 // Agent Configuration
 // ============================================
@@ -163,11 +296,11 @@ export interface AgentConfig {
   modelParams?: {
     maxTokens?: number;
     temperature?: number;
-  /** Agent refs (paths to other agents this agent can call) */
-  refs?: Record<string, { description?: string }>;
+    /** Agent refs (paths to other agents this agent can call) */
+    refs?: Record<string, { description?: string }>;
 
-  /** Tools to expose publicly (by name) */
-  public?: { tools?: string[] };
+    /** Tools to expose publicly (by name) */
+    public?: { tools?: string[] };
     [key: string]: unknown;
   };
 
@@ -178,6 +311,15 @@ export interface AgentConfig {
    */
   integration?: IntegrationConfig;
 
+  /**
+   * Security scheme — describes what authentication the agent's
+   * target API requires. Used by the registry to communicate
+   * credential requirements to consumers.
+   *
+   * @see SecurityScheme
+   */
+  security?: SecurityScheme;
+
   /** Additional configuration */
   /** Agent refs (paths to other agents this agent can call) */
   refs?: Record<string, { description?: string }>;
@@ -487,6 +629,12 @@ export interface ToolDefinition<
    * When set, rendered directly into the agent's system prompt.
    */
   doc?: string;
+
+  /**
+   * Internal: event listeners registered via tool.on().
+   * Collected by the registry on registration.
+   */
+  _listeners?: ListenerEntry[];
 }
 
 /**
@@ -542,6 +690,12 @@ export interface AgentDefinition<TContext extends ToolContext = ToolContext> {
    * Called once to load runtime hooks exported from the agent's entrypoint module.
    */
   loadListeners?: () => Promise<unknown>;
+
+  /**
+   * Internal: event listeners registered via agent.on().
+   * Collected by the registry on registration.
+   */
+  _listeners?: ListenerEntry[];
 }
 
 // ============================================