@slashfi/agents-sdk 0.4.0 → 0.6.0

package/src/agent-definitions/users.ts

@@ -0,0 +1,533 @@
+/**
+ * Users Agent (@users)
+ *
+ * Built-in agent for user and user identity management.
+ * Provides user CRUD and identity linking (OAuth providers, SSO, etc.).
+ *
+ * A User is a human entity. A UserIdentity links a user to an external
+ * identity provider (e.g. Google, Slack, GitHub) — one user can have
+ * many identities.
+ *
+ * @example
+ * ```typescript
+ * import { createAgentRegistry, createUsersAgent } from '@slashfi/agents-sdk';
+ *
+ * const registry = createAgentRegistry();
+ * registry.register(createUsersAgent({
+ *   store: myUserStore,
+ * }));
+ * ```
+ */
+
+import { defineAgent, defineTool } from "../define.js";
+import type { AgentDefinition, ToolContext, ToolDefinition } from "../types.js";
+
+// ============================================
+// User Types
+// ============================================
+
+export interface User {
+  id: string;
+  tenantId: string;
+  email?: string;
+  name?: string;
+  avatarUrl?: string;
+  metadata?: Record<string, unknown>;
+  createdAt: number;
+  updatedAt: number;
+}
+
+/**
+ * A link between a User and an external identity provider.
+ * One user can have many identities (e.g. Google + Slack + GitHub).
+ */
+export interface UserIdentity {
+  id: string;
+  userId: string;
+  provider: string;
+  /** External provider's user ID */
+  providerUserId: string;
+  /** Display info from the provider */
+  email?: string;
+  name?: string;
+  avatarUrl?: string;
+  /** OAuth tokens (encrypted at rest in the store) */
+  accessToken?: string;
+  refreshToken?: string;
+  expiresAt?: number;
+  tokenType?: string;
+  scopes?: string[];
+  metadata?: Record<string, unknown>;
+  connectedAt: number;
+  updatedAt: number;
+}
+
+// ============================================
+// User Store Interface
+// ============================================
+
+/**
+ * Pluggable storage backend for users and identities.
+ */
+export interface UserStore {
+  // Users
+  createUser(user: Omit<User, "createdAt" | "updatedAt">): Promise<User>;
+  getUser(userId: string): Promise<User | null>;
+  getUserByEmail(tenantId: string, email: string): Promise<User | null>;
+  listUsers(tenantId: string): Promise<User[]>;
+  updateUser(
+    userId: string,
+    updates: Partial<Pick<User, "email" | "name" | "avatarUrl" | "metadata">>,
+  ): Promise<User | null>;
+  deleteUser(userId: string): Promise<boolean>;
+
+  // Identities
+  createIdentity(
+    identity: Omit<UserIdentity, "connectedAt" | "updatedAt">,
+  ): Promise<UserIdentity>;
+  getIdentity(identityId: string): Promise<UserIdentity | null>;
+  getIdentityByProvider(
+    userId: string,
+    provider: string,
+  ): Promise<UserIdentity | null>;
+  findIdentityByProviderUserId(
+    provider: string,
+    providerUserId: string,
+  ): Promise<UserIdentity | null>;
+  listIdentities(userId: string): Promise<UserIdentity[]>;
+  updateIdentity(
+    identityId: string,
+    updates: Partial<
+      Pick<
+        UserIdentity,
+        | "accessToken"
+        | "refreshToken"
+        | "expiresAt"
+        | "email"
+        | "name"
+        | "avatarUrl"
+        | "metadata"
+      >
+    >,
+  ): Promise<UserIdentity | null>;
+  deleteIdentity(identityId: string): Promise<boolean>;
+}
+
+// ============================================
+// In-Memory User Store
+// ============================================
+
+function generateId(prefix: string): string {
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let id = prefix;
+  for (let i = 0; i < 20; i++) {
+    id += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return id;
+}
+
+export function createInMemoryUserStore(): UserStore {
+  const users = new Map<string, User>();
+  const identities = new Map<string, UserIdentity>();
+
+  return {
+    async createUser(input) {
+      const now = Date.now();
+      const user: User = { ...input, createdAt: now, updatedAt: now };
+      users.set(user.id, user);
+      return user;
+    },
+
+    async getUser(userId) {
+      return users.get(userId) ?? null;
+    },
+
+    async getUserByEmail(tenantId, email) {
+      for (const u of users.values()) {
+        if (u.tenantId === tenantId && u.email === email) return u;
+      }
+      return null;
+    },
+
+    async listUsers(tenantId) {
+      return Array.from(users.values()).filter((u) => u.tenantId === tenantId);
+    },
+
+    async updateUser(userId, updates) {
+      const user = users.get(userId);
+      if (!user) return null;
+      const updated = { ...user, ...updates, updatedAt: Date.now() };
+      users.set(userId, updated);
+      return updated;
+    },
+
+    async deleteUser(userId) {
+      // Delete identities too
+      for (const [id, identity] of identities) {
+        if (identity.userId === userId) identities.delete(id);
+      }
+      return users.delete(userId);
+    },
+
+    async createIdentity(input) {
+      const now = Date.now();
+      const identity: UserIdentity = {
+        ...input,
+        connectedAt: now,
+        updatedAt: now,
+      };
+      identities.set(identity.id, identity);
+      return identity;
+    },
+
+    async getIdentity(identityId) {
+      return identities.get(identityId) ?? null;
+    },
+
+    async getIdentityByProvider(userId, provider) {
+      for (const identity of identities.values()) {
+        if (identity.userId === userId && identity.provider === provider)
+          return identity;
+      }
+      return null;
+    },
+
+    async findIdentityByProviderUserId(provider, providerUserId) {
+      for (const identity of identities.values()) {
+        if (
+          identity.provider === provider &&
+          identity.providerUserId === providerUserId
+        )
+          return identity;
+      }
+      return null;
+    },
+
+    async listIdentities(userId) {
+      return Array.from(identities.values()).filter((i) => i.userId === userId);
+    },
+
+    async updateIdentity(identityId, updates) {
+      const identity = identities.get(identityId);
+      if (!identity) return null;
+      const updated = { ...identity, ...updates, updatedAt: Date.now() };
+      identities.set(identityId, updated);
+      return updated;
+    },
+
+    async deleteIdentity(identityId) {
+      return identities.delete(identityId);
+    },
+  };
+}
+
+// ============================================
+// Create Users Agent
+// ============================================
+
+export interface UsersAgentOptions {
+  /** User store backend */
+  store: UserStore;
+}
+
+export function createUsersAgent(options: UsersAgentOptions): AgentDefinition {
+  const { store } = options;
+
+  // ---- create_user ----
+  const createUserTool = defineTool({
+    name: "create_user",
+    description: "Create a new user.",
+    visibility: "public" as const,
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        id: {
+          type: "string",
+          description: "User ID (optional, auto-generated if omitted)",
+        },
+        tenantId: { type: "string", description: "Tenant ID" },
+        email: { type: "string", description: "Email address" },
+        name: { type: "string", description: "Display name" },
+        avatarUrl: { type: "string", description: "Avatar URL" },
+        metadata: { type: "object", description: "Additional metadata" },
+      },
+      required: ["tenantId"],
+    },
+    execute: async (input: any, __ctx: ToolContext) => {
+      const user = await store.createUser({
+        id: input.id ?? generateId("user_"),
+        tenantId: input.tenantId,
+        email: input.email,
+        name: input.name,
+        avatarUrl: input.avatarUrl,
+        metadata: input.metadata,
+      });
+      return { success: true, user };
+    },
+  });
+
+  // ---- get_user ----
+  const getUserTool = defineTool({
+    name: "get_user",
+    description: "Get a user by ID.",
+    visibility: "public" as const,
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        userId: { type: "string", description: "User ID" },
+      },
+      required: ["userId"],
+    },
+    execute: async (input: { userId: string }, __ctx: ToolContext) => {
+      const user = await store.getUser(input.userId);
+      if (!user) return { error: `User '${input.userId}' not found` };
+      return { user };
+    },
+  });
+
+  // ---- list_users ----
+  const listUsersTool = defineTool({
+    name: "list_users",
+    description: "List users in a tenant.",
+    visibility: "public" as const,
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        tenantId: { type: "string", description: "Tenant ID" },
+      },
+      required: ["tenantId"],
+    },
+    execute: async (input: { tenantId: string }, __ctx: ToolContext) => {
+      const users = await store.listUsers(input.tenantId);
+      return { users };
+    },
+  });
+
+  // ---- update_user ----
+  const updateUserTool = defineTool({
+    name: "update_user",
+    description: "Update a user's profile.",
+    visibility: "public" as const,
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        userId: { type: "string", description: "User ID" },
+        email: { type: "string", description: "New email" },
+        name: { type: "string", description: "New name" },
+        avatarUrl: { type: "string", description: "New avatar URL" },
+        metadata: { type: "object", description: "New metadata (merged)" },
+      },
+      required: ["userId"],
+    },
+    execute: async (input: any, __ctx: ToolContext) => {
+      const { userId, ...updates } = input;
+      const user = await store.updateUser(userId, updates);
+      if (!user) return { error: `User '${userId}' not found` };
+      return { success: true, user };
+    },
+  });
+
+  // ---- link_identity ----
+  const linkIdentityTool = defineTool({
+    name: "link_identity",
+    description:
+      "Link an external identity (OAuth provider) to a user. " +
+      "Creates a UserIdentity record associating the user with a provider account.",
+    visibility: "public" as const,
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        userId: { type: "string", description: "User ID to link to" },
+        provider: {
+          type: "string",
+          description: "Provider name (e.g. 'google', 'slack', 'github')",
+        },
+        providerUserId: {
+          type: "string",
+          description: "The user's ID in the external provider",
+        },
+        email: { type: "string", description: "Email from the provider" },
+        name: { type: "string", description: "Name from the provider" },
+        avatarUrl: {
+          type: "string",
+          description: "Avatar URL from the provider",
+        },
+        accessToken: { type: "string", description: "OAuth access token" },
+        refreshToken: { type: "string", description: "OAuth refresh token" },
+        expiresAt: {
+          type: "number",
+          description: "Token expiry timestamp (ms)",
+        },
+        scopes: {
+          type: "array",
+          items: { type: "string" },
+          description: "Granted scopes",
+        },
+        metadata: {
+          type: "object",
+          description: "Additional provider-specific data",
+        },
+      },
+      required: ["userId", "provider", "providerUserId"],
+    },
+    execute: async (input: any, __ctx: ToolContext) => {
+      // Check if identity already exists
+      const existing = await store.getIdentityByProvider(
+        input.userId,
+        input.provider,
+      );
+      if (existing) {
+        // Update existing
+        const updated = await store.updateIdentity(existing.id, {
+          accessToken: input.accessToken,
+          refreshToken: input.refreshToken,
+          expiresAt: input.expiresAt,
+          email: input.email,
+          name: input.name,
+          avatarUrl: input.avatarUrl,
+          metadata: input.metadata,
+        });
+        return { success: true, identity: updated, updated: true };
+      }
+
+      const identity = await store.createIdentity({
+        id: generateId("ident_"),
+        userId: input.userId,
+        provider: input.provider,
+        providerUserId: input.providerUserId,
+        email: input.email,
+        name: input.name,
+        avatarUrl: input.avatarUrl,
+        accessToken: input.accessToken,
+        refreshToken: input.refreshToken,
+        expiresAt: input.expiresAt,
+        tokenType: input.tokenType,
+        scopes: input.scopes,
+        metadata: input.metadata,
+      });
+      return { success: true, identity, created: true };
+    },
+  });
+
+  // ---- list_identities ----
+  const listIdentitiesTool = defineTool({
+    name: "list_identities",
+    description: "List all linked identities for a user.",
+    visibility: "public" as const,
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        userId: { type: "string", description: "User ID" },
+      },
+      required: ["userId"],
+    },
+    execute: async (input: { userId: string }, __ctx: ToolContext) => {
+      const identities = await store.listIdentities(input.userId);
+      return {
+        identities: identities.map((i) => ({
+          id: i.id,
+          provider: i.provider,
+          providerUserId: i.providerUserId,
+          email: i.email,
+          name: i.name,
+          connectedAt: i.connectedAt,
+          hasAccessToken: !!i.accessToken,
+          expiresAt: i.expiresAt,
+        })),
+      };
+    },
+  });
+
+  // ---- unlink_identity ----
+  const unlinkIdentityTool = defineTool({
+    name: "unlink_identity",
+    description: "Remove a linked identity from a user.",
+    visibility: "public" as const,
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        identityId: { type: "string", description: "Identity ID to unlink" },
+      },
+      required: ["identityId"],
+    },
+    execute: async (input: { identityId: string }, __ctx: ToolContext) => {
+      const deleted = await store.deleteIdentity(input.identityId);
+      return { success: deleted };
+    },
+  });
+
+  // ---- resolve_identity ----
+  const resolveIdentityTool = defineTool({
+    name: "resolve_identity",
+    description:
+      "Find a user by their external provider identity. " +
+      "Useful for login flows — given a provider + providerUserId, find the linked user.",
+    visibility: "public" as const,
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        provider: {
+          type: "string",
+          description: "Provider name (e.g. 'google')",
+        },
+        providerUserId: {
+          type: "string",
+          description: "External user ID from the provider",
+        },
+      },
+      required: ["provider", "providerUserId"],
+    },
+    execute: async (
+      input: { provider: string; providerUserId: string },
+      __ctx: ToolContext,
+    ) => {
+      const identity = await store.findIdentityByProviderUserId(
+        input.provider,
+        input.providerUserId,
+      );
+      if (!identity) return { found: false };
+
+      const user = await store.getUser(identity.userId);
+      return {
+        found: true,
+        user: user
+          ? {
+              id: user.id,
+              email: user.email,
+              name: user.name,
+              tenantId: user.tenantId,
+            }
+          : null,
+        identity: {
+          id: identity.id,
+          provider: identity.provider,
+          providerUserId: identity.providerUserId,
+          email: identity.email,
+        },
+      };
+    },
+  });
+
+  return defineAgent({
+    path: "@users",
+    entrypoint:
+      "You are the users agent. You manage user accounts and their linked external identities " +
+      "(OAuth providers like Google, Slack, GitHub, etc.).",
+    config: {
+      name: "Users",
+      description: "User and identity management",
+      supportedActions: ["execute_tool", "describe_tools", "load"],
+    },
+    visibility: "public",
+    tools: [
+      createUserTool,
+      getUserTool,
+      listUsersTool,
+      updateUserTool,
+      linkIdentityTool,
+      listIdentitiesTool,
+      unlinkIdentityTool,
+      resolveIdentityTool,
+    ] as ToolDefinition[],
+  });
+}

