@slashfi/agents-sdk 0.77.1 → 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> {
   /**
@@ -68,97 +310,14 @@ 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: {
-      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"],
-    },
+    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": {
@@ -166,18 +325,24 @@ 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 = (input.ref ?? input.name) as string | undefined;
+          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 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 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,
@@ -187,25 +352,25 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(
           };
         }
         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: {
@@ -213,27 +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(
-              input,
+              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/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 } from "./index";
+import { createAdk, createAgentRegistry, defineAgent } from "./index";
 import type { ToolContext } from "./types";
 
 function createMemoryFs(): FsStore {
@@ -326,6 +326,54 @@ 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", () => {

package/src/registry.ts

@@ -5,6 +5,7 @@
  */
 
 import { dirname, resolve } from "node:path";
+import { AdkError } from "./adk-error.js";
 import type { AgentEvent, BaseEvent, CallAgentToolCallEvent, CustomEventMap, EventCallback, EventType, ListAgentsResult, ListAgentsToolCallEvent } from "./events.js";
 import { createEventBus } from "./events.js";
 import type { Logger } from "./logger.js";
@@ -39,6 +40,33 @@ const DEFAULT_SUPPORTED_ACTIONS: AgentAction[] = [
   "read_resources",
 ];
 
+function adkErrorFields(
+  err: unknown,
+): { code: string; hint: string; details: Record<string, unknown> } | null {
+  if (err instanceof AdkError) {
+    return { code: err.code, hint: err.hint, details: err.details };
+  }
+  if (!err || typeof err !== "object") return null;
+  const candidate = err as {
+    name?: unknown;
+    code?: unknown;
+    hint?: unknown;
+    details?: unknown;
+  };
+  return candidate.name === "AdkError" &&
+    typeof candidate.code === "string" &&
+    typeof candidate.hint === "string" &&
+    !!candidate.details &&
+    typeof candidate.details === "object" &&
+    !Array.isArray(candidate.details)
+    ? {
+        code: candidate.code,
+        hint: candidate.hint,
+        details: candidate.details as Record<string, unknown>,
+      }
+    : null;
+}
+
 /**
  * Estimate the token count for a tool schema when serialized to JSON.
  * Uses a rough heuristic: ~4 characters per token (conservative estimate
@@ -760,10 +788,15 @@ export function createAgentRegistry(
                 })
                 .catch(() => {}); // don't let emit error mask tool error
 
+              const adkErr = adkErrorFields(err);
               return {
                 success: false,
                 error: err instanceof Error ? err.message : String(err),
-                code: "TOOL_EXECUTION_ERROR",
+                code: adkErr?.code ?? "TOOL_EXECUTION_ERROR",
+                ...(adkErr && {
+                  hint: adkErr.hint,
+                  details: adkErr.details,
+                }),
               } as CallAgentErrorResponse;
             }
 
@@ -784,11 +817,16 @@ export function createAgentRegistry(
             } as CallAgentExecuteToolResponse;
           } catch (outerErr) {
             // Catch-all for unexpected errors (e.g., emit failures)
+            const adkErr = adkErrorFields(outerErr);
             return {
               success: false,
               error:
                 outerErr instanceof Error ? outerErr.message : String(outerErr),
-              code: "TOOL_EXECUTION_ERROR",
+              code: adkErr?.code ?? "TOOL_EXECUTION_ERROR",
+              ...(adkErr && {
+                hint: adkErr.hint,
+                details: adkErr.details,
+              }),
             } as CallAgentErrorResponse;
           }
         }

package/src/types.ts

@@ -4,8 +4,8 @@
  * Defines the fundamental types for agent definitions, tools, and contexts.
  */
 
-import type { EventCallback, EventType } from "./events.js";
 import type { AgentAction, CallerType } from "./call-agent-schema.js";
+import type { EventCallback, EventType } from "./events.js";
 
 /** Internal listener entry stored on agents/tools */
 export interface ListenerEntry {
@@ -22,7 +22,15 @@ export interface ListenerEntry {
  * JSON Schema definition for tool input parameters.
  */
 export type JsonSchema = {
-  type: "object" | "array" | "string" | "number" | "integer" | "boolean" | "null" | string[];
+  type:
+    | "object"
+    | "array"
+    | "string"
+    | "number"
+    | "integer"
+    | "boolean"
+    | "null"
+    | string[];
   properties?: Record<string, JsonSchema>;
   items?: JsonSchema;
   required?: string[];
@@ -293,7 +301,7 @@ export type SecurityScheme =
  * directory-level overview (e.g., in list_agents responses).
  */
 export interface SecuritySchemeSummary {
-  type: SecurityScheme['type'];
+  type: SecurityScheme["type"];
   [key: string]: unknown;
 }
 
@@ -710,7 +718,7 @@ export interface AgentDefinition<TContext extends ToolContext = ToolContext> {
    * - 'direct': registry hosts and serves this agent's tools (default)
    * - 'redirect': registry catalogs this agent but clients connect to `upstream` directly
    */
-  mode?: 'direct' | 'redirect';
+  mode?: "direct" | "redirect";
 
   /**
    * Upstream URL for redirect-mode agents.
@@ -861,6 +869,8 @@ export interface CallAgentErrorResponse {
   success: false;
   error: string;
   code?: string;
+  hint?: string;
+  details?: Record<string, unknown>;
 }
 
 /** Union of all response types */
@@ -942,5 +952,10 @@ export type ServerSource =
   | string
   | { command: string; args?: string[]; env?: Record<string, string> }
   | { url: string; headers?: Record<string, string> }
-  | { spawn: string; args?: string[]; env?: Record<string, string>; port?: number; endpoint?: string };
-
+  | {
+      spawn: string;
+      args?: string[];
+      env?: Record<string, string>;
+      port?: number;
+      endpoint?: string;
+    };