@slashfi/agents-sdk 0.15.0 → 0.17.0

package/src/registry.ts

@@ -4,13 +4,22 @@
  * Manages registered agents and handles callAgent requests.
  */
 
+import { dirname, resolve } from "node:path";
+import type {
+  AgentEvent,
+  EventCallback,
+  EventType,
+} from "./events.js";
+import { createEventBus } from "./events.js";
 import type {
   AgentAction,
   AgentDefinition,
+  AgentRefEntry,
   CallAgentDescribeToolsResponse,
   CallAgentErrorResponse,
   CallAgentExecuteToolResponse,
   CallAgentLearnResponse,
+  CallAgentLoadRequest,
   CallAgentLoadResponse,
   CallAgentRequest,
   CallAgentResponse,
@@ -31,6 +40,25 @@ const DEFAULT_SUPPORTED_ACTIONS: AgentAction[] = [
 // Agent Registry Interface
 // ============================================
 
+/**
+ * Middleware hooks for registry lifecycle actions.
+ * Each hook receives the default handler fn and context,
+ * giving full control: call default, skip it, try/catch, or enhance.
+ */
+export interface RegistryMiddleware {
+  load?: (
+    defaultFn: (
+      agent: AgentDefinition,
+      request: CallAgentLoadRequest,
+    ) => Promise<CallAgentLoadResponse>,
+    ctx: {
+      agent: AgentDefinition;
+      request: CallAgentLoadRequest;
+      registry: AgentRegistry;
+    },
+  ) => Promise<CallAgentLoadResponse>;
+}
+
 /**
  * Options for creating an agent registry.
  */
@@ -39,6 +67,8 @@ export interface AgentRegistryOptions {
   defaultVisibility?: Visibility;
   /** Factory to enrich ToolContext with application-specific data */
   contextFactory?: ContextFactory;
+  /** Lifecycle middleware hooks */
+  middleware?: RegistryMiddleware;
 }
 
 /**
@@ -62,6 +92,12 @@ export interface AgentRegistry {
 
   /** Call an agent (execute action) */
   call(request: CallAgentRequest): Promise<CallAgentResponse>;
+
+  /** Register an event listener (global scope — fires for all agents) */
+  on<T extends EventType>(eventType: T, callback: EventCallback<T>): void;
+
+  /** Emit an event to all listeners. Used by the runtime to push lifecycle events. */
+  emit(event: AgentEvent): Promise<void>;
 }
 
 // ============================================
@@ -88,13 +124,16 @@ export interface AgentRegistry {
  * Factory function that enriches the base ToolContext with application-specific data.
  * Called before every tool execution.
  */
-export type ContextFactory = (baseCtx: import("./types.js").ToolContext) => import("./types.js").ToolContext;
+export type ContextFactory = (
+  baseCtx: import("./types.js").ToolContext,
+) => import("./types.js").ToolContext;
 
 export function createAgentRegistry(
   options: AgentRegistryOptions = {},
 ): AgentRegistry {
   const { defaultVisibility = "internal" } = options;
   const agents = new Map<string, AgentDefinition>();
+  const eventBus = createEventBus();
 
   /**
    * Check if agent supports the requested action.
@@ -182,9 +221,143 @@ export function createAgentRegistry(
     }
   }
 
+  function resolveRefPath(currentPath: string, ref: string): string {
+    if (ref.startsWith("@") && !ref.includes("/")) {
+      return `/agents/${ref}`;
+    }
+    if (ref.startsWith("../") || ref.startsWith("./")) {
+      const dir = dirname(currentPath);
+      return resolve(dir, ref);
+    }
+    if (ref.startsWith("/")) {
+      return ref;
+    }
+    return `/agents/${ref}`;
+  }
+
+  function buildToolsSection(
+    ownTools: ToolSchema[],
+    agentRefs: AgentRefEntry[],
+  ): string {
+    const hasOwnTools = ownTools.length > 0;
+    const hasRefTools = agentRefs.some((ref) => ref.tools.length > 0);
+    if (!hasOwnTools && !hasRefTools) return "";
+
+    const lines: string[] = ["\n\n## Available Tools\n"];
+
+    if (hasOwnTools) {
+      lines.push("| Tool | Description |", "|------|-------------|");
+      for (const t of ownTools) {
+        lines.push(`| ${t.name} | ${t.description} |`);
+      }
+      lines.push("");
+    }
+
+    for (const ref of agentRefs) {
+      if (ref.tools.length > 0) {
+        lines.push(`### From ${ref.key} (${ref.path})\n`);
+        lines.push("| Tool | Description |", "|------|-------------|");
+        for (const t of ref.tools) {
+          lines.push(`| ${t.name} | ${t.description} |`);
+        }
+        lines.push("");
+      }
+    }
+
+    return lines.join("\n");
+  }
+
+  async function defaultLoad(
+    agent: AgentDefinition,
+    request: CallAgentLoadRequest,
+  ): Promise<CallAgentLoadResponse> {
+    const toolSchemas: ToolSchema[] = agent.tools
+      .filter((t: ToolDefinition) =>
+        checkToolAccess(agent, t.name, request.callerId, request.callerType),
+      )
+      .map((t: ToolDefinition) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+        ...(t.outputSchema && { outputSchema: t.outputSchema }),
+      }));
+
+    const agentRefs: AgentRefEntry[] = [];
+    const refs = agent.config?.refs;
+    if (refs) {
+      for (const [key, refConfig] of Object.entries(refs)) {
+        const refPath = resolveRefPath(agent.path, key);
+        const refAgent = agents.get(refPath);
+        const allTools = (refAgent?.tools ?? [])
+          .filter((t: ToolDefinition) =>
+            checkToolAccess(
+              refAgent!,
+              t.name,
+              request.callerId,
+              request.callerType,
+            ),
+          )
+          .map((t: ToolDefinition) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+            ...(t.outputSchema && { outputSchema: t.outputSchema }),
+          }));
+        const publicFilter = refAgent?.config?.public?.tools;
+        const tools = publicFilter
+          ? allTools.filter((t) => publicFilter.includes(t.name))
+          : allTools;
+        agentRefs.push({
+          key,
+          path: refPath,
+          description: refConfig.description ?? key,
+          tools,
+        });
+      }
+    }
+
+    const systemPrompt =
+      agent.entrypoint + buildToolsSection(toolSchemas, agentRefs);
+
+    return {
+      success: true,
+      result: {
+        path: agent.path,
+        entrypoint: agent.entrypoint,
+        systemPrompt,
+        contextMessages: [],
+        config: agent.config,
+        tools: toolSchemas,
+        agentRefs,
+      },
+    };
+  }
+
   const registry: AgentRegistry = {
     register(agent: AgentDefinition): void {
       agents.set(agent.path, agent);
+
+      // Collect agent-level listeners into the bus
+      if (agent._listeners) {
+        for (const entry of agent._listeners) {
+          eventBus._onScoped(entry.eventType, entry.callback, {
+            agentPath: agent.path,
+            toolName: entry.toolScope,
+          });
+        }
+      }
+
+      // Collect tool-level listeners into the bus
+      for (const tool of agent.tools) {
+        if (tool._listeners) {
+          for (const entry of tool._listeners) {
+            eventBus._onScoped(entry.eventType, entry.callback, {
+              agentPath: agent.path,
+              toolName: tool.name,
+            });
+          }
+        }
+      }
     },
 
     get(path: string): AgentDefinition | undefined {
@@ -203,6 +376,14 @@ export function createAgentRegistry(
       return Array.from(agents.keys());
     },
 
+    on<T extends EventType>(eventType: T, callback: EventCallback<T>): void {
+      eventBus.on(eventType, callback);
+    },
+
+    async emit(event: AgentEvent): Promise<void> {
+      await eventBus.emit(event);
+    },
+
     async call(request: CallAgentRequest): Promise<CallAgentResponse> {
       const agent = agents.get(request.path);
 
@@ -311,15 +492,59 @@ export function createAgentRegistry(
                 error: `Tool ${request.tool} has no execute function`,
               } as CallAgentErrorResponse;
             }
-            const result = await tool.execute(request.params, ctx);
+
+            // Emit tool/call before execution
+            const startMs = Date.now();
+            await eventBus.emit({
+              type: "tool/call",
+              agentPath: agent.path,
+              tool: request.tool!,
+              params: request.params,
+              timestamp: startMs,
+            });
+
+            let result: unknown;
+            try {
+              result = await tool.execute(request.params, ctx);
+            } catch (err) {
+              // Emit tool/error on failure
+              await eventBus.emit({
+                type: "tool/error",
+                agentPath: agent.path,
+                tool: request.tool!,
+                params: request.params,
+                error: err,
+                durationMs: Date.now() - startMs,
+                timestamp: Date.now(),
+              }).catch(() => {}); // don't let emit error mask tool error
+
+              return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+                code: "TOOL_EXECUTION_ERROR",
+              } as CallAgentErrorResponse;
+            }
+
+            // Emit tool/result after success
+            await eventBus.emit({
+              type: "tool/result",
+              agentPath: agent.path,
+              tool: request.tool!,
+              params: request.params,
+              result,
+              durationMs: Date.now() - startMs,
+              timestamp: Date.now(),
+            });
+
             return {
               success: true,
               result,
             } as CallAgentExecuteToolResponse;
-          } catch (err) {
+          } catch (outerErr) {
+            // Catch-all for unexpected errors (e.g., emit failures)
             return {
               success: false,
-              error: err instanceof Error ? err.message : String(err),
+              error: outerErr instanceof Error ? outerErr.message : String(outerErr),
               code: "TOOL_EXECUTION_ERROR",
             } as CallAgentErrorResponse;
           }
@@ -352,31 +577,14 @@ export function createAgentRegistry(
         }
 
         case "load": {
-          const toolSchemas: ToolSchema[] = agent.tools
-            .filter((t: ToolDefinition) =>
-              checkToolAccess(
-                agent,
-                t.name,
-                request.callerId,
-                request.callerType,
-              ),
-            )
-            .map((t: ToolDefinition) => ({
-              name: t.name,
-              description: t.description,
-              inputSchema: t.inputSchema,
-              ...(t.outputSchema && { outputSchema: t.outputSchema }),
-            }));
-
-          return {
-            success: true,
-            result: {
-              path: agent.path,
-              entrypoint: agent.entrypoint,
-              config: agent.config,
-              tools: toolSchemas,
-            },
-          } as CallAgentLoadResponse;
+          if (options.middleware?.load) {
+            return options.middleware.load(defaultLoad, {
+              agent,
+              request,
+              registry,
+            });
+          }
+          return defaultLoad(agent, request);
         }
 
         case "learn": {

package/src/secret-collection.ts

@@ -44,7 +44,8 @@ export const pendingCollections = new Map<string, PendingCollection>();
 
 /** Generate a random one-time token for secret collection */
 export function generateCollectionToken(): string {
-  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  const chars =
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
   let token = "";
   for (let i = 0; i < 48; i++) {
     token += chars[Math.floor(Math.random() * chars.length)];