@slashfi/agents-sdk 0.72.0 → 0.74.0

package/src/adk-tools.ts

@@ -17,10 +17,10 @@
  * ```
  */
 
-import { defineTool } from "./define.js";
-import type { ToolDefinition, ToolContext } from "./types.js";
 import type { Adk } from "./config-store.js";
 import type { RefEntry, RegistryEntry } from "./define-config.js";
+import { defineTool } from "./define.js";
+import type { ToolContext, ToolDefinition } from "./types.js";
 
 export interface AdkToolsHooks<TCtx extends ToolContext = ToolContext> {
   /**
@@ -33,7 +33,9 @@ export interface AdkToolsHooks<TCtx extends ToolContext = ToolContext> {
    * getAuthStateContext: async (ctx) => ({ tid: ctx.tenantId, uid: ctx.userId })
    * ```
    */
-  getAuthStateContext?: (ctx: TCtx) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  getAuthStateContext?: (
+    ctx: TCtx,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>;
 }
 
 export interface CreateAdkToolsOptions<TCtx extends ToolContext = ToolContext> {
@@ -48,72 +50,184 @@ export interface CreateAdkToolsOptions<TCtx extends ToolContext = ToolContext> {
   hooks?: AdkToolsHooks<TCtx>;
 }
 
-export function createAdkTools<TCtx extends ToolContext = ToolContext>(opts: CreateAdkToolsOptions<TCtx>): ToolDefinition<TCtx>[] {
+export function createAdkTools<TCtx extends ToolContext = ToolContext>(
+  opts: CreateAdkToolsOptions<TCtx>,
+): ToolDefinition<TCtx>[] {
   const { resolveScope, scopes } = opts;
 
   const scopeSchema = scopes
-    ? { type: "string" as const, enum: scopes, description: "Config scope to operate on" }
+    ? {
+        type: "string" as const,
+        enum: scopes,
+        description: "Config scope to operate on",
+      }
     : { type: "string" as const, description: "Config scope (optional)" };
 
   const refTool = defineTool({
     name: "ref",
     description:
-      "Manage agent refs. Operations: add, remove, list, update, inspect, call, auth, auth-status, refresh-token, resources, read.",
+      "Manage agent refs. Operations: add, remove, list, update, inspect, call, auth, auth-status, refresh-token, resources, read. For `add`, supply `ref` (canonical agent path, e.g. 'notion') and optionally `name` for a local alias; either one uniquely identifies the ref. For every other operation, pass `name` (the local identifier you used on add — defaults to `ref` when you didn't set it explicitly).",
     inputSchema: {
       type: "object" as const,
       properties: {
         operation: {
           type: "string",
-          enum: ["add", "remove", "list", "update", "inspect", "call", "auth", "auth-status", "refresh-token", "resources", "read"],
+          enum: [
+            "add",
+            "remove",
+            "list",
+            "update",
+            "inspect",
+            "call",
+            "auth",
+            "auth-status",
+            "refresh-token",
+            "resources",
+            "read",
+          ],
         },
         scope: scopeSchema,
-        ref: { type: "string" },
-        name: { type: "string" },
-        scheme: { type: "string" },
-        url: { type: "string" },
-        as: { type: "string" },
-        sourceRegistry: { type: "object", properties: { url: { type: "string" }, agentPath: { type: "string" } } },
-        config: { type: "object" },
-        tool: { type: "string" },
-        params: { type: "object" },
-        full: { type: "boolean" },
-        uris: { type: "array", items: { type: "string" } },
-        apiKey: { type: "string" },
-        credentials: { type: "object", description: "Key-value map of credential fields (keys match field names from auth challenge)" },
+        ref: {
+          type: "string",
+          description:
+            "Canonical agent path on the remote registry (e.g. 'notion', 'linear', 'github'). Used by `add` to identify which agent definition to connect to. Other operations use `name` instead. If you call `add` with only `name` and no `ref`, `ref` defaults to `name`.",
+        },
+        name: {
+          type: "string",
+          description:
+            "Local identifier for this ref, used by all operations except `add` to look up the entry. On `add`, `name` is optional — it only needs to differ from `ref` when you want multiple local instances of the same agent (e.g. `{ ref: 'notion', name: 'work-notion' }`). Omit it and the ref is identified by its canonical path.",
+        },
+        scheme: {
+          type: "string",
+          description:
+            "Connection scheme: 'mcp' (direct MCP server), 'https' (REST proxy), or 'registry' (discovered via a registry). Auto-inferred from `url` or `sourceRegistry` when omitted.",
+        },
+        url: {
+          type: "string",
+          description:
+            "Direct URL to the agent (e.g. https://mcp.notion.com/mcp). Required for 'mcp' and 'https' schemes.",
+        },
+        sourceRegistry: {
+          type: "object",
+          properties: {
+            url: { type: "string" },
+            agentPath: { type: "string" },
+          },
+          description:
+            "When scheme is 'registry', the registry + agent path to resolve through.",
+        },
+        config: {
+          type: "object",
+          description:
+            "Per-instance config passed to the agent (headers, credentials, etc.). Supports `{{secret-uri}}` templates.",
+        },
+        tool: {
+          type: "string",
+          description:
+            "For `call` operation: the tool name on the ref to invoke.",
+        },
+        params: {
+          type: "object",
+          description: "For `call` operation: arguments to pass to the tool.",
+        },
+        full: {
+          type: "boolean",
+          description:
+            "For `inspect` operation: include full agent definition.",
+        },
+        uris: {
+          type: "array",
+          items: { type: "string" },
+          description: "For `read` operation: the resource URIs to read.",
+        },
+        apiKey: {
+          type: "string",
+          description: "For `auth` operation: pre-provisioned API key.",
+        },
+        credentials: {
+          type: "object",
+          description:
+            "For `auth` operation: key-value map of credential fields (keys match field names from the auth challenge).",
+        },
       },
       required: ["operation"],
     },
     execute: async (input: Record<string, unknown>, ctx) => {
-      const adk = await resolveScope(input.scope as string | undefined, ctx as TCtx);
+      const adk = await resolveScope(
+        input.scope as string | undefined,
+        ctx as TCtx,
+      );
       const op = input.operation as string;
 
       switch (op) {
         case "add": {
-          const entry: Record<string, unknown> = { ref: input.ref };
+          // Accept `ref` or `name` (or both). If only one is given, the
+          // other defaults to it. This matches the "Add a ref called X"
+          // natural-language phrasing — LLMs that pick `name` get the
+          // same behavior as ones that pick `ref`, eliminating
+          // non-determinism on the identifier field. Throws when both
+          // are missing, so misuse is loud instead of silently storing
+          // `{ ref: undefined }`.
+          const refValue = (input.ref ?? input.name) as string | undefined;
+          if (!refValue) {
+            throw new Error(
+              "ref.add: must supply either 'ref' (canonical agent path) or 'name' (local identifier); both may be the same string for the common single-instance case.",
+            );
+          }
+          const entry: Record<string, unknown> = { ref: refValue };
           if (input.scheme) entry.scheme = input.scheme;
           if (input.url) entry.url = input.url;
-          if (input.as) entry.as = input.as;
+          // Only store `name` when it's meaningfully different from
+          // `ref` (the multi-instance aliasing case). Avoids a
+          // redundant `{ name: 'notion', ref: 'notion' }` stored shape.
+          const nameValue = input.name as string | undefined;
+          if (nameValue && nameValue !== refValue) {
+            entry.name = nameValue;
+          }
           if (input.sourceRegistry) entry.sourceRegistry = input.sourceRegistry;
           if (input.config) entry.config = input.config;
           const { security } = await adk.ref.add(entry as unknown as RefEntry);
-          return { added: true, ref: input.ref, name: (input.as ?? input.ref) as string, security };
+          return {
+            added: true,
+            ref: refValue,
+            name: (entry.name ?? refValue) as string,
+            security,
+          };
         }
         case "remove":
           return { removed: await adk.ref.remove(input.name as string) };
         case "list":
           return { refs: await adk.ref.list() };
         case "update":
-          return { updated: await adk.ref.update(input.name as string, input as unknown as Partial<RefEntry>) };
+          return {
+            updated: await adk.ref.update(
+              input.name as string,
+              input as unknown as Partial<RefEntry>,
+            ),
+          };
         case "inspect":
-          return await adk.ref.inspect(input.name as string, { full: input.full as boolean });
+          return await adk.ref.inspect(input.name as string, {
+            full: input.full as boolean,
+          });
         case "call":
-          return await adk.ref.call(input.name as string, input.tool as string, input.params as Record<string, unknown>);
+          return await adk.ref.call(
+            input.name as string,
+            input.tool as string,
+            input.params as Record<string, unknown>,
+          );
         case "auth": {
-          const authOpts: { apiKey?: string; credentials?: Record<string, string>; stateContext?: Record<string, unknown> } = {};
+          const authOpts: {
+            apiKey?: string;
+            credentials?: Record<string, string>;
+            stateContext?: Record<string, unknown>;
+          } = {};
           if (input.apiKey) authOpts.apiKey = input.apiKey as string;
-          if (input.credentials) authOpts.credentials = input.credentials as Record<string, string>;
+          if (input.credentials)
+            authOpts.credentials = input.credentials as Record<string, string>;
           if (opts.hooks?.getAuthStateContext) {
-            authOpts.stateContext = await opts.hooks.getAuthStateContext(ctx as TCtx);
+            authOpts.stateContext = await opts.hooks.getAuthStateContext(
+              ctx as TCtx,
+            );
           }
           return await adk.ref.auth(input.name as string, authOpts);
         }
@@ -124,7 +238,10 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(opts: Cre
         case "resources":
           return await adk.ref.resources(input.name as string);
         case "read":
-          return await adk.ref.read(input.name as string, input.uris as string[]);
+          return await adk.ref.read(
+            input.name as string,
+            input.uris as string[],
+          );
         default:
           throw new Error(`Unknown ref operation: ${op}`);
       }
@@ -140,7 +257,15 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(opts: Cre
       properties: {
         operation: {
           type: "string",
-          enum: ["add", "remove", "list", "update", "browse", "inspect", "test"],
+          enum: [
+            "add",
+            "remove",
+            "list",
+            "update",
+            "browse",
+            "inspect",
+            "test",
+          ],
         },
         scope: scopeSchema,
         url: { type: "string" },
@@ -152,12 +277,18 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(opts: Cre
       required: ["operation"],
     },
     execute: async (input: Record<string, unknown>, ctx) => {
-      const adk = await resolveScope(input.scope as string | undefined, ctx as TCtx);
+      const adk = await resolveScope(
+        input.scope as string | undefined,
+        ctx as TCtx,
+      );
       const op = input.operation as string;
 
       switch (op) {
         case "add": {
-          const entry: Record<string, unknown> = { url: input.url, name: input.name };
+          const entry: Record<string, unknown> = {
+            url: input.url,
+            name: input.name,
+          };
           if (input.auth) entry.auth = input.auth;
           if (input.headers) entry.headers = input.headers;
           await adk.registry.add(entry as unknown as RegistryEntry);
@@ -173,10 +304,20 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(opts: Cre
           if (input.name !== undefined) updates.name = input.name;
           if (input.auth) updates.auth = input.auth;
           if (input.headers) updates.headers = input.headers;
-          return { updated: await adk.registry.update(input.name as string, updates as unknown as Partial<RegistryEntry>) };
+          return {
+            updated: await adk.registry.update(
+              input.name as string,
+              updates as unknown as Partial<RegistryEntry>,
+            ),
+          };
         }
         case "browse":
-          return { agents: await adk.registry.browse(input.name as string, input.query as string) };
+          return {
+            agents: await adk.registry.browse(
+              input.name as string,
+              input.query as string,
+            ),
+          };
         case "inspect":
           return await adk.registry.inspect(input.name as string);
         case "test":

package/src/adk.ts

@@ -75,7 +75,7 @@ const HELP_SECTIONS: Record<string, string> = {
   adk ref call <name> <tool> [params_json]
   adk ref resources <name>
   adk ref read <name> <uri> [uri...]
-  adk ref auth <name> [--api-key <key>]
+  adk ref auth <name> [--api-key <key>] [--<field> <value> ...]
   adk ref auth-status <name>
 
 Examples:
@@ -125,7 +125,7 @@ Ref operations:
   adk ref call <name> <tool> [params_json]
   adk ref resources <name>
   adk ref read <name> <uri> [uri...]
-  adk ref auth <name> [--api-key <key>]
+  adk ref auth <name> [--api-key <key>] [--<field> <value> ...]
   adk ref auth-status <name>
 
 Init targets (presets):
@@ -463,19 +463,14 @@ async function runRef() {
         break;
       }
 
-      if (status.security?.type === "apiKey" || status.security?.type === "http") {
-        console.error(`Provide a key: adk ref auth ${name} --api-key <your-key>`);
-        process.exit(1);
-      }
-
-      // OAuth — run locally with browser open
+      // authLocal handles both OAuth (browser redirect) and apiKey/http (local credential form)
       try {
         const result = await adk.ref.authLocal(name, {
           onAuthorizeUrl: (url) => {
-            console.log(`\nOpen this URL to authorize:\n\n  ${url}\n`);
+            console.log(`\nOpen this URL to authenticate:\n\n  ${url}\n`);
             const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
             import("node:child_process").then(({ exec }) => exec(`${opener} "${url}"`)).catch(() => {});
-            console.log("Waiting for callback ...");
+            console.log("Waiting ...");
           },
         });
         if (result.complete) {

package/src/agent-definitions/remote-registry.ts

@@ -25,6 +25,8 @@
  */
 
 import { defineAgent, defineTool } from "../define.js";
+import type { FetchFn } from "../fetch-types.js";
+import { getDefaultLogger, type Logger } from "../logger.js";
 import type {
   AgentDefinition,
   IntegrationMethodResult,
@@ -40,6 +42,19 @@ export interface RemoteRegistryAgentOptions {
   signJwt: (claims: Record<string, unknown>) => Promise<string>;
   /** Add a trusted JWKS issuer (optional — for bidirectional trust) */
   addTrustedIssuer?: (issuerUrl: string) => Promise<void>;
+  /**
+   * Structured logger for connection-store traces and setup flow. Defaults
+   * to the module-level default logger. Traces are emitted at debug level.
+   */
+  logger?: Logger;
+  /**
+   * Custom fetch implementation for outbound JWKS / oauth/token / MCP calls
+   * to remote registries. Defaults to `globalThis.fetch`. Hosts in
+   * long-running processes should pass a hardened fetch (e.g. one backed
+   * by undici.Agent with short timeouts, keepalive, and retry) to avoid
+   * dead-socket hangs on rolling deploys.
+   */
+  fetch?: FetchFn;
 }
 
 /** Stored connection to a remote registry */
@@ -90,6 +105,8 @@ export function createRemoteRegistryAgent(
   options: RemoteRegistryAgentOptions,
 ): AgentDefinition {
   const { secretStore, signJwt, addTrustedIssuer } = options;
+  const logger = options.logger ?? getDefaultLogger();
+  const fetchFn: FetchFn = options.fetch ?? globalThis.fetch;
 
   // --- Connection storage (KV via SecretStore) ---
 
@@ -97,12 +114,11 @@ export function createRemoteRegistryAgent(
     ownerId: string,
     conn: RegistryConnection,
   ): Promise<void> {
-    console.error(
-      "[remote-registry] storeConnection for owner:",
-      ownerId,
-      "conn:",
-      conn.id,
-    );
+    logger.debug("remote_registry_store_connection", {
+      component: "agents-sdk.remote-registry",
+      owner_id: ownerId,
+      connection_id: conn.id,
+    });
     const all = await loadAllConnections(ownerId);
     all[conn.id] = conn;
     const value = JSON.stringify(all);
@@ -116,7 +132,10 @@ export function createRemoteRegistryAgent(
   async function loadAllConnections(
     ownerId: string,
   ): Promise<Record<string, RegistryConnection>> {
-    console.error("[remote-registry] loadAllConnections for owner:", ownerId);
+    logger.debug("remote_registry_load_connections", {
+      component: "agents-sdk.remote-registry",
+      owner_id: ownerId,
+    });
     if (secretStore.resolveByEntity) {
       const scope = { tenantId: ownerId };
       const secretIds = await secretStore.resolveByEntity(
@@ -156,7 +175,7 @@ export function createRemoteRegistryAgent(
     jwt: string,
     request: Record<string, unknown>,
   ): Promise<unknown> {
-    const res = await globalThis.fetch(url, {
+    const res = await fetchFn(url, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -299,10 +318,10 @@ export function createRemoteRegistryAgent(
     params: Record<string, unknown>,
     _ctx: ToolContext,
   ): Promise<IntegrationMethodResult> => {
-    console.log(
-      "[remote-registry] setupFn called with:",
-      JSON.stringify(params),
-    );
+    logger.debug("remote_registry_setup_called", {
+      component: "agents-sdk.remote-registry",
+      params,
+    });
     const url = params.url as string;
     const name = (params.name as string) ?? "registry";
     const oidcUserId = params.oidcUserId as string | undefined;
@@ -317,7 +336,7 @@ export function createRemoteRegistryAgent(
           action: "setup",
           type: "agent-registry",
         });
-        const tokenRes = await globalThis.fetch(`${baseUrl}/oauth/token`, {
+        const tokenRes = await fetchFn(`${baseUrl}/oauth/token`, {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({
@@ -354,29 +373,39 @@ export function createRemoteRegistryAgent(
 
       // Phase 1: Verify JWKS at origin, establish trust, then request OIDC
       const jwksUri = `${new URL(baseUrl).origin}/.well-known/jwks.json`;
-      console.log("[setupFn] fetching JWKS:", jwksUri);
-      const jwksRes = await globalThis.fetch(jwksUri);
-      console.log("[setupFn] JWKS status:", jwksRes.status);
+      logger.debug("remote_registry_setup_fetching_jwks", {
+        component: "agents-sdk.remote-registry",
+        jwks_uri: jwksUri,
+      });
+      const jwksRes = await fetchFn(jwksUri);
+      logger.debug("remote_registry_setup_jwks_status", {
+        component: "agents-sdk.remote-registry",
+        status: jwksRes.status,
+      });
       if (!jwksRes.ok)
         return {
           success: false,
           error: `JWKS not reachable at ${jwksUri}`,
         };
       if (addTrustedIssuer) {
-        console.log("[setupFn] adding trusted issuer:", baseUrl);
+        logger.debug("remote_registry_setup_adding_trusted_issuer", {
+          component: "agents-sdk.remote-registry",
+          issuer: baseUrl,
+        });
         await addTrustedIssuer(baseUrl);
-        console.log("[setupFn] added trusted issuer");
       }
 
       // Request identity — atlas will return authorize URL for Slack OIDC
-      console.log("[setupFn] Phase 1: requesting identity via jwt_exchange");
+      logger.debug("remote_registry_setup_phase1_jwt_exchange", {
+        component: "agents-sdk.remote-registry",
+        target_url: `${baseUrl}/oauth/token`,
+      });
       const jwt = await signJwt({
         action: "setup",
         type: "agent-registry",
         targetUrl: url,
       });
-      console.log("[setupFn] POSTing to:", `${baseUrl}/oauth/token`);
-      const tokenRes = await globalThis.fetch(`${baseUrl}/oauth/token`, {
+      const tokenRes = await fetchFn(`${baseUrl}/oauth/token`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
@@ -386,12 +415,11 @@ export function createRemoteRegistryAgent(
           redirect_uri: params.redirect_uri ?? "",
         }),
       });
-      console.log("[setupFn] token status:", tokenRes.status);
       const tokenData = (await tokenRes.json()) as OAuthTokenJsonBody;
-      console.log(
-        "[setupFn] tokenData:",
-        JSON.stringify(tokenData).substring(0, 300),
-      );
+      logger.debug("remote_registry_setup_phase1_response", {
+        component: "agents-sdk.remote-registry",
+        status: tokenRes.status,
+      });
 
       // If already set up (user linked), store connection directly
       if (tokenData.access_token) {
@@ -460,7 +488,7 @@ export function createRemoteRegistryAgent(
         action: "connect",
         type: "agent-registry",
       });
-      const tokenRes = await globalThis.fetch(`${conn.url}/oauth/token`, {
+      const tokenRes = await fetchFn(`${conn.url}/oauth/token`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
@@ -532,7 +560,7 @@ export function createRemoteRegistryAgent(
           const base = url.replace(/\/$/, "");
           const origin = new URL(base).origin;
           const jwksUri = `${origin}/.well-known/jwks.json`;
-          const res = await globalThis.fetch(jwksUri);
+          const res = await fetchFn(jwksUri);
           if (!res.ok) {
             return {
               success: false,