@slashfi/agents-sdk 0.25.1 → 0.26.0

package/src/events.ts

@@ -10,26 +10,48 @@
  * Filtering happens in the callback, not the API.
  */
 
+import type { CallAgentRequest, CallAgentResponse } from "./types.js";
 // =============================================================================
 // Event Types
 // =============================================================================
 
 /**
- * All supported event types.
+ * Built-in system event types managed by the runtime.
  */
-export type EventType =
+export type SystemEventType =
   | "tool/call"
   | "tool/result"
   | "tool/error"
   | "step"
-  | "invoke";
+  | "invoke"
+  | "call";
+
+/**
+ * Augmentable map for custom event types. Consumers extend this
+ * via declaration merging to register their own events:
+ *
+ * ```ts
+ * declare module '@slashfi/agents-sdk' {
+ *   interface CustomEventMap {
+ *     'callback/resolve': MyCallbackResolveEvent;
+ *   }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface CustomEventMap {}
+
+/**
+ * All event types — system + consumer-defined custom events.
+ */
+export type EventType = SystemEventType | Extract<keyof CustomEventMap, string>;
 
 /**
  * Base event shape — every event has these fields.
  */
 export interface BaseEvent {
   /** Event type */
-  type: EventType;
+  type: string;
   /** Agent path (e.g., '/agents/atlas-slack') */
   agentPath: string;
   /** Timestamp */
@@ -102,31 +124,54 @@ export interface InvokeEvent extends BaseEvent {
 }
 
 /**
- * Union of all event types.
+ * Event emitted when a call_agent request is received.
+ * Call `resolve(response)` to short-circuit the default handler.
+ * If no listener resolves, the default call handler runs.
+ */
+export interface CallEvent extends BaseEvent {
+  type: "call";
+  /** The incoming call_agent request */
+  request: CallAgentRequest;
+  /** Run the default call handler and return its result */
+  next(): Promise<CallAgentResponse>;
+  /** Short-circuit with a response (skips default handler if next() not called) */
+  resolve(response: CallAgentResponse): void;
+}
+
+/**
+ * Union of all built-in event types.
  */
 export type AgentEvent =
   | ToolCallEvent
   | ToolResultEvent
   | ToolErrorEvent
   | StepEvent
-  | InvokeEvent;
+  | InvokeEvent
+  | CallEvent;
 
 /**
- * Map from event type string to event interface.
+ * Map from system event type string to event interface.
  */
-export interface EventMap {
+export interface SystemEventMap {
   "tool/call": ToolCallEvent;
   "tool/result": ToolResultEvent;
   "tool/error": ToolErrorEvent;
   step: StepEvent;
   invoke: InvokeEvent;
+  call: CallEvent;
 }
 
+/**
+ * Map from event type string to event interface.
+ * Combines system events with custom events.
+ */
+export interface EventMap extends SystemEventMap, CustomEventMap {}
+
 /**
  * Callback for a specific event type.
  */
 export type EventCallback<T extends EventType = EventType> = (
-  event: EventMap[T],
+  event: T extends keyof EventMap ? EventMap[T] : BaseEvent,
 ) => void | Promise<void>;
 
 // =============================================================================
@@ -136,7 +181,7 @@ export type EventCallback<T extends EventType = EventType> = (
 /**
  * Listener entry — callback + optional scope for agent/tool filtering.
  */
-interface ListenerEntry {
+export interface ListenerEntry {
   eventType: EventType;
   callback: EventCallback<EventType>;
   /** If set, only fire for events matching this agent path */
@@ -161,7 +206,7 @@ export interface EventBus {
    * Listeners are called in registration order.
    * Errors in listeners are caught and logged, never propagated.
    */
-  emit(event: AgentEvent): Promise<void>;
+  emit(event: AgentEvent | (BaseEvent & { type: string })): Promise<void>;
 
   /**
    * Register a scoped listener (used internally by agent.on / tool.on).
@@ -202,7 +247,9 @@ export function createEventBus(): EventBus {
     });
   }
 
-  async function emit(event: AgentEvent): Promise<void> {
+  async function emit(
+    event: AgentEvent | (BaseEvent & { type: string }),
+  ): Promise<void> {
     for (const listener of listeners) {
       // Match event type
       if (listener.eventType !== event.type) continue;
@@ -222,7 +269,7 @@ export function createEventBus(): EventBus {
       }
 
       try {
-        await listener.callback(event);
+        await listener.callback(event as never);
       } catch (err) {
         // Never propagate listener errors — log and continue
         console.error(

package/src/index.ts

@@ -112,14 +112,20 @@ export { createEventBus } from "./events.js";
 export type {
   EventBus,
   EventType,
+  SystemEventType,
+  CustomEventMap,
   EventCallback,
   AgentEvent,
+  BaseEvent,
   ToolCallEvent,
   ToolResultEvent,
   ToolErrorEvent,
   StepEvent,
   InvokeEvent,
+  CallEvent,
   EventMap,
+  SystemEventMap,
+  ListenerEntry,
 } from "./events.js";
 
 // Server

package/src/registry.ts

@@ -5,7 +5,7 @@
  */
 
 import { dirname, resolve } from "node:path";
-import type { AgentEvent, EventCallback, EventType } from "./events.js";
+import type { AgentEvent, BaseEvent, CustomEventMap, EventCallback, EventType } from "./events.js";
 import { createEventBus } from "./events.js";
 import type { SerializedAgentDefinition } from "./serialized.js";
 import type {
@@ -55,6 +55,7 @@ export interface RegistryMiddleware {
       registry: AgentRegistry;
     },
   ) => Promise<CallAgentLoadResponse>;
+
 }
 
 /**
@@ -97,6 +98,21 @@ export interface AgentRegistry {
 
   /** Emit an event to all listeners. Used by the runtime to push lifecycle events. */
   emit(event: AgentEvent): Promise<void>;
+
+  /**
+   * Trigger a custom event. Only accepts custom event types (not system events
+   * like tool/call, tool/result, etc. which are managed by the runtime).
+   *
+   * @example
+   * ```ts
+   * // After augmenting CustomEventMap:
+   * registry.trigger('callback/resolve', { type: 'callback/resolve', ... });
+   * ```
+   */
+  trigger<T extends Extract<keyof CustomEventMap, string>>(
+    eventType: T,
+    event: CustomEventMap[T] & BaseEvent,
+  ): Promise<void>;
 }
 
 // ============================================
@@ -412,7 +428,7 @@ export function createAgentRegistry(
     };
   }
 
-  const registry: AgentRegistry = {
+  const registryObj: AgentRegistry = {
     register(input: AgentDefinition | SerializedAgentDefinition): void {
       let agent: AgentDefinition;
       if (isSerialized(input)) {
@@ -473,7 +489,42 @@ export function createAgentRegistry(
       await eventBus.emit(event);
     },
 
+    async trigger<T extends Extract<keyof CustomEventMap, string>>(
+      _eventType: T,
+      event: CustomEventMap[T] & BaseEvent,
+    ): Promise<void> {
+      await eventBus.emit(event as never);
+    },
+
     async call(request: CallAgentRequest): Promise<CallAgentResponse> {
+      // Emit call event — listeners can next()/resolve() to control flow
+      let intercepted: CallAgentResponse | undefined;
+      let nextCalled = false;
+      let nextResult: CallAgentResponse | undefined;
+      await eventBus.emit({
+        type: "call",
+        agentPath: request.path,
+        timestamp: Date.now(),
+        request,
+        async next() {
+          nextCalled = true;
+          nextResult = await callInternal(request);
+          return nextResult;
+        },
+        resolve(response: CallAgentResponse) {
+          intercepted = response;
+        },
+      });
+      if (intercepted) return intercepted;
+      if (nextCalled) return nextResult!;
+      // No listener engaged — run default
+      return callInternal(request);
+    },
+  };
+
+  return registryObj;
+
+  async function callInternal(request: CallAgentRequest): Promise<CallAgentResponse> {
       const agent = agents.get(request.path);
 
       if (!agent) {
@@ -673,7 +724,7 @@ export function createAgentRegistry(
             return options.middleware.load(defaultLoad, {
               agent,
               request,
-              registry,
+              registry: registryObj,
             });
           }
           return defaultLoad(agent, request);
@@ -717,8 +768,5 @@ export function createAgentRegistry(
           } as CallAgentErrorResponse;
         }
       }
-    },
-  };
-
-  return registry;
-}
+    }
+  }