@slashfi/agents-sdk 0.77.0 → 0.77.2

package/src/adk-tools.ts

@@ -17,10 +17,252 @@
  * ```
  */
 
+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 { ToolContext, ToolDefinition } from "./types.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;
+}
 
 export interface AdkToolsHooks<TCtx extends ToolContext = ToolContext> {
   /**
@@ -30,10 +272,11 @@ export interface AdkToolsHooks<TCtx extends ToolContext = ToolContext> {
    *
    * @example
    * ```ts
-   * getAuthStateContext: async (ctx) => ({ tid: ctx.tenantId, uid: ctx.userId })
+   * getAuthStateContext: async (input, ctx) => ({ tid: ctx.tenantId, uid: ctx.userId, name: input.name })
    * ```
    */
   getAuthStateContext?: (
+    input: Record<string, unknown>,
     ctx: TCtx,
   ) => Record<string, unknown> | Promise<Record<string, unknown>>;
 }
@@ -66,154 +309,68 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(
   const refTool = defineTool({
     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 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",
-          ],
-        },
-        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 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"],
-    },
+      "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),
     execute: async (input: Record<string, unknown>, ctx) => {
+      const parsedInput = parseRefToolInput(input);
       const adk = await resolveScope(
-        input.scope as string | undefined,
+        parsedInput.scope as string | undefined,
         ctx as TCtx,
       );
-      const op = input.operation as string;
+      const op = parsedInput.operation as string;
 
       switch (op) {
         case "add": {
           // 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;
+          // 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;
           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;
-          // 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 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 { security } = await adk.ref.add(entry as unknown as RefEntry);
           return {
             added: true,
             ref: refValue,
-            name: (entry.name ?? refValue) as string,
+            name: nameValue,
             security,
           };
         }
         case "remove":
-          return { removed: await adk.ref.remove(input.name as string) };
+          return { removed: await adk.ref.remove(parsedInput.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>,
+              parsedInput.name as string,
+              parsedInput 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(parsedInput.name as string, {
+            full: parsedInput.full as boolean,
           });
         case "call":
           return await adk.ref.call(
-            input.name as string,
-            input.tool as string,
-            input.params as Record<string, unknown>,
+            parsedInput.name as string,
+            parsedInput.tool as string,
+            parsedInput.params as Record<string, unknown>,
           );
         case "auth": {
           const authOpts: {
@@ -221,26 +378,31 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(
             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 (parsedInput.apiKey)
+            authOpts.apiKey = parsedInput.apiKey as string;
+          if (parsedInput.credentials)
+            authOpts.credentials = parsedInput.credentials as Record<
+              string,
+              string
+            >;
           if (opts.hooks?.getAuthStateContext) {
             authOpts.stateContext = await opts.hooks.getAuthStateContext(
+              parsedInput,
               ctx as TCtx,
             );
           }
-          return await adk.ref.auth(input.name as string, authOpts);
+          return await adk.ref.auth(parsedInput.name as string, authOpts);
         }
         case "auth-status":
-          return await adk.ref.authStatus(input.name as string);
+          return await adk.ref.authStatus(parsedInput.name as string);
         case "refresh-token":
-          return await adk.ref.refreshToken(input.name as string);
+          return await adk.ref.refreshToken(parsedInput.name as string);
         case "resources":
-          return await adk.ref.resources(input.name as string);
+          return await adk.ref.resources(parsedInput.name as string);
         case "read":
           return await adk.ref.read(
-            input.name as string,
-            input.uris as string[],
+            parsedInput.name as string,
+            parsedInput.uris as string[],
           );
         default:
           throw new Error(`Unknown ref operation: ${op}`);

package/src/adk.ts

@@ -110,7 +110,7 @@ Registry operations:
   adk registry auth <name> [--token <t>] [--api-key <k>] [--header <h>]
 
 Ref operations:
-  adk ref add <ref> [--registry <name>] [--as <alias>] [--url <url>] [--scheme mcp|https|registry]
+  adk ref add <ref> [--name <name>] [--registry <name>] [--url <url>] [--scheme mcp|https|registry]
   adk ref remove <name>
   adk ref list
   adk ref inspect <name> [--full]
@@ -351,15 +351,14 @@ async function runRef() {
   switch (op) {
     case "add": {
       const refArg = args[2];
-      if (!refArg) { console.error("Usage: adk ref add <ref> [--registry <name>] [--as <alias>]"); process.exit(1); }
-      const entry: Record<string, unknown> = { ref: refArg };
-      const alias = getArg("--as");
+      if (!refArg) { console.error("Usage: adk ref add <ref> [--name <name>] [--registry <name>]"); process.exit(1); }
+      const name = getArg("--name") ?? refArg;
+      const entry: Record<string, unknown> = { ref: refArg, name };
       const url = getArg("--url");
       const registryName = getArg("--registry");
       // Auto-detect: if no --registry and no --url, try default registry
       const effectiveRegistry = registryName ?? (url ? undefined : "public");
       const scheme = getArg("--scheme") ?? (effectiveRegistry ? "registry" : undefined);
-      if (alias) entry.as = alias;
       if (url) entry.url = url;
       if (scheme) entry.scheme = scheme;
       if (effectiveRegistry) {
@@ -370,15 +369,15 @@ async function runRef() {
       }
       try {
         const { security } = await adk.ref.add(entry as import("./define-config.js").RefEntry);
-        console.log(`Added ref: ${alias ?? refArg}`);
+        console.log(`Added ref: ${name}`);
         if (security && security.type !== "none") {
           console.log(`\n  Auth required: ${security.type}`);
-          console.log(`  Run: adk ref auth ${alias ?? refArg}`);
+          console.log(`  Run: adk ref auth ${name}`);
         }
 
         // Materialize local docs
         const configDir = process.env.ADK_CONFIG_DIR ?? join(homedir(), ".adk");
-        const refDisplayName = alias ?? refArg;
+        const refDisplayName = name;
         try {
           const result = await materializeRef(adk, refDisplayName, configDir);
           if (result.toolCount > 0) {

package/src/agent-definitions/config.ts

@@ -108,9 +108,9 @@ export function createConfigAgent(
           type: "string",
           description: 'Agent ref name (e.g. "notion", "linear")',
         },
-        as: {
+        name: {
           type: "string",
-          description: "Local alias (for multi-instance refs)",
+          description: "Local ref name. Defaults to ref when omitted.",
         },
         url: {
           type: "string",
@@ -132,7 +132,7 @@ export function createConfigAgent(
     execute: async (
       input: {
         ref: string;
-        as?: string;
+        name?: string;
         url?: string;
         config?: Record<string, string>;
         registry?: string;
@@ -141,28 +141,27 @@ export function createConfigAgent(
     ) => {
       const fs = getStore(ctx);
       const currentConfig = await readConfig(fs);
+      const name = input.name ?? input.ref;
 
-      const entry: RefEntry = {
+      const entry = {
         ref: input.ref,
-        ...(input.as && { as: input.as }),
+        name,
         ...(input.url && { url: input.url }),
         ...(input.config && { config: input.config }),
         ...(input.registry && { registry: input.registry }),
-      };
+      } as RefEntry;
 
-      // Upsert: find existing ref by name/alias, replace or append
-      const name = input.as ?? input.ref;
       const refs = currentConfig.refs ?? [];
-      const existingIdx = refs.findIndex((r) => {
+      const altName = name.startsWith("@") ? name.slice(1) : `@${name}`;
+      const duplicate = refs.some((r) => {
         const normalized = normalizeRef(r);
-        return normalized.name === name;
+        return normalized.name === name || normalized.name === altName;
       });
 
-      if (existingIdx >= 0) {
-        refs[existingIdx] = entry;
-      } else {
-        refs.push(entry);
+      if (duplicate) {
+        throw new Error(`Cannot add ref "${input.ref}" as "${name}": a ref with that name already exists`);
       }
+      refs.push(entry);
 
       currentConfig.refs = refs;
       await writeConfig(fs, currentConfig);
@@ -178,13 +177,13 @@ export function createConfigAgent(
   // ---- remove_ref ----
   const removeRefTool = defineTool({
     name: "remove_ref",
-    description: "Remove an agent ref from the consumer config by name or alias.",
+    description: "Remove an agent ref from the consumer config by name.",
     inputSchema: {
       type: "object" as const,
       properties: {
         name: {
           type: "string",
-          description: "Ref name or alias to remove",
+          description: "Ref name to remove",
         },
       },
       required: ["name"],