@slashfi/agents-sdk 0.11.1 → 0.12.0

package/src/agent-definitions/users.ts

@@ -250,10 +250,30 @@ export function createUsersAgent(options: UsersAgentOptions): AgentDefinition {
         name: { type: "string", description: "Display name" },
         avatarUrl: { type: "string", description: "Avatar URL" },
         metadata: { type: "object", description: "Additional metadata" },
+        externalRef: {
+          type: "object",
+          description: "Link to a user on a remote system. Creates identity automatically.",
+          properties: {
+            issuer: { type: "string", description: "Issuer URL of the remote system" },
+            userId: { type: "string", description: "User ID on the remote system" },
+          },
+        },
       },
       required: ["tenantId"],
     },
     execute: async (input: any, __ctx: ToolContext) => {
+      // If externalRef provided, check if identity already exists
+      if (input.externalRef) {
+        const existing = await store.findIdentityByProviderUserId(
+          input.externalRef.issuer,
+          input.externalRef.userId,
+        );
+        if (existing) {
+          const user = await store.getUser(existing.userId);
+          return { success: true, user, identity: existing, alreadyLinked: true };
+        }
+      }
+
       const user = await store.createUser({
         id: input.id ?? generateId("user_"),
         tenantId: input.tenantId,
@@ -262,7 +282,21 @@ export function createUsersAgent(options: UsersAgentOptions): AgentDefinition {
         avatarUrl: input.avatarUrl,
         metadata: input.metadata,
       });
-      return { success: true, user };
+
+      // Auto-create identity link if externalRef provided
+      let identity: UserIdentity | undefined;
+      if (input.externalRef) {
+        identity = await store.createIdentity({
+          id: generateId("uid_"),
+          userId: user.id,
+          provider: input.externalRef.issuer,
+          providerUserId: input.externalRef.userId,
+          email: input.email,
+          name: input.name,
+        });
+      }
+
+      return { success: true, user, identity };
     },
   });
 

package/src/define.ts

