@slashfi/agents-sdk 0.15.0 → 0.17.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") */
@@ -163,11 +202,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;
   };
 
@@ -487,6 +526,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 +587,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[];
 }
 
 // ============================================
@@ -641,14 +692,25 @@ export interface CallAgentDescribeToolsResponse {
   tools: ToolSchema[];
 }
 
+/** A resolved agent ref with its discovered tools */
+export interface AgentRefEntry {
+  key: string;
+  path: string;
+  description: string;
+  tools: ToolSchema[];
+}
+
 /** Success response for load */
 export interface CallAgentLoadResponse {
   success: true;
   result: {
     path: string;
     entrypoint: string;
+    systemPrompt: string;
+    contextMessages: string[];
     config: AgentConfig | undefined;
     tools: ToolSchema[];
+    agentRefs: AgentRefEntry[];
   };
 }