npm - @slashfi/agents-sdk - Versions diffs - 0.71.4 → 0.73.0 - Mend

@slashfi/agents-sdk 0.71.4 → 0.73.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (80) hide show

package/dist/adk-tools.d.ts.map +1 -1
package/dist/adk-tools.js +2 -4
package/dist/adk-tools.js.map +1 -1
package/dist/adk.d.ts +1 -1
package/dist/adk.js +7 -27
package/dist/adk.js.map +1 -1
package/dist/agent-definitions/remote-registry.d.ts +15 -0
package/dist/agent-definitions/remote-registry.d.ts.map +1 -1
package/dist/agent-definitions/remote-registry.js +42 -17
package/dist/agent-definitions/remote-registry.js.map +1 -1
package/dist/cjs/adk-tools.js +2 -4
package/dist/cjs/adk-tools.js.map +1 -1
package/dist/cjs/agent-definitions/remote-registry.js +42 -17
package/dist/cjs/agent-definitions/remote-registry.js.map +1 -1
package/dist/cjs/config-store.js +125 -8
package/dist/cjs/config-store.js.map +1 -1
package/dist/cjs/events.js +11 -3
package/dist/cjs/events.js.map +1 -1
package/dist/cjs/fetch-types.js +3 -0
package/dist/cjs/fetch-types.js.map +1 -0
package/dist/cjs/index.js +8 -2
package/dist/cjs/index.js.map +1 -1
package/dist/cjs/key-manager.js +7 -1
package/dist/cjs/key-manager.js.map +1 -1
package/dist/cjs/logger.js +115 -0
package/dist/cjs/logger.js.map +1 -0
package/dist/cjs/registry-consumer.js.map +1 -1
package/dist/cjs/registry.js +1 -1
package/dist/cjs/registry.js.map +1 -1
package/dist/cjs/server.js +70 -13
package/dist/cjs/server.js.map +1 -1
package/dist/config-store.d.ts +19 -0
package/dist/config-store.d.ts.map +1 -1
package/dist/config-store.js +125 -8
package/dist/config-store.js.map +1 -1
package/dist/events.d.ts +6 -1
package/dist/events.d.ts.map +1 -1
package/dist/events.js +11 -3
package/dist/events.js.map +1 -1
package/dist/fetch-types.d.ts +11 -0
package/dist/fetch-types.d.ts.map +1 -0
package/dist/fetch-types.js +2 -0
package/dist/fetch-types.js.map +1 -0
package/dist/index.d.ts +4 -1
package/dist/index.d.ts.map +1 -1
package/dist/index.js +2 -0
package/dist/index.js.map +1 -1
package/dist/key-manager.d.ts +6 -0
package/dist/key-manager.d.ts.map +1 -1
package/dist/key-manager.js +7 -1
package/dist/key-manager.js.map +1 -1
package/dist/logger.d.ts +42 -0
package/dist/logger.d.ts.map +1 -0
package/dist/logger.js +109 -0
package/dist/logger.js.map +1 -0
package/dist/registry-consumer.d.ts +8 -2
package/dist/registry-consumer.d.ts.map +1 -1
package/dist/registry-consumer.js.map +1 -1
package/dist/registry.d.ts +6 -0
package/dist/registry.d.ts.map +1 -1
package/dist/registry.js +1 -1
package/dist/registry.js.map +1 -1
package/dist/server.d.ts +7 -0
package/dist/server.d.ts.map +1 -1
package/dist/server.js +70 -13
package/dist/server.js.map +1 -1
package/package.json +1 -1
package/src/adk-tools.ts +2 -4
package/src/adk.ts +7 -22
package/src/agent-definitions/remote-registry.ts +56 -28
package/src/config-store.ts +168 -9
package/src/events.ts +16 -6
package/src/fetch-types.ts +13 -0
package/src/index.ts +13 -0
package/src/key-manager.ts +12 -1
package/src/logger.test.ts +206 -0
package/src/logger.ts +123 -0
package/src/registry-consumer.ts +13 -7
package/src/registry.ts +7 -2
package/src/server.ts +76 -42

package/src/config-store.ts CHANGED Viewed

@@ -27,6 +27,8 @@ import type {
   ResolvedRegistry,
 } from "./define-config.js";
 import { normalizeRef } from "./define-config.js";