@@ -5,10 +5,10 @@
  */
 
 import type {
+  IntegrationHooks,
   AgentConfig,
   AgentDefinition,
   AgentRuntime,
-  IntegrationMethods,
   JsonSchema,
   ToolContext,
   ToolDefinition,
@@ -115,10 +115,18 @@ export interface DefineAgentOptions<
   allowedCallers?: string[];
 
   /**
+   * Integration hooks. When provided, defineAgent auto-generates
+   * setup_integration, connect_integration, etc. as tools.
+   */
+  integration?: IntegrationHooks;
+
+  /** Lazy loader for event listeners (e.g. entrypoint.ts) */
+  loadListeners?: () => Promise<unknown>;
+
+  /**
+   * @deprecated Use `integration` instead.
    * Integration method callbacks.
-   * Implement these when this agent acts as an integration.
    */
-  integrationMethods?: IntegrationMethods;
 }
 
 /**
@@ -148,14 +156,98 @@ export interface DefineAgentOptions<
 export function defineAgent<TContext extends ToolContext = ToolContext>(
   options: DefineAgentOptions<TContext>,
 ): AgentDefinition<TContext> {
+  const tools = [...(options.tools ?? [])];
+  let config = options.config;
+
+  // Auto-generate integration tools from hooks
+  if (options.integration) {
+    const h = options.integration;
+
+    // Set config.integration metadata if not already set
+    if (!config?.integration) {
+      config = {
+        ...config,
+        integration: {
+          provider: h.provider,
+          displayName: h.displayName,
+          icon: h.icon,
+          category: h.category,
+          description: h.description,
+        },
+      };
+    }
+
+    if (h.setup) {
+      const fn = h.setup;
+      tools.push(defineTool({
+        name: "setup_integration",
+        description: `Set up ${h.displayName} integration.`,
+        visibility: "public" as const,
+        inputSchema: { type: "object" as const, properties: { url: { type: "string" }, name: { type: "string" }, config: { type: "object" } } },
+        execute: (input: any, ctx: any) => fn(input, ctx),
+      }) as any);
+    }
+    if (h.connect) {
+      const fn = h.connect;
+      tools.push(defineTool({
+        name: "connect_integration",
+        description: `Connect a user to ${h.displayName}.`,
+        visibility: "public" as const,
+        inputSchema: { type: "object" as const, properties: { registryId: { type: "string" }, oidcUserId: { type: "string" }, redirectUri: { type: "string" } }, required: ["registryId"] as const },
+        execute: (input: any, ctx: any) => fn(input, ctx),
+      }) as any);
+    }
+    if (h.discover) {
+      const fn = h.discover;
+      tools.push(defineTool({
+        name: "discover_integrations",
+        description: `Discover available ${h.displayName} instances.`,
+        visibility: "public" as const,
+        inputSchema: { type: "object" as const, properties: { url: { type: "string" } } },
+        execute: (input: any, ctx: any) => fn(input, ctx),
+      }) as any);
+    }
+    if (h.list) {
+      const fn = h.list;
+      tools.push(defineTool({
+        name: "list_integrations",
+        description: `List connected ${h.displayName} instances.`,
+        visibility: "public" as const,
+        inputSchema: { type: "object" as const, properties: {} },
+        execute: (input: any, ctx: any) => fn(input, ctx),
+      }) as any);
+    }
+    if (h.get) {
+      const fn = h.get;
+      tools.push(defineTool({
+        name: "get_integration",
+        description: `Get details of a ${h.displayName} instance.`,
+        visibility: "public" as const,
+        inputSchema: { type: "object" as const, properties: { registryId: { type: "string" } }, required: ["registryId"] as const },
+        execute: (input: any, ctx: any) => fn(input, ctx),
+      }) as any);
+    }
+    if (h.update) {
+      const fn = h.update;
+      tools.push(defineTool({
+        name: "update_integration",
+        description: `Update a ${h.displayName} instance.`,
+        visibility: "public" as const,
+        inputSchema: { type: "object" as const, properties: { registryId: { type: "string" }, name: { type: "string" }, url: { type: "string" } }, required: ["registryId"] as const },
+        execute: (input: any, ctx: any) => fn(input, ctx),
+      }) as any);
+    }
+  }
+
+
   return {
     path: options.path,
     entrypoint: options.entrypoint,
-    config: options.config,
-    tools: options.tools ?? [],
+    config,
+    tools,
     runtime: options.runtime,
     visibility: options.visibility,
     allowedCallers: options.allowedCallers,
-    integrationMethods: options.integrationMethods,
+    loadListeners: options.loadListeners,
   };
 }

package/src/index.ts

@@ -85,6 +85,7 @@ export type {
   IntegrationMethods,
   IntegrationMethodResult,
   IntegrationMethodContext,
+  IntegrationHooks,
   Visibility,
 } from "./types.js";
 
@@ -98,7 +99,7 @@ export type { AgentRegistry, AgentRegistryOptions } from "./registry.js";
 
 // Server
 export { createAgentServer, detectAuth, resolveAuth, canSeeAgent } from "./server.js";
-export type { AgentServer, AgentServerOptions, AuthConfig, ResolvedAuth, TrustedIssuer } from "./server.js";
+export type { AgentServer, AgentServerOptions, AuthConfig, OAuthIdentityProvider, ResolvedAuth, TrustedIssuer } from "./server.js";
 
 // Secret Collection
 export {

package/src/jwt.ts

@@ -80,7 +80,7 @@ export interface ExportedKeyPair {
  * Generate a new ES256 signing key pair.
  */
 export async function generateSigningKey(kid?: string): Promise<SigningKey> {
-  const { privateKey, publicKey } = await generateKeyPair("ES256");
+  const { privateKey, publicKey } = await generateKeyPair("ES256", { extractable: true });
   return {
     kid: kid ?? `key-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
     privateKey,

package/src/server.test.ts

@@ -0,0 +1,284 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import {
+  createAgentServer,
+  createAgentRegistry,
+  detectAuth,
+  resolveAuth,
+  canSeeAgent,
+} from './index';
+import type { AgentDefinition, TrustedIssuer, AgentServer } from './index';
+import { generateKeyPair, exportJWK, SignJWT } from 'jose';
+
+// ─── Helpers ─────────────────────────────────────────────────────
+
+function makeAgent(
+  path: string,
+  opts: Partial<AgentDefinition> = {},
+): AgentDefinition {
+  return {
+    path,
+    entrypoint: 'test',
+    tools: [],
+    visibility: 'internal',
+    config: { name: path.split('/').pop(), supportedActions: ['load'] },
+    ...opts,
+  } as AgentDefinition;
+}
+
+async function mcpCall(
+  port: number,
+  toolName: string,
+  args: Record<string, unknown>,
+  authToken?: string,
+) {
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (authToken) headers.Authorization = `Bearer ${authToken}`;
+
+  const res = await fetch(`http://localhost:${port}`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: Date.now(),
+      method: 'tools/call',
+      params: { name: toolName, arguments: args },
+    }),
+  });
+  return res.json() as Promise<any>;
+}
+
+function parseResult(rpc: any): any {
+  const text = rpc.result?.content?.[0]?.text;
+  return text ? JSON.parse(text) : null;
+}
+
+// ─── E2E: Full server auth flow ──────────────────────────────────
+//
+// These tests spin up a real createAgentServer, send actual HTTP
+// requests, and verify the complete path:
+//   HTTP request → auth resolution → handleToolCall → registry.call → access check
+//
+// This is what actually broke today: authConfig was null → resolveAuth
+// was skipped → trusted issuer tokens were ignored.
+
+describe('E2E: createAgentServer with trusted issuers', () => {
+  let privateKey: CryptoKey;
+  let publicJwk: any;
+  let jwksHttpServer: ReturnType<typeof Bun.serve>;
+  let server: AgentServer;
+  const JWKS_PORT = 19880;
+  const SDK_PORT = 19881;
+  const ISSUER_URL = `http://localhost:${JWKS_PORT}`;
+  const KID = 'test-e2e-key';
+
+  beforeAll(async () => {
+    // 1. Generate ES256 keypair and serve JWKS
+    const keyPair = await generateKeyPair('ES256', { extractable: true });
+    privateKey = keyPair.privateKey;
+    publicJwk = await exportJWK(keyPair.publicKey);
+    publicJwk.kid = KID;
+    publicJwk.alg = 'ES256';
+    publicJwk.use = 'sig';
+
+    jwksHttpServer = Bun.serve({
+      port: JWKS_PORT,
+      fetch(req) {
+        const url = new URL(req.url);
+        if (url.pathname === '/.well-known/jwks.json') {
+          return new Response(JSON.stringify({ keys: [publicJwk] }), {
+            headers: { 'Content-Type': 'application/json' },
+          });
+        }
+        return new Response('Not found', { status: 404 });
+      },
+    });
+
+    // 2. Create registry with internal + public agents
+    const registry = createAgentRegistry();
+    registry.register(makeAgent('/agents/@clock', { visibility: 'internal' }));
+    registry.register(makeAgent('/agents/public-bot', { visibility: 'public' }));
+
+    // 3. Create server with trusted issuer — NO @auth agent registered
+    //    This is the exact scenario that was broken.
+    server = createAgentServer(registry, {
+      port: SDK_PORT,
+      trustedIssuers: [{
+        issuer: ISSUER_URL,
+        scopes: ['agents:admin'],
+      }],
+    });
+    await server.start();
+  });
+
+  afterAll(() => {
+    server?.stop?.();
+    jwksHttpServer?.stop();
+  });
+
+  async function signToken(claims: Record<string, unknown> = {}): Promise<string> {
+    return new SignJWT({ sub: 'atlas-api', ...claims } as any)
+      .setProtectedHeader({ alg: 'ES256', kid: KID })
+      .setIssuer(ISSUER_URL)
+      .setIssuedAt()
+      .setExpirationTime('5m')
+      .sign(privateKey);
+  }
+
+  // ─── Core auth flow tests ───────────────────────────────────
+
+  test('system token → can load internal agent', async () => {
+    const token = await signToken();
+    const rpc = await mcpCall(SDK_PORT, 'call_agent', {
+      request: { action: 'load', path: '/agents/@clock' },
+    }, token);
+
+    const result = parseResult(rpc);
+    expect(result.success).toBe(true);
+  });
+
+  test('no token → access denied for internal agent', async () => {
+    const rpc = await mcpCall(SDK_PORT, 'call_agent', {
+      request: { action: 'load', path: '/agents/@clock' },
+    });
+
+    const result = parseResult(rpc);
+    expect(result.success).toBe(false);
+    expect(result.code).toBe('ACCESS_DENIED');
+  });
+
+  test('no token → public agent still accessible', async () => {
+    const rpc = await mcpCall(SDK_PORT, 'call_agent', {
+      request: { action: 'load', path: '/agents/public-bot' },
+    });
+
+    const result = parseResult(rpc);
+    expect(result.success).toBe(true);
+  });
+
+  test('garbage token → access denied', async () => {
+    const rpc = await mcpCall(SDK_PORT, 'call_agent', {
+      request: { action: 'load', path: '/agents/@clock' },
+    }, 'not.a.valid.jwt');
+
+    const result = parseResult(rpc);
+    expect(result.success).toBe(false);
+    expect(result.code).toBe('ACCESS_DENIED');
+  });
+
+  test('token with wrong issuer → access denied', async () => {
+    // Sign with correct key but wrong iss claim
+    const token = await new SignJWT({ sub: 'evil' } as any)
+      .setProtectedHeader({ alg: 'ES256', kid: KID })
+      .setIssuer('http://evil:9999') // not in trustedIssuers
+      .setIssuedAt()
+      .setExpirationTime('5m')
+      .sign(privateKey);
+
+    const rpc = await mcpCall(SDK_PORT, 'call_agent', {
+      request: { action: 'load', path: '/agents/@clock' },
+    }, token);
+
+    const result = parseResult(rpc);
+    expect(result.success).toBe(false);
+    expect(result.code).toBe('ACCESS_DENIED');
+  });
+
+  // ─── Visibility in list_agents ─────────────────────────────
+
+  test('list_agents without token → only public agents', async () => {
+    const rpc = await mcpCall(SDK_PORT, 'list_agents', {});
+    const result = parseResult(rpc);
+    expect(result.success).toBe(true);
+
+    const paths = result.agents.map((a: any) => a.path);
+    expect(paths).toContain('/agents/public-bot');
+    expect(paths).not.toContain('/agents/@clock');
+  });
+
+  test('list_agents with system token → all agents visible', async () => {
+    const token = await signToken();
+    const rpc = await mcpCall(SDK_PORT, 'list_agents', {}, token);
+    const result = parseResult(rpc);
+    expect(result.success).toBe(true);
+
+    const paths = result.agents.map((a: any) => a.path);
+    expect(paths).toContain('/agents/public-bot');
+    expect(paths).toContain('/agents/@clock');
+  });
+
+  // ─── Scopes: limited issuer ────────────────────────────────
+
+  test('issuer with limited scopes → resolves as agent, not system', async () => {
+    // Create a separate server with limited-scope issuer
+    const limitedRegistry = createAgentRegistry();
+    limitedRegistry.register(makeAgent('/agents/@private-agent', { visibility: 'private' }));
+    limitedRegistry.register(makeAgent('/agents/@internal-agent', { visibility: 'internal' }));
+
+    const limitedServer = createAgentServer(limitedRegistry, {
+      port: 19882,
+      trustedIssuers: [{
+        issuer: ISSUER_URL,
+        scopes: ['agents:read'], // NOT agents:admin or *
+      }],
+    });
+    await limitedServer.start();
+
+    try {
+      const token = await signToken();
+
+      // agents:read grants agent-level access (not system)
+      // Internal agents are accessible to authenticated agents
+      const internalRpc = await mcpCall(19882, 'call_agent', {
+        request: { action: 'load', path: '/agents/@internal-agent' },
+      }, token);
+      expect(parseResult(internalRpc).success).toBe(true);
+
+      // Private agents should be denied (only self can access)
+      const privateRpc = await mcpCall(19882, 'call_agent', {
+        request: { action: 'load', path: '/agents/@private-agent' },
+      }, token);
+      expect(parseResult(privateRpc).success).toBe(false);
+      expect(parseResult(privateRpc).code).toBe('ACCESS_DENIED');
+    } finally {
+      limitedServer?.stop?.();
+    }
+  });
+});
+
+// ─── Unit: detectAuth ────────────────────────────────────────────
+
+describe('detectAuth', () => {
+  test('returns non-null even without @auth agent', () => {
+    const registry = createAgentRegistry();
+    const config = detectAuth(registry);
+    expect(config).toBeDefined();
+    expect(config).not.toBeNull();
+  });
+
+  test('returns empty config (no store, no rootKey) without @auth agent', () => {
+    const registry = createAgentRegistry();
+    const config = detectAuth(registry);
+    expect(config.store).toBeUndefined();
+    expect(config.rootKey).toBeUndefined();
+  });
+});
+
+// ─── Unit: canSeeAgent ───────────────────────────────────────────
+
+describe('canSeeAgent', () => {
+  test('system auth can see internal agents', () => {
+    const agent = makeAgent('/agents/@clock', { visibility: 'internal' });
+    const auth = { callerId: 'api', callerType: 'system' as const, scopes: ['*'], isRoot: true };
+    expect(canSeeAgent(agent, auth)).toBe(true);
+  });
+
+  test('null auth cannot see internal agents', () => {
+    const agent = makeAgent('/agents/@clock', { visibility: 'internal' });
+    expect(canSeeAgent(agent, null)).toBe(false);
+  });
+
+  test('null auth can see public agents', () => {
+    const agent = makeAgent('/agents/public', { visibility: 'public' });
+    expect(canSeeAgent(agent, null)).toBe(true);
+  });
+});