@slashfi/agents-sdk 0.16.0 → 0.18.0

package/src/define-config.ts

@@ -0,0 +1,205 @@
+/**
+ * defineConfig — Declarative configuration for agent consumers.
+ *
+ * A consumer's config declares which registries to connect to and which
+ * agent refs to use. This is the "package.json" of the agent world:
+ * registries are like npm registries, refs are like dependencies.
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from '@slashfi/agents-sdk';
+ *
+ * export default defineConfig({
+ *   registries: [
+ *     { url: 'https://registry.slash.com' },
+ *     { url: 'https://twin.slash.com/tenants/slash', auth: { type: 'bearer' } },
+ *   ],
+ *   refs: [
+ *     'notion',
+ *     { ref: 'postgres', as: 'prod-db', config: { url: 'https://twin.slash.com/secrets/crdb-url' } },
+ *     { ref: 'postgres', as: 'staging', config: { url: 'https://twin.slash.com/secrets/staging-url' } },
+ *   ],
+ * });
+ * ```
+ */
+
+// ============================================
+// Registry Config
+// ============================================
+
+/** Authentication methods for connecting to a registry */
+export type RegistryAuth =
+  | { type: "none" }
+  | { type: "bearer"; token?: string; tokenUrl?: string }
+  | { type: "api-key"; key?: string; header?: string }
+  | { type: "jwt"; issuer?: string };
+
+/** A registry endpoint the consumer connects to */
+export interface RegistryEntry {
+  /** Registry URL (e.g., 'https://registry.slash.com') */
+  url: string;
+
+  /** How to authenticate with this registry */
+  auth?: RegistryAuth;
+
+  /** Human-readable name / alias for this registry */
+  name?: string;
+
+  /** Publisher name shown in the app store UI */
+  publisher?: string;
+}
+
+// ============================================
+// Ref Config
+// ============================================
+
+/** Inline config for a ref — values can be literals or secret URLs */
+export type RefConfig = Record<string, string | number | boolean>;
+
+/** A ref can be a simple string or a full object */
+export type RefEntry =
+  | string
+  | {
+      /** Agent definition path (resolved from registries) */
+      ref: string;
+
+      /** Direct URL to the agent (e.g. http://localhost:3000/agents/notion) */
+      url?: string;
+
+      /** Local alias for this instance (required for multi-instance) */
+      as?: string;
+
+      /** Per-instance config (secrets as URIs, literals as values) */
+      config?: RefConfig;
+
+      /** Override the registry to resolve from */
+      registry?: string;
+    };
+
+// ============================================
+// Consumer Config
+// ============================================
+
+/** The full consumer configuration */
+export interface ConsumerConfig {
+  /** Registries to connect to, in resolution order */
+  registries?: (string | RegistryEntry)[];
+
+  /** Agent refs to use — your "dependencies" */
+  refs?: RefEntry[];
+
+  /** Optional metadata */
+  meta?: {
+    /** Config owner (user ID, tenant ID, etc.) */
+    owner?: string;
+    /** Human-readable description */
+    description?: string;
+    [key: string]: unknown;
+  };
+}
+
+// ============================================
+// Resolved Config (indexed output)
+// ============================================
+
+/** A normalized registry entry (after resolution) */
+export interface ResolvedRegistry {
+  url: string;
+  name: string;
+  publisher: string;
+  auth: RegistryAuth;
+}
+
+/** A normalized ref entry (after resolution) */
+export interface ResolvedRef {
+  /** Original ref name from the definition */
+  ref: string;
+
+  /** Local name (alias or ref name) */
+  name: string;
+
+  /** Which registry this was resolved from */
+  registry: string;
+
+  /** Resolved config (secret URLs NOT resolved — kept as URLs) */
+  config: RefConfig;
+}
+
+/** The serialized/indexed output stored in VCS */
+export interface ResolvedConfig {
+  /** Timestamp of resolution */
+  resolvedAt: string;
+
+  /** Source config hash (for cache invalidation) */
+  sourceHash: string;
+
+  /** Normalized registries */
+  registries: ResolvedRegistry[];
+
+  /** Normalized refs */
+  refs: ResolvedRef[];
+
+  /** Metadata */
+  meta?: ConsumerConfig["meta"];
+}
+
+// ============================================
+// Helpers
+// ============================================
+
+/** Normalize a ref entry to its full form */
+export function normalizeRef(entry: RefEntry): {
+  ref: string;
+  name: string;
+  config: RefConfig;
+  registry?: string;
+} {
+  if (typeof entry === "string") {
+    return { ref: entry, name: entry, config: {} };
+  }
+  return {
+    ref: entry.ref,
+    name: entry.as ?? entry.ref,
+    config: entry.config ?? {},
+    registry: entry.registry,
+  };
+}
+
+/** Normalize a registry entry to its full form */
+export function normalizeRegistry(
+  entry: string | RegistryEntry,
+): ResolvedRegistry {
+  if (typeof entry === "string") {
+    const url = new URL(entry);
+    return {
+      url: entry,
+      name: url.hostname,
+      publisher: url.hostname.split(".")[0],
+      auth: { type: "none" },
+    };
+  }
+  const url = new URL(entry.url);
+  return {
+    url: entry.url,
+    name: entry.name ?? url.hostname,
+    publisher: entry.publisher ?? url.hostname.split(".")[0],
+    auth: entry.auth ?? { type: "none" },
+  };
+}
+
+/** Supported secret URI schemes */
+const SECRET_SCHEMES = ["file:", "https:", "http:", "env:"];
+
+/** Check if a value is a secret URI (file://, https://, env://) */
+export function isSecretUri(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  try {
+    const url = new URL(value);
+    return SECRET_SCHEMES.includes(url.protocol);
+  } catch {
+    return false;
+  }
+}
+
+/** @deprecated Use isSecretUri instead */
+export const isSecretUrl = isSecretUri;