+import type { FetchFn } from "./fetch-types.js";
+import type { Logger } from "./logger.js";
 import { createRegistryConsumer } from "./registry-consumer.js";
 import type {
   AgentListing,
@@ -94,6 +96,23 @@ export interface AdkOptions {
    * (e.g. client_id/client_secret) before the user auth flow runs.
    */
   resolveCredentials?: ResolveCredentials;
+  /**
+   * Custom fetch implementation. Forwarded to every `createRegistryConsumer`
+   * call spun up internally by the adk (consumer(), available(), registry.test()).
+   *
+   * Hosts running inside a long-lived server (e.g. atlas) should pass a
+   * hardened fetch — one backed by a connection pool with short timeouts,
+   * TCP keepalive, and one-shot retry on connection errors — to avoid
+   * dead-socket hangs when upstream pods roll. Defaults to `globalThis.fetch`.
+   */
+  fetch?: FetchFn;
+  /**
+   * Structured logger. Currently reserved for future use; the adk itself
+   * does not emit logs today but may in future versions. Threading this in
+   * now lets hosts standardize on a single logger across all sdk surfaces
+   * (`createAgentRegistry`, `createAgentServer`, `createAdk`, etc.).
+   */
+  logger?: Logger;
 }
 export interface RegistryTestResult {
@@ -353,6 +372,74 @@ function isUnauthorized(result: unknown): boolean {
   return false;
 }
+// ============================================
+// Local auth form HTML
+// ============================================
+const esc = (s: string) =>
+  s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+function renderCredentialForm(name: string, fields: AuthChallengeField[], error?: string): string {
+  const fieldHtml = fields.map((f) => `
+      <div class="field">
+        <label for="${esc(f.name)}">${esc(f.label)}</label>
+        ${f.description ? `<p class="desc">${esc(f.description)}</p>` : ""}
+        <input id="${esc(f.name)}" name="${esc(f.name)}" type="${f.secret ? "password" : "text"}" required autocomplete="off" spellcheck="false" />
+      </div>`).join("");
+  const errorHtml = error
+    ? `<div class="error">${esc(error)}</div>`
+    : "";
+  return `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Authenticate \u2014 ${esc(name)}</title>
+<style>
+*,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
+body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#0a0a0a;color:#e5e5e5;display:flex;justify-content:center;align-items:center;min-height:100vh}
+.card{background:#141414;border:1px solid #262626;border-radius:12px;padding:32px;width:100%;max-width:420px}
+h1{font-size:20px;font-weight:600;color:#fafafa;margin-bottom:4px}
+.sub{font-size:14px;color:#a3a3a3;margin-bottom:24px}
+.field{margin-bottom:16px}
+label{display:block;font-size:13px;font-weight:500;color:#d4d4d4;margin-bottom:6px}
+.desc{font-size:12px;color:#737373;margin-bottom:6px}
+input{width:100%;padding:10px 12px;background:#0a0a0a;border:1px solid #333;border-radius:8px;color:#fafafa;font-size:14px;font-family:'SF Mono',Menlo,Consolas,monospace;outline:none;transition:border-color .15s}
+input:focus{border-color:#3b82f6}
+button{width:100%;padding:10px;background:#f5f5f5;color:#0a0a0a;border:none;border-radius:8px;font-size:14px;font-weight:600;cursor:pointer;margin-top:8px;transition:background .15s}
+button:hover{background:#e5e5e5}
+.error{font-size:13px;color:#f87171;margin-bottom:16px;padding:10px 12px;background:rgba(239,68,68,.1);border:1px solid rgba(239,68,68,.2);border-radius:8px}
+</style></head><body>
+<div class="card">
+  <h1>Authenticate</h1>
+  <p class="sub">${esc(name)}</p>
+  ${errorHtml}
+  <form method="POST">${fieldHtml}
+    <button type="submit">Authenticate</button>
+  </form>
+</div>
+</body></html>`;
+}
+function renderAuthSuccess(name: string): string {
+  return `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Authenticated \u2014 ${esc(name)}</title>
+<style>
+*,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
+body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#0a0a0a;color:#e5e5e5;display:flex;justify-content:center;align-items:center;min-height:100vh}
+.card{background:#141414;border:1px solid #262626;border-radius:12px;padding:32px 48px;width:100%;max-width:420px;text-align:center}
+.icon{font-size:48px;margin-bottom:16px;color:#22c55e}
+h1{font-size:20px;font-weight:600;color:#fafafa;margin-bottom:4px}
+p{font-size:14px;color:#a3a3a3}
+</style></head><body>
+<div class="card">
+  <div class="icon">&#10003;</div>
+  <h1>Authenticated</h1>
+  <p>${esc(name)} is ready to use. You can close this tab.</p>
+</div>
+</body></html>`;
+}
 export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
   async function readConfig(): Promise<ConsumerConfig> {
@@ -579,7 +666,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
     return createRegistryConsumer(
       { registries: resolved, refs: config.refs ?? [] },
-      { token: options.token },
+      { token: options.token, fetch: options.fetch },
     );
   }
@@ -617,7 +704,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
     return createRegistryConsumer(
       { registries: resolved, refs: config.refs ?? [] },
-      { token: options.token },
+      { token: options.token, fetch: options.fetch },
     );
   }
@@ -725,7 +812,10 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
           const url = registryUrl(r);
           const rName = registryDisplayName(r);
           try {
-            const consumer = await createRegistryConsumer({ registries: [r] }, { token: options.token });
+            const consumer = await createRegistryConsumer(
+              { registries: [r] },
+              { token: options.token, fetch: options.fetch },
+            );
             const disc = await consumer.discover(url);
             return { name: rName, url, status: "active", issuer: disc.issuer };
           } catch (err: unknown) {
@@ -1392,19 +1482,88 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
       const result = await ref.auth(name);
       if (result.complete) return { complete: true };
+      const port = options.oauthCallbackPort ?? 8919;
+      const timeout = opts?.timeoutMs ?? 300_000;
+      const { createServer } = await import("node:http");
+      // API key / HTTP auth — serve a local credential form
+      if (result.fields && result.fields.length > 0 && result.type !== "oauth2") {
+        return new Promise<{ complete: boolean }>((resolve, reject) => {
+          const server = createServer(async (req, res) => {
+            const reqUrl = new URL(req.url ?? "/", `http://localhost:${port}`);
+            if (req.method === "GET" && reqUrl.pathname === "/auth") {
+              res.writeHead(200, { "Content-Type": "text/html" });
+              res.end(renderCredentialForm(name, result.fields!));
+              return;
+            }
+            if (req.method === "POST" && reqUrl.pathname === "/auth") {
+              const chunks: Buffer[] = [];
+              for await (const chunk of req) chunks.push(chunk as Buffer);
+              const body = Buffer.concat(chunks).toString();
+              const params = new URLSearchParams(body);
+              const credentials: Record<string, string> = {};
+              for (const field of result.fields!) {
+                const val = params.get(field.name);
+                if (val) credentials[field.name] = val;
+              }
+              try {
+                const authResult = await ref.auth(name, { credentials });
+                if (authResult.complete) {
+                  res.writeHead(200, { "Content-Type": "text/html" });
+                  res.end(renderAuthSuccess(name));
+                  server.close();
+                  resolve({ complete: true });
+                } else {
+                  res.writeHead(200, { "Content-Type": "text/html" });
+                  res.end(renderCredentialForm(
+                    name,
+                    authResult.fields ?? result.fields!,
+                    "Some credentials were missing or invalid.",
+                  ));
+                }
+              } catch (err) {
+                res.writeHead(500, { "Content-Type": "text/html" });
+                res.end(renderCredentialForm(
+                  name,
+                  result.fields!,
+                  err instanceof Error ? err.message : String(err),
+                ));
+              }
+              return;
+            }
+            res.writeHead(404);
+            res.end();
+          });
+          server.listen(port, () => {
+            if (opts?.onAuthorizeUrl) {
+              opts.onAuthorizeUrl(`http://localhost:${port}/auth`);
+            }
+          });
+          const timer = setTimeout(() => {
+            server.close();
+            reject(new Error("Auth timed out"));
+          }, timeout);
+          server.on("close", () => clearTimeout(timer));
+        });
+      }
+      // OAuth2 — open authorize URL and wait for callback
       if (result.type !== "oauth2" || !result.authorizeUrl) {
-        throw new Error(`authLocal only handles OAuth2. Auth type: ${result.type}`);
+        throw new Error(`authLocal cannot handle auth type: ${result.type}`);
       }
       if (opts?.onAuthorizeUrl) {
         opts.onAuthorizeUrl(result.authorizeUrl);
       }
-      // Spin up local callback server
-      const port = options.oauthCallbackPort ?? 8919;
-      const timeout = opts?.timeoutMs ?? 300_000;
-      const { createServer } = await import("node:http");
       return new Promise<{ complete: boolean }>((resolve, reject) => {
         const server = createServer(async (req, res) => {
           const reqUrl = new URL(req.url ?? "/", `http://localhost:${port}`);

package/src/events.ts CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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;
+}