@slashfi/agents-sdk 0.33.1 → 0.34.0

package/src/call-agent-schema.test.ts

@@ -0,0 +1,306 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import {
+  stripNulls,
+  nullTolerant,
+  zodToOpenAiJsonSchema,
+  callAgentValidationSchema,
+  callAgentRequestSchema,
+  listAgentsValidationSchema,
+} from "./call-agent-schema";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// stripNulls
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("stripNulls", () => {
+  test("converts null to undefined", () => {
+    expect(stripNulls(null)).toBe(undefined);
+  });
+
+  test("passes through primitives", () => {
+    expect(stripNulls("hello")).toBe("hello");
+    expect(stripNulls(42)).toBe(42);
+    expect(stripNulls(true)).toBe(true);
+    expect(stripNulls(undefined)).toBe(undefined);
+  });
+
+  test("strips null from flat objects", () => {
+    expect(stripNulls({ a: null, b: "hello" })).toEqual({ b: "hello" });
+  });
+
+  test("strips null from nested objects", () => {
+    expect(stripNulls({ a: { b: null, c: "ok" }, d: null })).toEqual({
+      a: { c: "ok" },
+    });
+  });
+
+  test("strips null from arrays", () => {
+    expect(stripNulls([1, null, 3])).toEqual([1, undefined, 3]);
+  });
+
+  test("handles deeply nested structures", () => {
+    const input = {
+      action: "execute_tool",
+      path: "/agents/@test",
+      tool: "my_tool",
+      params: null,
+      callerId: null,
+      callerType: null,
+      metadata: { nested: null, keep: "this" },
+    };
+    const result = stripNulls(input) as Record<string, unknown>;
+    expect(result.action).toBe("execute_tool");
+    expect(result.path).toBe("/agents/@test");
+    expect(result.params).toBe(undefined);
+    expect(result.callerId).toBe(undefined);
+    expect(result.callerType).toBe(undefined);
+    expect(result.metadata).toEqual({ keep: "this" });
+  });
+
+  test("handles empty objects and arrays", () => {
+    expect(stripNulls({})).toEqual({});
+    expect(stripNulls([])).toEqual([]);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// nullTolerant
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("nullTolerant", () => {
+  const schema = z.object({
+    name: z.string().optional(),
+    count: z.number().optional(),
+    tags: z.array(z.string()).optional(),
+    nested: z
+      .object({
+        value: z.string().optional(),
+      })
+      .optional(),
+  });
+
+  test("original schema rejects null", () => {
+    expect(() => schema.parse({ name: null })).toThrow();
+    expect(() => schema.parse({ tags: null })).toThrow();
+    expect(() => schema.parse({ count: null })).toThrow();
+  });
+
+  test("tolerant schema accepts null for optional string", () => {
+    const tolerant = nullTolerant(schema);
+    const result = tolerant.parse({ name: null });
+    expect(result).toEqual({});
+  });
+
+  test("tolerant schema accepts null for optional array", () => {
+    const tolerant = nullTolerant(schema);
+    const result = tolerant.parse({ tags: null });
+    expect(result).toEqual({});
+  });
+
+  test("tolerant schema accepts null for optional number", () => {
+    const tolerant = nullTolerant(schema);
+    const result = tolerant.parse({ count: null });
+    expect(result).toEqual({});
+  });
+
+  test("tolerant schema accepts null for nested optional", () => {
+    const tolerant = nullTolerant(schema);
+    const result = tolerant.parse({ nested: { value: null } });
+    expect(result).toEqual({ nested: {} });
+  });
+
+  test("tolerant schema still validates real values", () => {
+    const tolerant = nullTolerant(schema);
+    const result = tolerant.parse({
+      name: "test",
+      count: 5,
+      tags: ["a", "b"],
+    });
+    expect(result).toEqual({ name: "test", count: 5, tags: ["a", "b"] });
+  });
+
+  test("tolerant schema still rejects invalid types", () => {
+    const tolerant = nullTolerant(schema);
+    expect(() => tolerant.parse({ name: 123 })).toThrow();
+    expect(() => tolerant.parse({ count: "not a number" })).toThrow();
+    expect(() => tolerant.parse({ tags: "not an array" })).toThrow();
+  });
+
+  test("all nulls at once", () => {
+    const tolerant = nullTolerant(schema);
+    const result = tolerant.parse({
+      name: null,
+      count: null,
+      tags: null,
+      nested: null,
+    });
+    expect(result).toEqual({});
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// callAgentValidationSchema — real-world scenarios
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("callAgentValidationSchema", () => {
+  test("accepts execute_tool with null optional fields (the original bug)", () => {
+    const input = {
+      request: {
+        action: "execute_tool",
+        path: "/agents/@librarian",
+        tool: "search_skill",
+        params: { query: "agent registry" },
+        callerId: null,
+        callerType: null,
+        metadata: null,
+      },
+    };
+    const result = callAgentValidationSchema.safeParse(input);
+    expect(result.success).toBe(true);
+  });
+
+  test("accepts describe_tools with tools: null (the original bug)", () => {
+    const input = {
+      request: {
+        action: "describe_tools",
+        path: "/agents/@librarian",
+        tools: null,
+        callerId: null,
+        callerType: null,
+        metadata: null,
+      },
+    };
+    const result = callAgentValidationSchema.safeParse(input);
+    expect(result.success).toBe(true);
+  });
+
+  test("accepts invoke with null sessionId and branchAttributes", () => {
+    const input = {
+      request: {
+        action: "invoke",
+        path: "/agents/@compactor",
+        prompt: "Hello",
+        sessionId: null,
+        branchAttributes: null,
+        callerId: null,
+        callerType: null,
+        metadata: null,
+      },
+    };
+    const result = callAgentValidationSchema.safeParse(input);
+    expect(result.success).toBe(true);
+  });
+
+  test("accepts ask with null optional fields", () => {
+    const input = {
+      request: {
+        action: "ask",
+        path: "/agents/@worker",
+        prompt: "What time is it?",
+        sessionId: null,
+        branchAttributes: null,
+        callerId: null,
+        callerType: null,
+        metadata: null,
+      },
+    };
+    const result = callAgentValidationSchema.safeParse(input);
+    expect(result.success).toBe(true);
+  });
+
+  test("accepts list_resources with null optional fields", () => {
+    const input = {
+      request: {
+        action: "list_resources",
+        path: "/agents/@agent-fs",
+        callerId: null,
+        callerType: null,
+        metadata: null,
+      },
+    };
+    const result = callAgentValidationSchema.safeParse(input);
+    expect(result.success).toBe(true);
+  });
+
+  test("accepts read_resources with null optional fields", () => {
+    const input = {
+      request: {
+        action: "read_resources",
+        path: "/agents/@agent-fs",
+        uris: ["AUTH.md"],
+        callerId: null,
+        callerType: null,
+        metadata: null,
+      },
+    };
+    const result = callAgentValidationSchema.safeParse(input);
+    expect(result.success).toBe(true);
+  });
+
+  test("still rejects truly invalid input", () => {
+    const result = callAgentValidationSchema.safeParse({
+      request: {
+        action: "execute_tool",
+        // missing required 'path' and 'tool'
+      },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  test("still rejects unknown action", () => {
+    const result = callAgentValidationSchema.safeParse({
+      request: {
+        action: "unknown_action",
+        path: "/agents/@test",
+      },
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// listAgentsValidationSchema
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("listAgentsValidationSchema", () => {
+  test("accepts all-null optional fields", () => {
+    const result = listAgentsValidationSchema.parse({
+      query: null,
+      limit: null,
+      cursor: null,
+    });
+    expect(result).toEqual({});
+  });
+
+  test("accepts mix of null and real values", () => {
+    const result = listAgentsValidationSchema.parse({
+      query: "notion",
+      limit: null,
+      cursor: null,
+    });
+    expect(result).toEqual({ query: "notion" });
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// zodToOpenAiJsonSchema
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("zodToOpenAiJsonSchema", () => {
+  test("produces JSON schema with nullable optional fields", () => {
+    const schema = z.object({
+      required: z.string(),
+      optional: z.string().optional(),
+    });
+    const jsonSchema = zodToOpenAiJsonSchema(schema) as any;
+
+    // Required field should be in required array
+    expect(jsonSchema.required).toContain("required");
+    // Optional field should also be required (openAi convention)
+    expect(jsonSchema.required).toContain("optional");
+    // Optional field should allow null
+    const optProp = jsonSchema.properties.optional;
+    expect(optProp.anyOf || optProp.type).toBeTruthy();
+  });
+});

package/src/call-agent-schema.ts

@@ -12,7 +12,69 @@
  * Response types live in types.ts (they're output shapes, not validated input).
  */
 
-import { z } from "zod";
+import { z, type ZodTypeAny } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// OpenAI null-tolerance transform
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Recursively strip null values from an object, converting them to undefined.
+ * This is the inverse of zod-to-json-schema's openAi target behavior, which
+ * converts .optional() fields to nullable+required in JSON Schema.
+ *
+ * Used as a z.preprocess() step so that Zod's .optional() (which accepts
+ * undefined but not null) works correctly with LLM outputs that send null
+ * for "no value" per the OpenAI function calling convention.
+ */
+export function stripNulls(obj: unknown): unknown {
+  if (obj === null) return undefined;
+  if (Array.isArray(obj)) return obj.map(stripNulls);
+  if (typeof obj === "object") {
+    return Object.fromEntries(
+      Object.entries(obj as Record<string, unknown>).map(([k, v]) => [
+        k,
+        stripNulls(v),
+      ]),
+    );
+  }
+  return obj;
+}
+
+/**
+ * Wrap a Zod schema with a preprocess step that converts null → undefined.
+ * This makes the schema "null-tolerant" — matching what the OpenAI JSON Schema
+ * target promises to LLMs (nullable fields) while keeping Zod's .optional()
+ * semantics internally.
+ *
+ * @example
+ * ```ts
+ * const schema = z.object({ name: z.string().optional() });
+ * const tolerant = nullTolerant(schema);
+ * tolerant.parse({ name: null }); // { name: undefined } — no error
+ * ```
+ */
+export function nullTolerant<T extends ZodTypeAny>(schema: T) {
+  return z.preprocess(stripNulls, schema) as unknown as T;
+}
+
+/**
+ * Convert a Zod schema to JSON Schema using the OpenAI target,
+ * which makes all optional fields nullable+required.
+ *
+ * This is the standard way to generate input schemas for MCP tools
+ * that will be called by LLMs.
+ */
+export function zodToOpenAiJsonSchema(
+  schema: ZodTypeAny,
+): Record<string, unknown> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return zodToJsonSchema(schema as any, { target: "openAi" }) as Record<
+    string,
+    unknown
+  >;
+}
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Base schemas
@@ -85,12 +147,20 @@ export const loadActionSchema = callAgentBaseSchema.extend({
 
 /** List resources: discover available resources on an agent */
 export const listResourcesActionSchema = callAgentBaseSchema.extend({
-  action: z.literal("list_resources").describe("List all resources available on an agent — docs, auth instructions, config schemas, etc."),
+  action: z
+    .literal("list_resources")
+    .describe(
+      "List all resources available on an agent — docs, auth instructions, config schemas, etc.",
+    ),
 });
 
 /** Read resources: fetch one or more resources by URI */
 export const readResourcesActionSchema = callAgentBaseSchema.extend({
-  action: z.literal("read_resources").describe("Fetch one or more resources by URI. Use list_resources first to discover available URIs."),
+  action: z
+    .literal("read_resources")
+    .describe(
+      "Fetch one or more resources by URI. Use list_resources first to discover available URIs.",
+    ),
   uris: z
     .array(z.string())
     .describe("Resource URIs to read (e.g., ['AUTH.md'])"),
@@ -140,15 +210,13 @@ export type CallerType = z.infer<typeof callerTypeSchema>;
 /** All supported action strings as a const array. */
 export const CALL_AGENT_ACTIONS: AgentAction[] =
   callAgentRequestSchema.options.map(
-    (s) => (s.shape as { action: z.ZodLiteral<AgentAction> }).action.value
+    (s) => (s.shape as { action: z.ZodLiteral<AgentAction> }).action.value,
   );
 
 // ─────────────────────────────────────────────────────────────────────────────
 // JSON Schema for MCP (derived from zod)
 // ─────────────────────────────────────────────────────────────────────────────
 
-import { zodToJsonSchema } from "zod-to-json-schema";
-
 /**
  * Zod schema for the full MCP tool input (wraps request in an outer object).
  * This is the schema that gets converted to JSON Schema for the LLM.
@@ -163,10 +231,17 @@ export const callAgentToolInputSchema = z.object({
  *
  * Fully derived from the zod schemas — no hand-written JSON Schema.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const callAgentInputSchema = zodToJsonSchema(
-  callAgentToolInputSchema as any,
-  { target: "openAi" }
+export const callAgentInputSchema = zodToOpenAiJsonSchema(
+  callAgentToolInputSchema,
+);
+
+/**
+ * Null-tolerant validation schema for `call_agent`.
+ * Accepts null values where the JSON Schema promises nullable,
+ * converting them to undefined before Zod validation.
+ */
+export const callAgentValidationSchema = nullTolerant(
+  callAgentToolInputSchema,
 );
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -183,9 +258,7 @@ export const listAgentsToolInputSchema = z.object({
   limit: z
     .number()
     .optional()
-    .describe(
-      "Maximum number of results per page (default: 20)",
-    ),
+    .describe("Maximum number of results per page (default: 20)"),
   cursor: z
     .string()
     .optional()
@@ -196,8 +269,10 @@ export const listAgentsToolInputSchema = z.object({
 
 export type ListAgentsInput = z.infer<typeof listAgentsToolInputSchema>;
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const listAgentsInputSchema = zodToJsonSchema(
-  listAgentsToolInputSchema as any,
-  { target: "openAi" }
+export const listAgentsInputSchema = zodToOpenAiJsonSchema(
+  listAgentsToolInputSchema,
+);
+
+export const listAgentsValidationSchema = nullTolerant(
+  listAgentsToolInputSchema,
 );

package/src/index.ts

@@ -384,6 +384,8 @@ export type { IntrospectOptions } from "./introspect.js";
 export {
   callAgentInputSchema,
   callAgentRequestSchema,
+  callAgentValidationSchema,
+  callAgentToolInputSchema,
   invokeActionSchema,
   askActionSchema,
   executeToolActionSchema,
@@ -393,6 +395,10 @@ export {
   readResourcesActionSchema,
   callerTypeSchema,
   CALL_AGENT_ACTIONS,
+  nullTolerant,
+  stripNulls,
+  zodToOpenAiJsonSchema,
+  listAgentsValidationSchema,
 } from "./call-agent-schema.js";
 
 // ============================================

package/src/registry-consumer.ts

@@ -229,8 +229,13 @@ type ListAgentsEntry = Omit<AgentListing, "publisher" | "tools"> & {
   tools?: Array<{ name: string; description?: string } | string>;
 };
 
-/** Response shape from list_agents — an array of agent entries. */
-type ListAgentsResponse = ListAgentsEntry[];
+/** Response shape from list_agents — wrapped object with agents array. */
+type ListAgentsResponse = {
+  agents: ListAgentsEntry[];
+  total?: number;
+  nextCursor?: string;
+  success?: boolean;
+};
 
 // ============================================
 // Secret Resolver
@@ -590,7 +595,7 @@ export async function createRegistryConsumer(
     const mcpUrl =
       configuration.call_endpoint ?? registry.url.replace(/\/$/, "");
 
-    const agents = await callMcpTool(
+    const response = await callMcpTool(
       mcpUrl,
       "list_agents",
       query ? { query } : {},
@@ -601,6 +606,8 @@ export async function createRegistryConsumer(
       fetchFn,
     ) as ListAgentsResponse;
 
+    const agents = response.agents ?? [];
+
     return agents.map((agent) => ({
       ...agent,
       ...agent,

package/src/server.ts

@@ -48,8 +48,11 @@ import type { AgentDefinition, CallAgentRequest } from "./types.js";
 
 import {
   callAgentInputSchema,
+  callAgentValidationSchema,
   listAgentsInputSchema,
-  listAgentsToolInputSchema,
+  listAgentsValidationSchema,
+  nullTolerant,
+  zodToOpenAiJsonSchema,
 } from "./call-agent-schema.js";
 
 // ============================================
@@ -146,6 +149,24 @@ export interface AgentServerOptions {
    * ```
    */
   resolveAuth?: (req: Request) => Promise<ResolvedAuth | null>;
+  /**
+   * Schema overrides for built-in MCP tools.
+   * When provided, these replace the default schemas for both
+   * JSON Schema generation (what LLMs see) and runtime validation.
+   *
+   * Schemas must be Zod schemas that are supersets of the defaults
+   * (e.g., extending the base action schemas with additional fields).
+   *
+   * The server automatically:
+   * - Converts to JSON Schema (openAi target) for tools/list
+   * - Wraps with nullTolerant() for validation
+   */
+  schemas?: {
+    /** Override call_agent tool input schema (wraps callAgentRequestSchema) */
+    callAgent?: import("zod").ZodTypeAny;
+    /** Override list_agents tool input schema */
+    listAgents?: import("zod").ZodTypeAny;
+  };
   /**
    * Registry capabilities — advertised in MCP initialize response.
    * When set, this server identifies as an agent registry (superset of MCP).
@@ -437,19 +458,23 @@ function resolveAgent(
 // MCP Tool Definitions
 // ============================================
 
-function getToolDefinitions() {
+function getToolDefinitions(schemas?: AgentServerOptions["schemas"]) {
   return [
     {
       name: "call_agent",
       description:
         "Execute a tool on a registered agent. Provide the agent path and tool name.\n\nSupported actions:\n- invoke: Fire-and-forget agent invocation\n- ask: Invoke and wait for response\n- execute_tool: Call a specific tool on an agent\n- describe_tools: Get tool schemas for an agent\n- load: Get agent definition/system prompt\n- list_resources: List all resources available on an agent (docs, auth instructions, config schemas, etc.)\n- read_resources: Fetch one or more resources by URI",
-      inputSchema: callAgentInputSchema,
+      inputSchema: schemas?.callAgent
+        ? zodToOpenAiJsonSchema(schemas.callAgent)
+        : callAgentInputSchema,
     },
     {
       name: "list_agents",
       description:
         "List all registered agents and their available tools. Optionally search/filter by query using BM25 ranking.",
-      inputSchema: listAgentsInputSchema,
+      inputSchema: schemas?.listAgents
+        ? zodToOpenAiJsonSchema(schemas.listAgents)
+        : listAgentsInputSchema,
     },
   ];
 }
@@ -473,6 +498,15 @@ export function createAgentServer(
     oauthIdentityProvider,
   } = options;
 
+  // Build tool definitions and validation schemas from overrides
+  const toolDefs = getToolDefinitions(options.schemas);
+  const callAgentValidate = options.schemas?.callAgent
+    ? nullTolerant(options.schemas.callAgent)
+    : callAgentValidationSchema;
+  const listAgentsValidate = options.schemas?.listAgents
+    ? nullTolerant(options.schemas.listAgents)
+    : listAgentsValidationSchema;
+
   // OIDC sign-in handler (if configured)
   const oidcSignIn = options.oidcProvider
     ? createOIDCSignIn(options.oidcProvider)
@@ -518,7 +552,7 @@ export function createAgentServer(
 
       case "tools/list":
         return jsonRpcSuccess(request.id, {
-          tools: getToolDefinitions(),
+          tools: toolDefs,
         });
 
       case "tools/call": {
@@ -562,7 +596,11 @@ export function createAgentServer(
   ) {
     switch (toolName) {
       case "call_agent": {
-        const req = (args.request ?? args) as CallAgentRequest;
+        // Validate + strip nulls (OpenAI convention: null = absent)
+        const parsed = callAgentValidate.safeParse(args);
+        const req = (parsed.success
+          ? (parsed.data as Record<string, unknown>).request ?? parsed.data
+          : (args.request ?? args)) as CallAgentRequest;
 
         // Inject auth context
         if (auth) {
@@ -597,7 +635,7 @@ export function createAgentServer(
 
       case "list_agents": {
         const { query: listQuery, limit: listLimit, cursor: listCursor } =
-          listAgentsToolInputSchema.parse(args);
+          listAgentsValidate.parse(args);
         const agents = registry.list();
         let visible = agents.filter((agent) => canSeeAgent(agent, auth));