@slashfi/agents-sdk 0.77.2 → 0.77.3

package/src/adk-tools.ts

@@ -17,252 +17,10 @@
  * ```
  */
 
-import { z } from "zod";
-import { AdkError } from "./adk-error.js";
-import { zodToOpenAiJsonSchema } from "./call-agent-schema.js";
 import type { Adk } from "./config-store.js";
 import type { RefEntry, RegistryEntry } from "./define-config.js";
 import { defineTool } from "./define.js";
-import type { JsonSchema, ToolContext, ToolDefinition } from "./types.js";
-
-const objectRecordSchema = z.record(z.unknown());
-const sourceRegistrySchema = z
-  .object({
-    url: z.string().min(1).describe("Registry MCP URL."),
-    agentPath: z.string().optional().describe("Agent path on that registry."),
-  })
-  .passthrough();
-const refScopeSchema = z
-  .string()
-  .optional()
-  .describe("Config scope to operate on.");
-const refNameSchema = z.string().min(1).describe("Local connection name.");
-
-const refAddOperationSchema = z
-  .object({
-    operation: z.literal("add"),
-    scope: refScopeSchema,
-    ref: z
-      .string()
-      .min(1)
-      .optional()
-      .describe(
-        "Canonical agent path, e.g. 'google-calendar'. Defaults to name when omitted.",
-      ),
-    name: refNameSchema
-      .optional()
-      .describe("Local connection name. Defaults to ref when omitted."),
-    scheme: z
-      .enum(["registry", "mcp", "https"])
-      .optional()
-      .describe(
-        "Connection type. Usually inferred from sourceRegistry or url.",
-      ),
-    url: z
-      .string()
-      .min(1)
-      .optional()
-      .describe("Direct MCP/HTTPS URL. Required for direct mcp/https refs."),
-    sourceRegistry: sourceRegistrySchema
-      .optional()
-      .describe(
-        "Registry that serves this agent. Required for registry-backed refs.",
-      ),
-    config: objectRecordSchema
-      .optional()
-      .describe("Optional per-instance config."),
-  })
-  .passthrough()
-  .superRefine((input, ctx) => {
-    if (!input.ref && !input.name) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        path: ["ref"],
-        message: "Either ref or name is required.",
-      });
-    }
-    if (input.scheme === "registry" && !input.sourceRegistry?.url) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        path: ["sourceRegistry", "url"],
-        message: "scheme=registry requires sourceRegistry.url.",
-      });
-    }
-    if ((input.scheme === "mcp" || input.scheme === "https") && !input.url) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        path: ["url"],
-        message: `scheme=${input.scheme} requires url.`,
-      });
-    }
-    if (!input.url && !input.sourceRegistry?.url) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        path: ["sourceRegistry"],
-        message:
-          "Connection target is required: provide sourceRegistry.url for a registry ref, or url for a direct mcp/https ref.",
-      });
-    }
-  });
-
-const refOperationSchemas = {
-  add: refAddOperationSchema,
-  remove: z
-    .object({
-      operation: z.literal("remove"),
-      scope: refScopeSchema,
-      name: refNameSchema,
-    })
-    .passthrough(),
-  list: z
-    .object({ operation: z.literal("list"), scope: refScopeSchema })
-    .passthrough(),
-  update: z
-    .object({
-      operation: z.literal("update"),
-      scope: refScopeSchema,
-      name: refNameSchema,
-      ref: z.string().optional(),
-      scheme: z.enum(["registry", "mcp", "https"]).optional(),
-      url: z.string().optional(),
-      sourceRegistry: sourceRegistrySchema.optional(),
-      config: objectRecordSchema.optional(),
-    })
-    .passthrough(),
-  inspect: z
-    .object({
-      operation: z.literal("inspect"),
-      scope: refScopeSchema,
-      name: refNameSchema,
-      full: z.boolean().optional(),
-    })
-    .passthrough(),
-  call: z
-    .object({
-      operation: z.literal("call"),
-      scope: refScopeSchema,
-      name: refNameSchema,
-      tool: z.string().min(1),
-      params: objectRecordSchema.optional(),
-    })
-    .passthrough(),
-  auth: z
-    .object({
-      operation: z.literal("auth"),
-      scope: refScopeSchema,
-      name: refNameSchema,
-      ref: z.string().optional(),
-      apiKey: z.string().optional(),
-      credentials: z.record(z.string()).optional(),
-      sourceRegistry: sourceRegistrySchema.optional(),
-    })
-    .passthrough(),
-  "auth-status": z
-    .object({
-      operation: z.literal("auth-status"),
-      scope: refScopeSchema,
-      name: refNameSchema,
-    })
-    .passthrough(),
-  "refresh-token": z
-    .object({
-      operation: z.literal("refresh-token"),
-      scope: refScopeSchema,
-      name: refNameSchema,
-    })
-    .passthrough(),
-  resources: z
-    .object({
-      operation: z.literal("resources"),
-      scope: refScopeSchema,
-      name: refNameSchema,
-    })
-    .passthrough(),
-  read: z
-    .object({
-      operation: z.literal("read"),
-      scope: refScopeSchema,
-      name: refNameSchema,
-      uris: z.array(z.string()),
-    })
-    .passthrough(),
-} as const;
-
-const refToolInputSchema = z.union([
-  refOperationSchemas.add,
-  refOperationSchemas.remove,
-  refOperationSchemas.list,
-  refOperationSchemas.update,
-  refOperationSchemas.inspect,
-  refOperationSchemas.call,
-  refOperationSchemas.auth,
-  refOperationSchemas["auth-status"],
-  refOperationSchemas["refresh-token"],
-  refOperationSchemas.resources,
-  refOperationSchemas.read,
-]);
-const refToolInputJsonSchema = zodToOpenAiJsonSchema(
-  refToolInputSchema,
-) as JsonSchema;
-
-function parseRefToolInput(
-  input: Record<string, unknown>,
-): Record<string, unknown> {
-  const op = typeof input.operation === "string" ? input.operation : undefined;
-  const schema =
-    op && op in refOperationSchemas
-      ? refOperationSchemas[op as keyof typeof refOperationSchemas]
-      : refToolInputSchema;
-  const result = schema.safeParse(input);
-  if (result.success) return result.data as Record<string, unknown>;
-
-  const operation = op ? `ref.${op}` : "ref";
-  throw new AdkError({
-    code: "TOOL_INPUT_INVALID",
-    message: `Invalid ${operation} input`,
-    hint: "The expected input schema is serialized in details.schema; operation-specific schema is in details.operationSchema.",
-    details: {
-      operation,
-      issues: result.error.issues.map((issue) => ({
-        path: issue.path.join("."),
-        message: issue.message,
-      })),
-      received: input,
-      schema: refToolInputJsonSchema,
-      ...(op &&
-        op in refOperationSchemas && {
-          operationSchema: zodToOpenAiJsonSchema(
-            refOperationSchemas[op as keyof typeof refOperationSchemas],
-          ),
-        }),
-    },
-  });
-}
-
-function withScopeSchema(
-  schema: JsonSchema,
-  scopeSchema: JsonSchema,
-): JsonSchema {
-  const clone = JSON.parse(JSON.stringify(schema)) as JsonSchema;
-  const visit = (value: unknown) => {
-    if (!value || typeof value !== "object") return;
-    if (Array.isArray(value)) {
-      for (const item of value) visit(item);
-      return;
-    }
-
-    const record = value as Record<string, unknown>;
-    const properties = record.properties as Record<string, unknown> | undefined;
-    if (properties?.scope) {
-      properties.scope = scopeSchema;
-    }
-    for (const child of Object.values(record)) {
-      visit(child);
-    }
-  };
-  visit(clone);
-  return clone;
-}
+import type { ToolContext, ToolDefinition } from "./types.js";
 
 export interface AdkToolsHooks<TCtx extends ToolContext = ToolContext> {
   /**
@@ -310,14 +68,97 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(
     name: "ref",
     description:
       "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 `name` (local identifier). If `name` is omitted on add, it defaults to `ref`. For every other operation, pass `name`.",
-    inputSchema: withScopeSchema(refToolInputJsonSchema, scopeSchema),
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        operation: {
+          type: "string",
+          enum: [
+            "add",
+            "remove",
+            "list",
+            "update",
+            "inspect",
+            "call",
+            "auth",
+            "auth-status",
+            "refresh-token",
+            "resources",
+            "read",
+          ],
+        },
+        scope: scopeSchema,
+        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 to look up the entry. On `add`, defaults to `ref` when omitted.",
+        },
+        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 parsedInput = parseRefToolInput(input);
       const adk = await resolveScope(
-        parsedInput.scope as string | undefined,
+        input.scope as string | undefined,
         ctx as TCtx,
       );
-      const op = parsedInput.operation as string;
+      const op = input.operation as string;
 
       switch (op) {
         case "add": {
@@ -325,24 +166,18 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(
           // other defaults to it. The stored entry always has an explicit
           // `name`, so downstream auth/callback state can distinguish the
           // canonical ref from the local connection handle.
-          const refValue = (parsedInput.ref ?? parsedInput.name) as
-            | string
-            | 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 nameValue = (parsedInput.name ?? refValue) as string;
-          const entry: Record<string, unknown> = {
-            ref: refValue,
-            name: nameValue,
-          };
-          if (parsedInput.scheme) entry.scheme = parsedInput.scheme;
-          if (parsedInput.url) entry.url = parsedInput.url;
-          if (parsedInput.sourceRegistry)
-            entry.sourceRegistry = parsedInput.sourceRegistry;
-          if (parsedInput.config) entry.config = parsedInput.config;
+          const nameValue = (input.name ?? refValue) as string;
+          const entry: Record<string, unknown> = { ref: refValue, name: nameValue };
+          if (input.scheme) entry.scheme = input.scheme;
+          if (input.url) entry.url = input.url;
+          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,
@@ -352,25 +187,25 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(
           };
         }
         case "remove":
-          return { removed: await adk.ref.remove(parsedInput.name as string) };
+          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(
-              parsedInput.name as string,
-              parsedInput as unknown as Partial<RefEntry>,
+              input.name as string,
+              input as unknown as Partial<RefEntry>,
             ),
           };
         case "inspect":
-          return await adk.ref.inspect(parsedInput.name as string, {
-            full: parsedInput.full as boolean,
+          return await adk.ref.inspect(input.name as string, {
+            full: input.full as boolean,
           });
         case "call":
           return await adk.ref.call(
-            parsedInput.name as string,
-            parsedInput.tool as string,
-            parsedInput.params as Record<string, unknown>,
+            input.name as string,
+            input.tool as string,
+            input.params as Record<string, unknown>,
           );
         case "auth": {
           const authOpts: {
@@ -378,31 +213,27 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(
             credentials?: Record<string, string>;
             stateContext?: Record<string, unknown>;
           } = {};
-          if (parsedInput.apiKey)
-            authOpts.apiKey = parsedInput.apiKey as string;
-          if (parsedInput.credentials)
-            authOpts.credentials = parsedInput.credentials as Record<
-              string,
-              string
-            >;
+          if (input.apiKey) authOpts.apiKey = input.apiKey as string;
+          if (input.credentials)
+            authOpts.credentials = input.credentials as Record<string, string>;
           if (opts.hooks?.getAuthStateContext) {
             authOpts.stateContext = await opts.hooks.getAuthStateContext(
-              parsedInput,
+              input,
               ctx as TCtx,
             );
           }
-          return await adk.ref.auth(parsedInput.name as string, authOpts);
+          return await adk.ref.auth(input.name as string, authOpts);
         }
         case "auth-status":
-          return await adk.ref.authStatus(parsedInput.name as string);
+          return await adk.ref.authStatus(input.name as string);
         case "refresh-token":
-          return await adk.ref.refreshToken(parsedInput.name as string);
+          return await adk.ref.refreshToken(input.name as string);
         case "resources":
-          return await adk.ref.resources(parsedInput.name as string);
+          return await adk.ref.resources(input.name as string);
         case "read":
           return await adk.ref.read(
-            parsedInput.name as string,
-            parsedInput.uris as string[],
+            input.name as string,
+            input.uris as string[],
           );
         default:
           throw new Error(`Unknown ref operation: ${op}`);

package/src/config-store.ts

@@ -521,7 +521,73 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
     return value;
   }
 
+  // ─────────────────────────────────────────────────────────────────────
+  // Credential resolution helpers
+  //
+  // Three callsites used to inline a `tryResolve`/`canResolve` closure
+  // (auth, authStatus, refreshToken) and two of them duplicated the
+  // client_id/client_secret lookup chain verbatim. Those chains MUST stay
+  // symmetric — if `auth` accepts a credential source, `refreshToken` has
+  // to read from the same source or refresh silently no-ops on every ref
+  // `auth` succeeded against. Centralising it here removes that drift
+  // risk.
+  // ─────────────────────────────────────────────────────────────────────
+
+  type OAuthServerMetadata = import("./mcp-client.js").OAuthServerMetadata;
+
+  interface CredentialResolverContext {
+    name: string;
+    entry: RefEntry;
+    security: SecuritySchemeSummary | null;
+  }
+
+  /**
+   * Build a `tryResolve(field, oauthMetadata?)` function bound to a
+   * specific ref + entry + security context. Wraps the host-injected
+   * `resolveCredentials` callback (e.g. atlas's env/static/tenant chain
+   * for first-party agents). Errors propagate to the caller.
+   */
+  function makeTryResolve(ctx: CredentialResolverContext) {
+    return async (
+      field: string,
+      oauthMetadata?: OAuthServerMetadata | null,
+    ): Promise<string | null> => {
+      const resolve = options.resolveCredentials;
+      if (!resolve) return null;
+      return resolve({
+        ref: ctx.name,
+        field,
+        entry: ctx.entry,
+        security: ctx.security,
+        oauthMetadata,
+      });
+    };
+  }
 
+  /**
+   * Resolve OAuth client credentials (client_id + client_secret) for a
+   * ref. Walks: `resolveCredentials` callback → per-ref VCS storage.
+   * Used by both `auth` (initial OAuth flow) and `refreshToken` (token
+   * refresh) — must be a single function so the two paths can never
+   * disagree about where credentials live.
+   *
+   * Returns null when no client_id is available anywhere; caller decides
+   * whether to attempt dynamic registration (`auth`) or bail (`refresh`).
+   */
+  async function resolveOAuthClient(
+    ctx: CredentialResolverContext & { metadata?: OAuthServerMetadata | null },
+  ): Promise<{ clientId: string; clientSecret?: string } | null> {
+    const tryResolve = makeTryResolve(ctx);
+    const clientId =
+      (await tryResolve("client_id", ctx.metadata)) ??
+      (await readRefSecret(ctx.name, "client_id"));
+    if (!clientId) return null;
+    const clientSecret =
+      (await tryResolve("client_secret", ctx.metadata)) ??
+      (await readRefSecret(ctx.name, "client_secret")) ??
+      undefined;
+    return { clientId, ...(clientSecret && { clientSecret }) };
+  }
 
   const PENDING_OAUTH_PATH = "pending-oauth.json";
 
@@ -1806,12 +1872,12 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
       }
 
       const configKeys = Object.keys(entry.config ?? {});
-      const resolve = options.resolveCredentials;
-
-      async function canResolve(field: string, oauthMetadata?: import("./mcp-client.js").OAuthServerMetadata | null): Promise<boolean> {
-        if (!resolve || !entry) return false;
-        const val = await resolve({ ref: name, field, entry, security, oauthMetadata });
-        return val !== null;
+      const tryResolveField = makeTryResolve({ name, entry, security });
+      async function canResolve(
+        field: string,
+        oauthMetadata?: OAuthServerMetadata | null,
+      ): Promise<boolean> {
+        return (await tryResolveField(field, oauthMetadata)) !== null;
       }
 
       const fields: Record<string, CredentialField> = {};
@@ -1944,12 +2010,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
 
       const status = await ref.authStatus(name);
       const security = status.security;
-      const resolve = options.resolveCredentials;
-
-      async function tryResolve(field: string, oauthMetadata?: import("./mcp-client.js").OAuthServerMetadata | null): Promise<string | null> {
-        if (!resolve) return null;
-        return resolve({ ref: name, field, entry: entry!, security, oauthMetadata });
-      }
+      const tryResolve = makeTryResolve({ name, entry, security });
 
       if (!security || security.type === "none") {
         return { type: "none", complete: true };
@@ -2101,11 +2162,14 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         const redirectUri = callbackUrl();
 
         // Resolve client credentials: callback → stored → dynamic registration
-        let clientId = await tryResolve("client_id", metadata)
-          ?? await readRefSecret(name, "client_id");
-        let clientSecret = await tryResolve("client_secret", metadata)
-          ?? await readRefSecret(name, "client_secret")
-          ?? undefined;
+        const fromHelper = await resolveOAuthClient({
+          name,
+          entry,
+          security,
+          metadata,
+        });
+        let clientId: string | undefined = fromHelper?.clientId;
+        let clientSecret: string | undefined = fromHelper?.clientSecret;
 
         if (!clientId && metadata.registration_endpoint) {
           const supportedAuthMethods = metadata.token_endpoint_auth_methods_supported ?? ["none"];
@@ -2365,22 +2429,28 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
       const refreshToken = await readRefSecret(name, "refresh_token");
       if (!refreshToken) return null;
 
-      // Read client credentials
-      const clientId = await readRefSecret(name, "client_id");
-      if (!clientId) return null;
-      const clientSecret = await readRefSecret(name, "client_secret");
-
-      // Get the agent's token endpoint from its security metadata
+      // Resolve token endpoint + OAuth client via the host's
+      // `resolveCredentials` chain. Same chain `auth` uses (see
+      // `resolveOAuthClient`) — kept symmetric so refresh works on every
+      // ref `auth` works on, including first-party registry-hosted
+      // clients whose creds live in env / tenant scope, not the user's
+      // per-ref config.
       const entry = await ref.get(name);
       if (!entry) return null;
 
-      const info = await ref.inspect(name);
-      const security = (info as any)?.security as Record<string, unknown> | undefined;
-      const flows = (security?.flows as Record<string, Record<string, unknown>> | undefined);
+      const status = await ref.authStatus(name);
+      const security = status.security;
+      const flows = security && "flows" in security
+        ? (security as { flows?: Record<string, { tokenUrl?: string; refreshUrl?: string }> }).flows
+        : undefined;
       const authCodeFlow = flows?.authorizationCode;
-      const tokenUrl = (authCodeFlow?.refreshUrl ?? authCodeFlow?.tokenUrl) as string | undefined;
+      const tokenUrl = authCodeFlow?.refreshUrl ?? authCodeFlow?.tokenUrl;
       if (!tokenUrl) return null;
 
+      const oauthClient = await resolveOAuthClient({ name, entry, security });
+      if (!oauthClient) return null;
+      const { clientId, clientSecret } = oauthClient;
+
       // POST to the token endpoint with grant_type=refresh_token
       const body = new URLSearchParams({
         grant_type: "refresh_token",

package/src/ref-naming.test.ts

@@ -10,7 +10,7 @@
 import { describe, expect, test } from "bun:test";
 import { createAdkTools } from "./adk-tools";
 import type { FsStore } from "./agent-definitions/config";
-import { createAdk, createAgentRegistry, defineAgent } from "./index";
+import { createAdk } from "./index";
 import type { ToolContext } from "./types";
 
 function createMemoryFs(): FsStore {
@@ -326,54 +326,6 @@ describe("ref tool — add operation defaults ref to name", () => {
     const raw = await fs.readFile("consumer-config.json");
     expect(raw).toBeNull();
   });
-
-  test("invalid add input returns schema details through registry call", async () => {
-    const fs = createMemoryFs();
-    const adk = createAdk(fs);
-    const refTool = makeRefTool(adk);
-    const registry = createAgentRegistry();
-    registry.register(
-      defineAgent({
-        path: "@config",
-        entrypoint: "Config agent",
-        tools: [refTool],
-        visibility: "public",
-      }),
-    );
-
-    const response = await registry.call({
-      action: "execute_tool",
-      path: "@config",
-      tool: "ref",
-      params: {
-        operation: "add",
-        ref: "google-calendar",
-      },
-    });
-
-    expect(response.success).toBe(false);
-    if (response.success) throw new Error("expected invalid input error");
-    expect(response.code).toBe("TOOL_INPUT_INVALID");
-    expect(response.error).toContain("Invalid ref.add input");
-    expect(response.details?.issues).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({
-          path: "sourceRegistry",
-        }),
-      ]),
-    );
-    expect(response.details?.schema).toMatchObject({
-      anyOf: expect.any(Array),
-    });
-    expect(response.details?.operationSchema).toMatchObject({
-      type: "object",
-    });
-    expect(response.hint).toContain("details.schema");
-    expect(response.details).not.toHaveProperty("examples");
-    expect(JSON.stringify(response.details?.operationSchema)).toContain(
-      "sourceRegistry",
-    );
-  });
 });
 
 describe("ref tool — auth state hook", () => {