@slashfi/agents-sdk 0.72.0 → 0.73.0

package/src/events.ts

@@ -10,6 +10,7 @@
  * Filtering happens in the callback, not the API.
  */
 
+import { getDefaultLogger, type Logger } from "./logger.js";
 import type { AgentDefinition, CallAgentRequest, CallAgentResponse } from "./types.js";
 // =============================================================================
 // Event Types
@@ -293,11 +294,17 @@ export interface EventBus {
   ): void;
 }
 
+export interface EventBusOptions {
+  /** Logger for listener errors (default: module-level default logger) */
+  logger?: Logger;
+}
+
 /**
  * Create an event bus.
  */
-export function createEventBus(): EventBus {
+export function createEventBus(options: EventBusOptions = {}): EventBus {
   const listeners: ListenerEntry[] = [];
+  const logger = options.logger ?? getDefaultLogger();
 
   function on<T extends EventType>(
     eventType: T,
@@ -346,11 +353,14 @@ export function createEventBus(): EventBus {
       try {
         await listener.callback(event as never);
       } catch (err) {
-        // Never propagate listener errors — log and continue
-        console.error(
-          `[agents-sdk] Event listener error for ${event.type}:`,
-          err,
-        );
+        // Never propagate listener errors — log and continue.
+        // Structured fields so Datadog keeps the whole record as one event.
+        logger.error("event_listener_error", {
+          component: "agents-sdk.events",
+          event_type: event.type,
+          agent_path: event.agentPath,
+          error: err,
+        });
       }
     }
   }

package/src/fetch-types.ts

@@ -0,0 +1,13 @@
+/**
+ * Structural `fetch` type that's compatible across Node (undici-backed) and
+ * Bun (which extends the global fetch with extras like `preconnect`).
+ *
+ * Using `typeof globalThis.fetch` in options types causes type-errors when a
+ * Node-typed fetch implementation (e.g. an undici.Agent-backed wrapper) is
+ * passed in a codebase whose @types/bun is loaded. This structural subset is
+ * the minimum surface the SDK actually uses and both runtimes satisfy it.
+ */
+export type FetchFn = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;

package/src/index.ts

@@ -126,6 +126,7 @@ export type {
 export { createEventBus } from "./events.js";
 export type {
   EventBus,
+  EventBusOptions,
   EventType,
   SystemEventType,
   CustomEventMap,
@@ -145,6 +146,18 @@ export type {
   ListenerEntry,
 } from "./events.js";
 
+// Logger
+export {
+  createConsoleJsonLogger,
+  createNoopLogger,
+  getDefaultLogger,
+  setDefaultLogger,
+} from "./logger.js";
+export type { LogFields, LogLevel, Logger } from "./logger.js";
+
+// Structural fetch type
+export type { FetchFn } from "./fetch-types.js";
+
 // Server
 export {
   createAgentServer,

package/src/key-manager.ts

@@ -21,6 +21,7 @@ import {
   generateKeyPair,
   importJWK,
 } from "jose";
+import { getDefaultLogger, type Logger } from "./logger.js";
 
 // ── Types ──
 
@@ -88,6 +89,11 @@ export interface KeyManagerOptions {
   tokenTtlSeconds?: number;
   /** Enable background key rotation (default: true). Set to false on read-only replicas. */
   enableRotation?: boolean;
+  /**
+   * Structured logger for rotation errors. Defaults to the module-level
+   * default logger (single-line JSON).
+   */
+  logger?: Logger;
 }
 
 // ── Constants ──
@@ -148,6 +154,7 @@ export async function createKeyManager(
     tokenTtlSeconds = 300,
     enableRotation = true,
   } = opts;
+  const logger = opts.logger ?? getDefaultLogger();
 
   let keys: CachedKey[] = [];
 
@@ -221,7 +228,11 @@ export async function createKeyManager(
         try {
           await checkAndRotate();
         } catch (err) {
-          console.error("[key-manager] Check/rotation failed:", err);
+          logger.error("key_rotation_failed", {
+            component: "agents-sdk.key-manager",
+            issuer,
+            error: err,
+          });
         }
       }, checkIntervalMs)
     : null;

package/src/logger.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, test } from "bun:test";
+import { createEventBus } from "./events.js";
+import {
+  type Logger,
+  createConsoleJsonLogger,
+  createNoopLogger,
+  getDefaultLogger,
+  setDefaultLogger,
+} from "./logger.js";
+
+function captureLogger(): { logger: Logger; records: unknown[] } {
+  const records: unknown[] = [];
+  const logger: Logger = {
+    debug: (msg, fields) => records.push({ level: "debug", msg, fields }),
+    info: (msg, fields) => records.push({ level: "info", msg, fields }),
+    warn: (msg, fields) => records.push({ level: "warn", msg, fields }),
+    error: (msg, fields) => records.push({ level: "error", msg, fields }),
+    with: () => logger,
+  };
+  return { logger, records };
+}
+
+describe("createConsoleJsonLogger", () => {
+  test("emits single-line JSON for each record", () => {
+    const lines: string[] = [];
+    const originalError = console.error;
+    const originalLog = console.log;
+    console.error = (line: string) => lines.push(line);
+    console.log = (line: string) => lines.push(line);
+    try {
+      const logger = createConsoleJsonLogger();
+      logger.info("hello", { foo: "bar" });
+      logger.error("oops", { err: new Error("boom") });
+    } finally {
+      console.error = originalError;
+      console.log = originalLog;
+    }
+
+    expect(lines.length).toBe(2);
+    for (const line of lines) {
+      // Single line
+      expect(line.includes("\n")).toBe(false);
+      // Valid JSON
+      expect(() => JSON.parse(line)).not.toThrow();
+    }
+
+    const info = JSON.parse(lines[0]!);
+    expect(info.level).toBe("info");
+    expect(info.message).toBe("hello");
+    expect(info.foo).toBe("bar");
+    expect(typeof info.timestamp).toBe("string");
+
+    const err = JSON.parse(lines[1]!);
+    expect(err.level).toBe("error");
+    expect(err.message).toBe("oops");
+    expect(err.err.name).toBe("Error");
+    expect(err.err.message).toBe("boom");
+    expect(typeof err.err.stack).toBe("string");
+  });
+
+  test("with() merges base fields into child records", () => {
+    const lines: string[] = [];
+    const originalLog = console.log;
+    console.log = (line: string) => lines.push(line);
+    try {
+      const root = createConsoleJsonLogger({ service: "atlas-api" });
+      const child = root.with({ request_id: "abc123" });
+      child.info("req", { method: "GET" });
+    } finally {
+      console.log = originalLog;
+    }
+    expect(lines.length).toBe(1);
+    const record = JSON.parse(lines[0]!);
+    expect(record.service).toBe("atlas-api");
+    expect(record.request_id).toBe("abc123");
+    expect(record.method).toBe("GET");
+    expect(record.message).toBe("req");
+  });
+
+  test("handles non-serializable values without throwing", () => {
+    const lines: string[] = [];
+    const originalLog = console.log;
+    console.log = (line: string) => lines.push(line);
+    try {
+      const logger = createConsoleJsonLogger();
+      const circular: Record<string, unknown> = {};
+      circular.self = circular;
+      logger.info("cycle", { circular });
+    } finally {
+      console.log = originalLog;
+    }
+    expect(lines.length).toBe(1);
+    const record = JSON.parse(lines[0]!);
+    expect(record.serializer_error).toBe(true);
+    expect(record.message).toBe("cycle");
+  });
+
+  test("serializes bigint and drops functions", () => {
+    const lines: string[] = [];
+    const originalLog = console.log;
+    console.log = (line: string) => lines.push(line);
+    try {
+      const logger = createConsoleJsonLogger();
+      logger.info("values", { big: 42n, fn: () => "ignored" });
+    } finally {
+      console.log = originalLog;
+    }
+    const record = JSON.parse(lines[0]!);
+    expect(record.big).toBe("42");
+    expect(record.fn).toBeUndefined();
+  });
+});
+
+describe("createNoopLogger", () => {
+  test("drops every record and with() returns self", () => {
+    const noop = createNoopLogger();
+    expect(() => {
+      noop.debug("d");
+      noop.info("i");
+      noop.warn("w");
+      noop.error("e", { err: new Error("ignored") });
+    }).not.toThrow();
+    const child = noop.with({ ctx: "x" });
+    expect(typeof child.info).toBe("function");
+  });
+});
+
+describe("default logger", () => {
+  test("setDefaultLogger / getDefaultLogger round-trip", () => {
+    const original = getDefaultLogger();
+    const { logger, records } = captureLogger();
+    try {
+      setDefaultLogger(logger);
+      getDefaultLogger().info("routed");
+      expect(records.length).toBe(1);
+    } finally {
+      setDefaultLogger(original);
+    }
+  });
+});
+
+describe("createEventBus uses injected logger", () => {
+  test("listener error is logged as a single structured record", async () => {
+    const { logger, records } = captureLogger();
+    const bus = createEventBus({ logger });
+    bus.on("tool/call", () => {
+      throw new Error("listener boom");
+    });
+    await bus.emit({
+      type: "tool/call",
+      agentPath: "@test",
+      timestamp: Date.now(),
+      tool: "demo",
+      params: {},
+    });
+    expect(records.length).toBe(1);
+    const rec = records[0] as {
+      level: string;
+      msg: string;
+      fields: Record<string, unknown>;
+    };
+    expect(rec.level).toBe("error");
+    expect(rec.msg).toBe("event_listener_error");
+    expect(rec.fields.component).toBe("agents-sdk.events");
+    expect(rec.fields.event_type).toBe("tool/call");
+    expect(rec.fields.agent_path).toBe("@test");
+    expect(rec.fields.error).toBeInstanceOf(Error);
+  });
+
+  test("listener errors never propagate", async () => {
+    const bus = createEventBus({ logger: createNoopLogger() });
+    bus.on("invoke", () => {
+      throw new Error("nope");
+    });
+    await expect(
+      bus.emit({
+        type: "invoke",
+        agentPath: "@test",
+        timestamp: Date.now(),
+        prompt: "hi",
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  test("falls back to module default logger when no option passed", async () => {
+    const original = getDefaultLogger();
+    const { logger, records } = captureLogger();
+    try {
+      setDefaultLogger(logger);
+      const bus = createEventBus();
+      bus.on("tool/call", () => {
+        throw new Error("captured");
+      });
+      await bus.emit({
+        type: "tool/call",
+        agentPath: "@test",
+        timestamp: Date.now(),
+        tool: "demo",
+        params: {},
+      });
+      expect(records.length).toBe(1);
+    } finally {
+      setDefaultLogger(original);
+    }
+  });
+});

package/src/logger.ts

@@ -0,0 +1,123 @@
+/**
+ * Logger — pluggable structured logger for the agents-sdk.
+ *
+ * The SDK emits errors and traces via this interface so consumers (e.g. atlas)
+ * can route logs into their own observability stack. The default logger writes
+ * single-line JSON to stdout/stderr, which keeps Datadog from splitting
+ * multi-line stack traces into separate events.
+ *
+ * @example Inject your own logger
+ * ```ts
+ * const registry = createAgentRegistry({ logger: myStructuredLogger });
+ * ```
+ *
+ * @example Disable all SDK logging
+ * ```ts
+ * const registry = createAgentRegistry({ logger: createNoopLogger() });
+ * ```
+ */
+
+export type LogFields = Record<string, unknown>;
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface Logger {
+  debug(message: string, fields?: LogFields): void;
+  info(message: string, fields?: LogFields): void;
+  warn(message: string, fields?: LogFields): void;
+  error(message: string, fields?: LogFields): void;
+  /** Return a child logger that merges the given fields into every record. */
+  with(fields: LogFields): Logger;
+}
+
+/**
+ * Replacer that expands Error objects into plain JSON-serializable fields
+ * (name/message/stack/cause), and falls back to String() for other
+ * non-serializable values so the logger never throws or drops the message.
+ */
+function errorReplacer(_key: string, value: unknown): unknown {
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: value.message,
+      stack: value.stack,
+      ...(value.cause !== undefined ? { cause: value.cause } : {}),
+    };
+  }
+  if (typeof value === "bigint") return value.toString();
+  if (typeof value === "function") return undefined;
+  return value;
+}
+
+/**
+ * Default logger: emits a single JSON line per record.
+ *  - debug/info → stdout
+ *  - warn/error → stderr
+ *
+ * Kept intentionally minimal. Hosts should replace this with their own
+ * transport in production.
+ */
+export function createConsoleJsonLogger(base: LogFields = {}): Logger {
+  function emit(level: LogLevel, message: string, fields?: LogFields): void {
+    const record = {
+      level,
+      timestamp: new Date().toISOString(),
+      message,
+      ...base,
+      ...fields,
+    };
+    let line: string;
+    try {
+      line = JSON.stringify(record, errorReplacer);
+    } catch {
+      // Last-ditch fallback: if the payload can't be serialized, at least
+      // emit the message so callers aren't flying blind.
+      line = JSON.stringify({
+        level,
+        timestamp: new Date().toISOString(),
+        message,
+        serializer_error: true,
+      });
+    }
+    if (level === "error" || level === "warn") {
+      console.error(line);
+    } else {
+      console.log(line);
+    }
+  }
+  return {
+    debug: (message, fields) => emit("debug", message, fields),
+    info: (message, fields) => emit("info", message, fields),
+    warn: (message, fields) => emit("warn", message, fields),
+    error: (message, fields) => emit("error", message, fields),
+    with: (fields) => createConsoleJsonLogger({ ...base, ...fields }),
+  };
+}
+
+/** Logger that drops every record. Useful for silencing SDK output in tests. */
+export function createNoopLogger(): Logger {
+  const noop = (): void => {};
+  const self: Logger = {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    with: () => self,
+  };
+  return self;
+}
+
+/**
+ * Module-level default logger. Hosts that want JSON output everywhere can
+ * set this once at startup instead of threading a logger through every
+ * factory call.
+ */
+let defaultLogger: Logger = createConsoleJsonLogger();
+
+export function setDefaultLogger(logger: Logger): void {
+  defaultLogger = logger;
+}
+
+export function getDefaultLogger(): Logger {
+  return defaultLogger;
+}

package/src/registry-consumer.ts

@@ -39,6 +39,7 @@ import type {
   ResolvedRegistry,
 } from "./define-config.js";
 import type { CallAgentRequest } from "./call-agent-schema.js";
+import type { FetchFn } from "./fetch-types.js";
 import type { SecuritySchemeSummary, CallAgentResponse } from "./types.js";
 import {
   isSecretUri,
@@ -331,7 +332,7 @@ async function defaultSecretResolver(
 async function listFromMcpServer(
   url: string,
   auth: { token?: string; headers?: Record<string, string> },
-  fetchFn: typeof globalThis.fetch,
+  fetchFn: FetchFn,
 ): Promise<AgentListing[]> {
   const serverUrl = url.replace(/\/$/, "");
 
@@ -409,7 +410,7 @@ function issuerFromMcpUrlAndServerInfo(
 async function discoverRegistryViaMcp(
   registryUrl: string,
   authHeaders: Record<string, string>,
-  fetchFn: typeof globalThis.fetch,
+  fetchFn: FetchFn,
 ): Promise<RegistryConfiguration> {
   const serverUrl = registryUrl.replace(/\/$/, "");
   const headers: Record<string, string> = {
@@ -467,7 +468,7 @@ async function callMcpTool(
   toolName: string,
   params: Record<string, unknown>,
   auth: { token?: string; headers?: Record<string, string> },
-  fetchFn: typeof globalThis.fetch,
+  fetchFn: FetchFn,
 ): Promise<unknown> {
   const serverUrl = url.replace(/\/$/, "");
   const headers: Record<string, string> = {
@@ -539,7 +540,7 @@ async function callHttpsTool(
   _toolName: string,
   params: Record<string, unknown>,
   auth: { token?: string; headers?: Record<string, string> },
-  fetchFn: typeof globalThis.fetch,
+  fetchFn: FetchFn,
 ): Promise<unknown> {
   const method = (params.method as string) ?? "GET";
   const path = (params.path as string) ?? "";
@@ -582,8 +583,13 @@ export interface RegistryConsumerOptions {
   /** Bearer token for authenticated registries */
   token?: string;
 
-  /** Custom fetch implementation */
-  fetch?: typeof globalThis.fetch;
+  /**
+   * Custom fetch implementation. Forwarded to every outbound HTTP call the
+   * consumer makes (discovery, jwks, callRegistry, secret resolve). Hosts
+   * running in long-lived servers should pass a hardened fetch to avoid
+   * dead-socket hangs on rolling deploys.
+   */
+  fetch?: FetchFn;
 }
 
 // ============================================
@@ -651,7 +657,7 @@ export async function createRegistryConsumer(
   config: ConsumerConfig,
   options: RegistryConsumerOptions = {},
 ): Promise<RegistryConsumer> {
-  const fetchFn = options.fetch ?? globalThis.fetch;
+  const fetchFn: FetchFn = options.fetch ?? globalThis.fetch;
   const resolveSecretFn = options.resolveSecret ?? defaultSecretResolver;
 
   // Normalize registries

package/src/registry.ts

@@ -7,6 +7,7 @@
 import { dirname, resolve } from "node:path";
 import type { AgentEvent, BaseEvent, CallAgentToolCallEvent, CustomEventMap, EventCallback, EventType, ListAgentsResult, ListAgentsToolCallEvent } from "./events.js";
 import { createEventBus } from "./events.js";
+import type { Logger } from "./logger.js";
 import type { SerializedAgentDefinition } from "./serialized.js";
 import type {
   AgentAction,
@@ -87,7 +88,11 @@ export interface AgentRegistryOptions {
   contextFactory?: ContextFactory;
   /** Lifecycle middleware hooks */
   middleware?: RegistryMiddleware;
-
+  /**
+   * Structured logger for SDK-internal events (listener errors, etc.).
+   * Defaults to the module-level default logger (JSON to stdout/stderr).
+   */
+  logger?: Logger;
 }
 
 /**
@@ -231,7 +236,7 @@ export function createAgentRegistry(
 ): AgentRegistry {
   const { defaultVisibility = "internal" } = options;
   const agents = new Map<string, AgentDefinition>();
-  const eventBus = createEventBus();
+  const eventBus = createEventBus({ logger: options.logger });
 
   /**
    * Check if agent supports the requested action.