package/src/define.ts

@@ -4,12 +4,14 @@
  * Factory functions for creating agent and tool definitions.
  */
 
+import type { EventCallback, EventType } from "./events.js";
 import type {
-  IntegrationHooks,
   AgentConfig,
   AgentDefinition,
   AgentRuntime,
+  IntegrationHooks,
   JsonSchema,
+  ListenerEntry,
   ToolContext,
   ToolDefinition,
   Visibility,
@@ -65,14 +67,37 @@ export interface DefineToolOptions<
  * });
  * ```
  */
+/** A ToolDefinition with .on() chaining support */
+export type ToolWithHooks<
+  TContext extends ToolContext = ToolContext,
+  TInput = unknown,
+  TOutput = unknown,
+> = ToolDefinition<TContext, TInput, TOutput> & {
+  on<T extends EventType>(
+    eventType: T,
+    callback: EventCallback<T>,
+  ): ToolWithHooks<TContext, TInput, TOutput>;
+};
+
+/** An AgentDefinition with .on() chaining support */
+export type AgentWithHooks<TContext extends ToolContext = ToolContext> =
+  AgentDefinition<TContext> & {
+    on<T extends EventType>(
+      eventType: T,
+      callback: EventCallback<T>,
+    ): AgentWithHooks<TContext>;
+  };
+
 export function defineTool<
   TContext extends ToolContext = ToolContext,
   TInput = unknown,
   TOutput = unknown,
 >(
   options: DefineToolOptions<TContext, TInput, TOutput>,
-): ToolDefinition<TContext, TInput, TOutput> {
-  return {
+): ToolWithHooks<TContext, TInput, TOutput> {
+  const listeners: ListenerEntry[] = [];
+
+  const def: ToolWithHooks<TContext, TInput, TOutput> = {
     name: options.name,
     description: options.description,
     inputSchema: options.inputSchema,
@@ -80,7 +105,17 @@ export function defineTool<
     visibility: options.visibility,
     allowedCallers: options.allowedCallers,
     execute: options.execute,
+    _listeners: listeners,
+    on<T extends EventType>(eventType: T, callback: EventCallback<T>) {
+      listeners.push({
+        eventType,
+        callback: callback as EventCallback<EventType>,
+      });
+      return def;
+    },
   };
+
+  return def;
 }
 
 // ============================================
@@ -179,68 +214,111 @@ export function defineAgent<TContext extends ToolContext = ToolContext>(
 
     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);
+      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);
+      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);
+      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);
+      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);
+      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);
+      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,
+      );
     }
   }
 
+  const agentListeners: ListenerEntry[] = [];
 
-  return {
+  const def: AgentWithHooks<TContext> = {
     path: options.path,
     entrypoint: options.entrypoint,
     config,
@@ -249,5 +327,15 @@ export function defineAgent<TContext extends ToolContext = ToolContext>(
     visibility: options.visibility,
     allowedCallers: options.allowedCallers,
     loadListeners: options.loadListeners,
+    _listeners: agentListeners,
+    on<T extends EventType>(eventType: T, callback: EventCallback<T>) {
+      agentListeners.push({
+        eventType,
+        callback: callback as EventCallback<EventType>,
+      });
+      return def;
+    },
   };
+
+  return def;
 }

package/src/events.ts

@@ -0,0 +1,237 @@
+/**
+ * Event Bus — Generic event system for the agents-sdk.
+ *
+ * Three scopes, one bus:
+ *   registry.on(event, cb)  — global, all agents
+ *   agent.on(event, cb)     — scoped to one agent
+ *   tool.on(event, cb)      — scoped to one tool
+ *
+ * All are sugar for the same underlying EventBus.
+ * Filtering happens in the callback, not the API.
+ */
+
+// =============================================================================
+// Event Types
+// =============================================================================
+
+/**
+ * All supported event types.
+ */
+export type EventType =
+  | "tool/call"
+  | "tool/result"
+  | "tool/error"
+  | "step"
+  | "invoke";
+
+/**
+ * Base event shape — every event has these fields.
+ */
+export interface BaseEvent {
+  /** Event type */
+  type: EventType;
+  /** Agent path (e.g., '/agents/atlas-slack') */
+  agentPath: string;
+  /** Timestamp */
+  timestamp: number;
+}
+
+/**
+ * Event emitted before a tool executes.
+ */
+export interface ToolCallEvent extends BaseEvent {
+  type: "tool/call";
+  /** Tool name */
+  tool: string;
+  /** Input parameters */
+  params: unknown;
+}
+
+/**
+ * Event emitted after a tool succeeds.
+ */
+export interface ToolResultEvent extends BaseEvent {
+  type: "tool/result";
+  /** Tool name */
+  tool: string;
+  /** Input parameters */
+  params: unknown;
+  /** Tool result */
+  result: unknown;
+  /** Execution duration in ms */
+  durationMs: number;
+}
+
+/**
+ * Event emitted when a tool throws.
+ */
+export interface ToolErrorEvent extends BaseEvent {
+  type: "tool/error";
+  /** Tool name */
+  tool: string;
+  /** Input parameters */
+  params: unknown;
+  /** The error */
+  error: unknown;
+  /** Execution duration in ms */
+  durationMs: number;
+}
+
+/**
+ * Event emitted when a step finishes.
+ */
+export interface StepEvent extends BaseEvent {
+  type: "step";
+  /** Branch ID */
+  branchId: string;
+  /** Step outcome */
+  stepResult: "continue" | "stop";
+  /** Tools called in this step */
+  toolNames?: string[];
+}
+
+/**
+ * Event emitted when an agent is invoked.
+ */
+export interface InvokeEvent extends BaseEvent {
+  type: "invoke";
+  /** The prompt */
+  prompt: string;
+  /** Session/branch ID */
+  sessionId?: string;
+}
+
+/**
+ * Union of all event types.
+ */
+export type AgentEvent =
+  | ToolCallEvent
+  | ToolResultEvent
+  | ToolErrorEvent
+  | StepEvent
+  | InvokeEvent;
+
+/**
+ * Map from event type string to event interface.
+ */
+export interface EventMap {
+  "tool/call": ToolCallEvent;
+  "tool/result": ToolResultEvent;
+  "tool/error": ToolErrorEvent;
+  step: StepEvent;
+  invoke: InvokeEvent;
+}
+
+/**
+ * Callback for a specific event type.
+ */
+export type EventCallback<T extends EventType = EventType> = (
+  event: EventMap[T],
+) => void | Promise<void>;
+
+// =============================================================================
+// Event Bus
+// =============================================================================
+
+/**
+ * Listener entry — callback + optional scope for agent/tool filtering.
+ */
+interface ListenerEntry {
+  eventType: EventType;
+  callback: EventCallback<EventType>;
+  /** If set, only fire for events matching this agent path */
+  agentScope?: string;
+  /** If set, only fire for tool events matching this tool name */
+  toolScope?: string;
+}
+
+export interface EventBus {
+  /**
+   * Register a listener for an event type.
+   *
+   * @example
+   * ```ts
+   * bus.on('tool/result', (event) => { ... })
+   * ```
+   */
+  on<T extends EventType>(eventType: T, callback: EventCallback<T>): void;
+
+  /**
+   * Emit an event to all matching listeners.
+   * Listeners are called in registration order.
+   * Errors in listeners are caught and logged, never propagated.
+   */
+  emit(event: AgentEvent): Promise<void>;
+
+  /**
+   * Register a scoped listener (used internally by agent.on / tool.on).
+   */
+  _onScoped<T extends EventType>(
+    eventType: T,
+    callback: EventCallback<T>,
+    scope: { agentPath?: string; toolName?: string },
+  ): void;
+}
+
+/**
+ * Create an event bus.
+ */
+export function createEventBus(): EventBus {
+  const listeners: ListenerEntry[] = [];
+
+  function on<T extends EventType>(
+    eventType: T,
+    callback: EventCallback<T>,
+  ): void {
+    listeners.push({
+      eventType,
+      callback: callback as EventCallback<EventType>,
+    });
+  }
+
+  function _onScoped<T extends EventType>(
+    eventType: T,
+    callback: EventCallback<T>,
+    scope: { agentPath?: string; toolName?: string },
+  ): void {
+    listeners.push({
+      eventType,
+      callback: callback as EventCallback<EventType>,
+      agentScope: scope.agentPath,
+      toolScope: scope.toolName,
+    });
+  }
+
+  async function emit(event: AgentEvent): Promise<void> {
+    for (const listener of listeners) {
+      // Match event type
+      if (listener.eventType !== event.type) continue;
+
+      // Match agent scope
+      if (listener.agentScope && listener.agentScope !== event.agentPath) {
+        continue;
+      }
+
+      // Match tool scope (only for tool:* events)
+      if (
+        listener.toolScope &&
+        "tool" in event &&
+        listener.toolScope !== event.tool
+      ) {
+        continue;
+      }
+
+      try {
+        await listener.callback(event);
+      } catch (err) {
+        // Never propagate listener errors — log and continue
+        console.error(
+          `[agents-sdk] Event listener error for ${event.type}:`,
+          err,
+        );
+      }
+    }
+  }
+
+  return { on, emit, _onScoped };
+}