@slashfi/agents-sdk 0.22.0 → 0.23.1

package/dist/validate.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Zod schema for SerializedAgentDefinition.
+ *
+ * Validates definition.json files at runtime — JSON imports have no type safety,
+ * so this catches malformed definitions before they hit the registry.
+ *
+ * Used in:
+ *   - registry.register() — validate on ingest
+ *   - adk pack — validate after introspection
+ *   - adk publish — validate before shipping
+ */
+import { z } from "zod";
+export declare const SerializedToolSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    inputSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    name: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown> | undefined;
+}, {
+    description: string;
+    name: string;
+    outputSchema?: Record<string, unknown> | undefined;
+    inputSchema?: Record<string, unknown> | undefined;
+}>;
+export declare const SerializedAgentDefinitionSchema: z.ZodObject<{
+    path: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    version: z.ZodDefault<z.ZodString>;
+    visibility: z.ZodDefault<z.ZodEnum<["public", "private"]>>;
+    auth: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    serverSource: z.ZodOptional<z.ZodString>;
+    serverInfo: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        version: string;
+    }, {
+        name: string;
+        version: string;
+    }>>;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        inputSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        name: string;
+        inputSchema: Record<string, unknown>;
+        outputSchema?: Record<string, unknown> | undefined;
+    }, {
+        description: string;
+        name: string;
+        outputSchema?: Record<string, unknown> | undefined;
+        inputSchema?: Record<string, unknown> | undefined;
+    }>, "many">;
+    generatedAt: z.ZodOptional<z.ZodString>;
+    sdkVersion: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    path: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    version: z.ZodDefault<z.ZodString>;
+    visibility: z.ZodDefault<z.ZodEnum<["public", "private"]>>;
+    auth: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    serverSource: z.ZodOptional<z.ZodString>;
+    serverInfo: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        version: string;
+    }, {
+        name: string;
+        version: string;
+    }>>;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        inputSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        name: string;
+        inputSchema: Record<string, unknown>;
+        outputSchema?: Record<string, unknown> | undefined;
+    }, {
+        description: string;
+        name: string;
+        outputSchema?: Record<string, unknown> | undefined;
+        inputSchema?: Record<string, unknown> | undefined;
+    }>, "many">;
+    generatedAt: z.ZodOptional<z.ZodString>;
+    sdkVersion: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    path: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    version: z.ZodDefault<z.ZodString>;
+    visibility: z.ZodDefault<z.ZodEnum<["public", "private"]>>;
+    auth: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    serverSource: z.ZodOptional<z.ZodString>;
+    serverInfo: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        version: string;
+    }, {
+        name: string;
+        version: string;
+    }>>;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        inputSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        name: string;
+        inputSchema: Record<string, unknown>;
+        outputSchema?: Record<string, unknown> | undefined;
+    }, {
+        description: string;
+        name: string;
+        outputSchema?: Record<string, unknown> | undefined;
+        inputSchema?: Record<string, unknown> | undefined;
+    }>, "many">;
+    generatedAt: z.ZodOptional<z.ZodString>;
+    sdkVersion: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export type ValidationResult = {
+    ok: true;
+    definition: z.infer<typeof SerializedAgentDefinitionSchema>;
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * Validate a definition against the SerializedAgentDefinition schema.
+ *
+ * Returns either the validated definition or a list of human-readable errors.
+ */
+export declare function validateDefinition(input: unknown): ValidationResult;
+/**
+ * Validate and throw if invalid.
+ * Use in register() and pack/publish where failure should be fatal.
+ */
+export declare function assertValidDefinition(input: unknown, context?: string): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;EAO/B,CAAC;AAMH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAsB5B,CAAC;AAMjB,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAA;CAAE,GACzE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEpC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAUnE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAQ5E"}

package/dist/validate.js

@@ -0,0 +1,79 @@
+/**
+ * Zod schema for SerializedAgentDefinition.
+ *
+ * Validates definition.json files at runtime — JSON imports have no type safety,
+ * so this catches malformed definitions before they hit the registry.
+ *
+ * Used in:
+ *   - registry.register() — validate on ingest
+ *   - adk pack — validate after introspection
+ *   - adk publish — validate before shipping
+ */
+import { z } from "zod";
+// ============================================
+// Tool Schema
+// ============================================
+export const SerializedToolSchema = z.object({
+    name: z.string().min(1, "Tool name is required"),
+    description: z.string(),
+    inputSchema: z
+        .record(z.unknown())
+        .default({ type: "object", properties: {} }),
+    outputSchema: z.record(z.unknown()).optional(),
+});
+// ============================================
+// Agent Definition Schema
+// ============================================
+export const SerializedAgentDefinitionSchema = z
+    .object({
+    path: z.string().min(1, "Agent path is required"),
+    name: z.string().min(1, "Agent name is required"),
+    description: z.string().default(""),
+    version: z.string().default("1.0.0"),
+    visibility: z.enum(["public", "private"]).default("public"),
+    auth: z.record(z.unknown()).optional(),
+    serverSource: z.string().optional(),
+    serverInfo: z
+        .object({
+        name: z.string(),
+        version: z.string(),
+    })
+        .optional(),
+    tools: z
+        .array(SerializedToolSchema)
+        .min(1, "At least one tool is required"),
+    generatedAt: z.string().optional(),
+    sdkVersion: z.string().optional(),
+    // Allow additional fields (e.g., $defs from MCP introspection)
+})
+    .passthrough();
+/**
+ * Validate a definition against the SerializedAgentDefinition schema.
+ *
+ * Returns either the validated definition or a list of human-readable errors.
+ */
+export function validateDefinition(input) {
+    const result = SerializedAgentDefinitionSchema.safeParse(input);
+    if (result.success) {
+        return { ok: true, definition: result.data };
+    }
+    const errors = result.error.issues.map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "root";
+        return `${path}: ${issue.message}`;
+    });
+    return { ok: false, errors };
+}
+/**
+ * Validate and throw if invalid.
+ * Use in register() and pack/publish where failure should be fatal.
+ */
+export function assertValidDefinition(input, context) {
+    const result = validateDefinition(input);
+    if (!result.ok) {
+        const prefix = context
+            ? `Invalid definition (${context})`
+            : "Invalid definition";
+        throw new Error(`${prefix}:\n  ${result.errors.join("\n  ")}`);
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slashfi/agents-sdk",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "author": "Slash Financial",
   "repository": {
     "type": "git",
@@ -59,6 +59,7 @@
   "types": "dist/index.d.ts",
   "dependencies": {
     "cross-spawn": "^7.0.6",
-    "jose": "^6.2.2"
+    "jose": "^6.2.2",
+    "zod": "^3.23.0"
   }
 }

package/src/callback/index.ts

@@ -0,0 +1,172 @@
+/**
+ * Agent Callback — Deferred call_agent execution with triggers.
+ *
+ * An agent_callback is a call_agent command with an optional trigger.
+ * When the trigger fires (e.g., user submits a form), template references
+ * like {{trigger.variable_name}} are resolved with the trigger's values
+ * and the call_agent command is executed.
+ *
+ * This module provides the unopinionated contract:
+ * - Trigger schema (extensible discriminated union)
+ * - Template resolution
+ * - Store interface
+ * - Validation utilities
+ *
+ * No platform-specific code (no Slack, no CockroachDB, no Atlas).
+ */
+
+// ---------------------------------------------------------------------------
+// Trigger Schema
+// ---------------------------------------------------------------------------
+
+/**
+ * Base trigger type. Implementations extend this with specific trigger sources
+ * (e.g., slack_block_kit, webhook, timer).
+ *
+ * The `type` field discriminates between trigger sources.
+ * Additional fields are trigger-specific.
+ */
+export interface AgentCallbackTrigger {
+  type: string;
+  [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Callback Status
+// ---------------------------------------------------------------------------
+
+export type AgentCallbackStatus =
+  | 'pending'
+  | 'completed'
+  | 'expired'
+  | 'cancelled';
+
+// ---------------------------------------------------------------------------
+// Callback Entry
+// ---------------------------------------------------------------------------
+
+/**
+ * A stored agent_callback — a call_agent command waiting for its trigger to fire.
+ */
+export interface AgentCallbackEntry<TMetadata = Record<string, unknown>> {
+  id: string;
+  status: AgentCallbackStatus;
+  /** The call_agent command. Params may contain {{trigger.x}} templates. */
+  callback: Record<string, unknown>;
+  /** Trigger definition — how values are collected. */
+  trigger?: AgentCallbackTrigger;
+  /** Implementation-specific context (e.g., creator branch, user ID). */
+  metadata?: TMetadata;
+  /** Resolved values from the trigger, keyed by variable name. */
+  resolvedValues?: Record<string, string>;
+  /** Callback expires after this time. */
+  expiresAt?: Date;
+  createdAt: Date;
+  completedAt?: Date;
+}
+
+// ---------------------------------------------------------------------------
+// Create Options
+// ---------------------------------------------------------------------------
+
+export interface CreateAgentCallbackOptions<TMetadata = Record<string, unknown>> {
+  /** The call_agent command. May contain {{trigger.x}} template references in params. */
+  callback: Record<string, unknown>;
+  /** Trigger definition. */
+  trigger?: AgentCallbackTrigger;
+  /** Implementation-specific context. */
+  metadata?: TMetadata;
+  /** TTL in milliseconds (default: implementation-defined). */
+  ttlMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Resolve Options
+// ---------------------------------------------------------------------------
+
+export interface ResolveAgentCallbackOptions {
+  /** The callback ID to resolve. */
+  id: string;
+  /** Values from the trigger source, keyed by variable name. */
+  values: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Store Interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Agent Callback Store — persistence layer for deferred call_agent commands.
+ * Implementations can use any backing store (CockroachDB, SQLite, in-memory, etc.).
+ */
+export interface AgentCallbackStore<TMetadata = Record<string, unknown>> {
+  create(options: CreateAgentCallbackOptions<TMetadata>): Promise<string>;
+  get(id: string): Promise<AgentCallbackEntry<TMetadata> | null>;
+  resolve(options: ResolveAgentCallbackOptions): Promise<AgentCallbackEntry<TMetadata>>;
+  cancel(id: string): Promise<boolean>;
+  listPending(limit?: number): Promise<AgentCallbackEntry<TMetadata>[]>;
+  expireStale(): Promise<number>;
+}
+
+// ---------------------------------------------------------------------------
+// Template Resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve {{trigger.variable}} references in an object tree.
+ * Scans all string values and replaces {{trigger.x}} with the
+ * corresponding value from triggerValues.
+ *
+ * Unresolved references are left as-is.
+ */
+export function resolveCallbackTemplates<T>(
+  obj: T,
+  triggerValues: Record<string, string>,
+): T {
+  if (typeof obj === 'string') {
+    return obj.replace(/\{\{trigger\.(\w+)\}\}/g, (_match, varName: string) => {
+      return triggerValues[varName] ?? `{{trigger.${varName}}}`;
+    }) as T;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => resolveCallbackTemplates(item, triggerValues)) as T;
+  }
+  if (obj !== null && typeof obj === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(obj as Record<string, unknown>)) {
+      result[key] = resolveCallbackTemplates(val, triggerValues);
+    }
+    return result as T;
+  }
+  return obj;
+}
+
+/**
+ * Validate that all {{trigger.x}} references in a callback have
+ * corresponding variables in the provided set.
+ * Returns array of unresolved variable names, or empty if valid.
+ */
+export function validateCallbackTemplates(
+  callback: Record<string, unknown>,
+  knownVariables: string[],
+): string[] {
+  const definedVars = new Set(knownVariables);
+  const referencedVars: string[] = [];
+
+  const scanForRefs = (obj: unknown): void => {
+    if (typeof obj === 'string') {
+      const matches = obj.matchAll(/\{\{trigger\.(\w+)\}\}/g);
+      for (const match of matches) {
+        referencedVars.push(match[1]);
+      }
+    } else if (Array.isArray(obj)) {
+      obj.forEach(scanForRefs);
+    } else if (obj !== null && typeof obj === 'object') {
+      Object.values(obj as Record<string, unknown>).forEach(scanForRefs);
+    }
+  };
+
+  scanForRefs(callback);
+
+  return referencedVars.filter((v) => !definedVars.has(v));
+}

package/src/index.ts

@@ -100,7 +100,7 @@ export { defineAgent, defineTool } from "./define.js";
 export type { DefineAgentOptions, DefineToolOptions, AgentWithHooks, ToolWithHooks } from "./define.js";
 
 // Registry
-export { createAgentRegistry } from "./registry.js";
+export { createAgentRegistry, agentFromSerialized } from "./registry.js";
 export type {
   AgentRegistry,
   AgentRegistryOptions,
@@ -340,3 +340,32 @@ export type {
 
 export { introspectMcp } from "./introspect.js";
 export type { IntrospectOptions } from "./introspect.js";
+
+// ============================================
+// Agent Callbacks (deferred call_agent commands)
+// ============================================
+
+export {
+  resolveCallbackTemplates,
+  validateCallbackTemplates,
+} from "./callback/index.js";
+export type {
+  AgentCallbackTrigger,
+  AgentCallbackStatus,
+  AgentCallbackEntry,
+  AgentCallbackStore,
+  CreateAgentCallbackOptions,
+  ResolveAgentCallbackOptions,
+} from "./callback/index.js";
+
+// ============================================
+// Validation
+// ============================================
+
+export {
+  SerializedAgentDefinitionSchema,
+  SerializedToolSchema,
+  validateDefinition,
+  assertValidDefinition,
+} from "./validate.js";
+export type { ValidationResult } from "./validate.js";

package/src/pack.ts

@@ -13,15 +13,11 @@
 
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseJsonc } from "./jsonc.js";
 import type { SerializedAgentDefinition } from "./serialized.js";
+import { assertValidDefinition } from "./validate.js";
 
 // ============================================
 // Types
@@ -159,6 +155,9 @@ export function pack(options: PackOptions): PackResult {
   const agentContent = readFileSync(agentPath, "utf-8");
   const definition = parseJsonc(agentContent) as SerializedAgentDefinition;
 
+  // Validate the definition schema
+  assertValidDefinition(definition, agentPath);
+
   // Compute hash + version
   const hash = contentHash(agentContent);
   const version = `${definition.version || "1.0.0"}`;

package/src/registry.ts

@@ -5,12 +5,9 @@
  */
 
 import { dirname, resolve } from "node:path";
-import type {
-  AgentEvent,
-  EventCallback,
-  EventType,
-} from "./events.js";
+import type { AgentEvent, EventCallback, EventType } from "./events.js";
 import { createEventBus } from "./events.js";
+import type { SerializedAgentDefinition } from "./serialized.js";
 import type {
   AgentAction,
   AgentDefinition,
@@ -28,6 +25,7 @@ import type {
   ToolSchema,
   Visibility,
 } from "./types.js";
+import { assertValidDefinition } from "./validate.js";
 
 /** Default supported actions if not specified */
 const DEFAULT_SUPPORTED_ACTIONS: AgentAction[] = [
@@ -75,8 +73,8 @@ export interface AgentRegistryOptions {
  * Agent registry interface.
  */
 export interface AgentRegistry {
-  /** Register an agent */
-  register(agent: AgentDefinition): void;
+  /** Register an agent (accepts both AgentDefinition and SerializedAgentDefinition) */
+  register(agent: AgentDefinition | SerializedAgentDefinition): void;
 
   /** Get an agent by path */
   get(path: string): AgentDefinition | undefined;
@@ -128,6 +126,43 @@ export type ContextFactory = (
   baseCtx: import("./types.js").ToolContext,
 ) => import("./types.js").ToolContext;
 
+/**
+ * Convert a SerializedAgentDefinition to an AgentDefinition.
+ *
+ * Use this when you need an AgentDefinition but have a serialized one
+ * (e.g., from an @agentdef package or adk introspect output).
+ *
+ * Tools get a proxy execute that throws — actual execution goes through MCP.
+ * The registry's `register()` method calls this automatically.
+ */
+export function agentFromSerialized(
+  def: SerializedAgentDefinition,
+): AgentDefinition {
+  return {
+    path: def.path,
+    entrypoint: def.description || `Agent for ${def.name}`,
+    config: {
+      name: def.name,
+      description: def.description,
+      visibility: def.visibility as Visibility | undefined,
+    },
+    visibility: def.visibility as Visibility | undefined,
+    tools: def.tools.map(
+      (t) =>
+        ({
+          name: t.name,
+          description: t.description,
+          inputSchema: t.inputSchema,
+          execute: async () => {
+            throw new Error(
+              `Tool "${t.name}" is from a SerializedAgentDefinition and requires MCP server execution. Use createClient() to call tools on serialized agents.`,
+            );
+          },
+        }) as unknown as ToolDefinition,
+    ),
+  };
+}
+
 export function createAgentRegistry(
   options: AgentRegistryOptions = {},
 ): AgentRegistry {
@@ -333,8 +368,61 @@ export function createAgentRegistry(
     };
   }
 
+  /**
+   * Detect if the input is a SerializedAgentDefinition (vs AgentDefinition).
+   * SerializedAgentDefinition has tools with inputSchema but no execute function.
+   */
+  function isSerialized(
+    agent: AgentDefinition | SerializedAgentDefinition,
+  ): agent is SerializedAgentDefinition {
+    if (!agent.tools || agent.tools.length === 0) return false;
+    // SerializedAgentDefinition tools have inputSchema but no execute
+    const firstTool = agent.tools[0] as unknown as Record<string, unknown>;
+    return "inputSchema" in firstTool && !("execute" in firstTool);
+  }
+
+  /**
+   * Convert a SerializedAgentDefinition to an AgentDefinition.
+   * Tools get a proxy execute that throws — actual execution goes through MCP.
+   */
+  function fromSerialized(def: SerializedAgentDefinition): AgentDefinition {
+    return {
+      path: def.path,
+      entrypoint: def.description || `Agent for ${def.name}`,
+      config: {
+        name: def.name,
+        description: def.description,
+        visibility: def.visibility as Visibility | undefined,
+      },
+      visibility: def.visibility as Visibility | undefined,
+      tools: def.tools.map(
+        (t) =>
+          ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+            execute: async () => {
+              throw new Error(
+                `Tool "${t.name}" is from a SerializedAgentDefinition and requires MCP server execution. Use createClient() to call tools on serialized agents.`,
+              );
+            },
+          }) as unknown as ToolDefinition,
+      ),
+    };
+  }
+
   const registry: AgentRegistry = {
-    register(agent: AgentDefinition): void {
+    register(input: AgentDefinition | SerializedAgentDefinition): void {
+      let agent: AgentDefinition;
+      if (isSerialized(input)) {
+        assertValidDefinition(
+          input,
+          `register(${(input as SerializedAgentDefinition).path || "unknown"})`,
+        );
+        agent = fromSerialized(input as SerializedAgentDefinition);
+      } else {
+        agent = input as AgentDefinition;
+      }
       agents.set(agent.path, agent);
 
       // Collect agent-level listeners into the bus
@@ -508,15 +596,17 @@ export function createAgentRegistry(
               result = await tool.execute(request.params, ctx);
             } catch (err) {
               // Emit tool/error on failure
-              await eventBus.emit({
-                type: "tool/error",
-                agentPath: agent.path,
-                tool: request.tool!,
-                params: request.params,
-                error: err,
-                durationMs: Date.now() - startMs,
-                timestamp: Date.now(),
-              }).catch(() => {}); // don't let emit error mask tool error
+              await eventBus
+                .emit({
+                  type: "tool/error",
+                  agentPath: agent.path,
+                  tool: request.tool!,
+                  params: request.params,
+                  error: err,
+                  durationMs: Date.now() - startMs,
+                  timestamp: Date.now(),
+                })
+                .catch(() => {}); // don't let emit error mask tool error
 
               return {
                 success: false,
@@ -544,7 +634,8 @@ export function createAgentRegistry(
             // Catch-all for unexpected errors (e.g., emit failures)
             return {
               success: false,
-              error: outerErr instanceof Error ? outerErr.message : String(outerErr),
+              error:
+                outerErr instanceof Error ? outerErr.message : String(outerErr),
               code: "TOOL_EXECUTION_ERROR",
             } as CallAgentErrorResponse;
           }