package/src/crypto.ts

@@ -0,0 +1,71 @@
+/**
+ * AES-256-GCM encryption utilities for the agents SDK.
+ * Uses Web Crypto API - no external dependencies.
+ */
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+async function deriveKey(secret: string): Promise<CryptoKey> {
+  const keyMaterial = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    "PBKDF2",
+    false,
+    ["deriveKey"],
+  );
+  return crypto.subtle.deriveKey(
+    {
+      name: "PBKDF2",
+      salt: encoder.encode("agents-sdk-secrets-v1"),
+      iterations: 100000,
+      hash: "SHA-256",
+    },
+    keyMaterial,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+/**
+ * Encrypt a string with AES-256-GCM.
+ * Returns a base64-encoded string containing IV + ciphertext.
+ */
+export async function encryptSecret(
+  plaintext: string,
+  encryptionKey: string,
+): Promise<string> {
+  const key = await deriveKey(encryptionKey);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv },
+    key,
+    encoder.encode(plaintext),
+  );
+  const combined = new Uint8Array(
+    iv.length + new Uint8Array(ciphertext).length,
+  );
+  combined.set(iv);
+  combined.set(new Uint8Array(ciphertext), iv.length);
+  return btoa(String.fromCharCode(...combined));
+}
+
+/**
+ * Decrypt a string encrypted with encryptSecret.
+ */
+export async function decryptSecret(
+  encrypted: string,
+  encryptionKey: string,
+): Promise<string> {
+  const key = await deriveKey(encryptionKey);
+  const combined = Uint8Array.from(atob(encrypted), (c) => c.charCodeAt(0));
+  const iv = combined.slice(0, 12);
+  const ciphertext = combined.slice(12);
+  const plaintext = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv },
+    key,
+    ciphertext,
+  );
+  return decoder.decode(plaintext);
+}

package/src/define.ts

@@ -8,6 +8,7 @@ import type {
   AgentConfig,
   AgentDefinition,
   AgentRuntime,
+  IntegrationMethods,
   JsonSchema,
   ToolContext,
   ToolDefinition,
@@ -112,6 +113,12 @@ export interface DefineAgentOptions<
 
   /** Explicit allowed callers */
   allowedCallers?: string[];
+
+  /**
+   * Integration method callbacks.
+   * Implement these when this agent acts as an integration.
+   */
+  integrationMethods?: IntegrationMethods;
 }
 
 /**
@@ -149,5 +156,6 @@ export function defineAgent<TContext extends ToolContext = ToolContext>(
     runtime: options.runtime,
     visibility: options.visibility,
     allowedCallers: options.allowedCallers,
+    integrationMethods: options.integrationMethods,
   };
 }