@slashfi/agents-sdk 0.72.0 → 0.74.0

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/ref-naming.test.ts

@@ -0,0 +1,351 @@
+/**
+ * Tests for the `ref` naming contract introduced in 0.74:
+ *
+ *   - `RefEntry` gains an optional `name?` field for the local identifier.
+ *     The legacy `as?` field still parses for backward compat.
+ *   - `normalizeRef` resolves the identifier as `name ?? as ?? ref`, so
+ *     all lookup paths (get, list, update, remove) accept entries written
+ *     in either shape.
+ *   - `createRefTool` (the adk-tools.ts MCP tool) drops `as` from its
+ *     schema and defaults `ref` to `name` on add, so "Add a ref called X"
+ *     via an LLM that picks either field lands on the same stored
+ *     `{ ref: 'X' }` entry.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createAdkTools } from "./adk-tools";
+import type { FsStore } from "./agent-definitions/config";
+import { createAdk } from "./index";
+import type { ToolContext } from "./types";
+
+function createMemoryFs(): FsStore {
+  const files = new Map<string, string>();
+  return {
+    async readFile(path: string) {
+      return files.get(path) ?? null;
+    },
+    async writeFile(path: string, content: string) {
+      files.set(path, content);
+    },
+  };
+}
+
+/** Read a known-present file and parse it as JSON, with typed assertion. */
+async function readJson<T = unknown>(fs: FsStore, path: string): Promise<T> {
+  const raw = await fs.readFile(path);
+  if (raw === null) {
+    throw new Error(`Expected ${path} to exist`);
+  }
+  return JSON.parse(raw) as T;
+}
+
+// ─── RefEntry: name field on write ───────────────────────────────────
+
+describe("ref.add — identifier field", () => {
+  test("single-instance case stores only `ref` (no `name`/`as`)", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+
+    await adk.ref.add({
+      ref: "test-ref",
+      scheme: "mcp",
+      url: "http://localhost:12345",
+    });
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs).toHaveLength(1);
+    expect(parsed.refs[0].ref).toBe("test-ref");
+    expect(parsed.refs[0].name).toBeUndefined();
+    expect(parsed.refs[0].as).toBeUndefined();
+  });
+
+  test("aliasing case stores both `ref` and `name`", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+
+    await adk.ref.add({
+      ref: "notion",
+      name: "work-notion",
+      scheme: "mcp",
+      url: "http://localhost:12345",
+    });
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs[0].ref).toBe("notion");
+    expect(parsed.refs[0].name).toBe("work-notion");
+    // Legacy `as` field is never emitted on new writes.
+    expect(parsed.refs[0].as).toBeUndefined();
+  });
+});
+
+// ─── Lookup compatibility: new `name` field works end-to-end ─────────
+
+describe("ref lookup — name/as/ref resolution", () => {
+  test("entries written with `name` are findable by `name`", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+
+    await adk.ref.add({
+      ref: "notion",
+      name: "work-notion",
+      scheme: "mcp",
+      url: "http://localhost:12345",
+    });
+
+    const entry = await adk.ref.get("work-notion");
+    expect(entry).not.toBeNull();
+    expect(entry?.ref).toBe("notion");
+  });
+
+  test("entries written with `name` return name field when listed", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+
+    await adk.ref.add({
+      ref: "notion",
+      name: "work-notion",
+      scheme: "mcp",
+      url: "http://localhost:12345",
+    });
+
+    const refs = await adk.ref.list();
+    expect(refs).toHaveLength(1);
+    expect(refs[0]?.name).toBe("work-notion");
+  });
+
+  test("legacy entries written with `as` remain findable by `as`", async () => {
+    // Simulate a consumer-config.json produced by a pre-0.74 client that
+    // still writes the `as` field. The read path must still resolve it.
+    const fs = createMemoryFs();
+    await fs.writeFile(
+      "consumer-config.json",
+      JSON.stringify({
+        refs: [
+          {
+            ref: "notion",
+            as: "work-notion",
+            scheme: "mcp",
+            url: "http://localhost:12345",
+          },
+        ],
+      }),
+    );
+    const adk = createAdk(fs);
+
+    const entry = await adk.ref.get("work-notion");
+    expect(entry).not.toBeNull();
+    expect(entry?.ref).toBe("notion");
+    expect(entry?.as).toBe("work-notion");
+  });
+
+  test("when both `name` and `as` are present, `name` wins", async () => {
+    const fs = createMemoryFs();
+    await fs.writeFile(
+      "consumer-config.json",
+      JSON.stringify({
+        refs: [
+          {
+            ref: "notion",
+            name: "new-identifier",
+            as: "legacy-identifier",
+            scheme: "mcp",
+            url: "http://localhost:12345",
+          },
+        ],
+      }),
+    );
+    const adk = createAdk(fs);
+
+    const byNew = await adk.ref.get("new-identifier");
+    expect(byNew).not.toBeNull();
+    expect(byNew?.ref).toBe("notion");
+  });
+});
+
+// ─── ref.update: renaming clears the legacy `as` field ───────────────
+
+describe("ref.update — name/as handling", () => {
+  test("passing `name` in updates sets name and clears legacy `as`", async () => {
+    const fs = createMemoryFs();
+    await fs.writeFile(
+      "consumer-config.json",
+      JSON.stringify({
+        refs: [
+          {
+            ref: "notion",
+            as: "old-alias",
+            scheme: "mcp",
+            url: "http://localhost:12345",
+          },
+        ],
+      }),
+    );
+    const adk = createAdk(fs);
+
+    const ok = await adk.ref.update("old-alias", { name: "new-alias" });
+    expect(ok).toBe(true);
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs[0].name).toBe("new-alias");
+    expect(parsed.refs[0].as).toBeUndefined();
+    expect(parsed.refs[0].ref).toBe("notion");
+  });
+
+  test("passing only `as` updates the legacy field (pre-0.74 callers)", async () => {
+    const fs = createMemoryFs();
+    await fs.writeFile(
+      "consumer-config.json",
+      JSON.stringify({
+        refs: [
+          {
+            ref: "notion",
+            as: "first",
+            scheme: "mcp",
+            url: "http://localhost:12345",
+          },
+        ],
+      }),
+    );
+    const adk = createAdk(fs);
+
+    const ok = await adk.ref.update("first", { as: "second" });
+    expect(ok).toBe(true);
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs[0].as).toBe("second");
+  });
+});
+
+// ─── Tool surface: the LLM non-determinism scenario ──────────────────
+//
+// When an LLM is prompted with "Add a ref called X", its tool-call
+// arguments can land on either `{ ref: 'X', … }` or `{ name: 'X', … }`
+// depending on sampling. Pre-0.74, the former stored `{ ref: 'X' }`
+// and the latter stored `{ ref: undefined }` (broken lookup). The
+// `add` handler now defaults `ref ??= name` so both paths converge on
+// the same stored entry.
+
+describe("ref tool — add operation defaults ref to name", () => {
+  function makeRefTool(adk: ReturnType<typeof createAdk>) {
+    const tools = createAdkTools({ resolveScope: () => adk });
+    const ref = tools.find((t) => t.name === "ref");
+    if (!ref) throw new Error("ref tool not found");
+    return ref;
+  }
+
+  test("LLM sends only `name` → ref defaults to name, entry is findable", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+    const refTool = makeRefTool(adk);
+
+    const ctx = {} as ToolContext;
+    await refTool.execute(
+      {
+        operation: "add",
+        name: "test-identity-ref",
+        scheme: "mcp",
+        url: "http://127.0.0.1:33469",
+      },
+      ctx,
+    );
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs).toHaveLength(1);
+    expect(parsed.refs[0].ref).toBe("test-identity-ref");
+    // name was not stored because it equals ref (single-instance case)
+    expect(parsed.refs[0].name).toBeUndefined();
+
+    const entry = await adk.ref.get("test-identity-ref");
+    expect(entry).not.toBeNull();
+  });
+
+  test("LLM sends only `ref` → same resulting entry", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+    const refTool = makeRefTool(adk);
+
+    const ctx = {} as ToolContext;
+    await refTool.execute(
+      {
+        operation: "add",
+        ref: "test-identity-ref",
+        scheme: "mcp",
+        url: "http://127.0.0.1:33469",
+      },
+      ctx,
+    );
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs[0].ref).toBe("test-identity-ref");
+    expect(parsed.refs[0].name).toBeUndefined();
+  });
+
+  test("LLM sends `ref` + different `name` → stored as canonical + alias", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+    const refTool = makeRefTool(adk);
+
+    const ctx = {} as ToolContext;
+    await refTool.execute(
+      {
+        operation: "add",
+        ref: "notion",
+        name: "work-notion",
+        scheme: "mcp",
+        url: "http://127.0.0.1:33469",
+      },
+      ctx,
+    );
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs[0].ref).toBe("notion");
+    expect(parsed.refs[0].name).toBe("work-notion");
+
+    // The entry is findable by the local identifier (name), not the
+    // canonical ref.
+    expect(await adk.ref.get("work-notion")).not.toBeNull();
+  });
+
+  test("LLM omits both `ref` and `name` → loud error (no silent bad write)", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+    const refTool = makeRefTool(adk);
+
+    const ctx = {} as ToolContext;
+    await expect(
+      refTool.execute(
+        {
+          operation: "add",
+          scheme: "mcp",
+          url: "http://127.0.0.1:33469",
+        },
+        ctx,
+      ),
+    ).rejects.toThrow(/ref|name/);
+
+    // Nothing got written.
+    const raw = await fs.readFile("consumer-config.json");
+    expect(raw).toBeNull();
+  });
+});

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.