@contractspec/lib.ai-agent 5.0.4 → 6.0.0

package/dist/tools/memory-tools.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Memory tools for AI agents — Anthropic memory and custom operation-backed tools.
+ *
+ * @see https://ai-sdk.dev/docs/agents/memory
+ * @see https://console.anthropic.com/docs/en/agents-and-tools/tool-use/memory-tool
+ */
+import type { Tool } from 'ai';
+import type { AgentMemoryStore } from './agent-memory-store';
+/** Action shape from Anthropic memory_20250818 tool. */
+export interface AnthropicMemoryAction {
+    command: 'view' | 'create' | 'str_replace' | 'insert' | 'delete' | 'rename';
+    path?: string;
+    view_range?: [number, number];
+    file_text?: string;
+    old_str?: string;
+    new_str?: string;
+    insert_line?: number;
+    insert_text?: string;
+    old_path?: string;
+    new_path?: string;
+}
+/**
+ * Creates the Anthropic memory tool backed by an AgentMemoryStore.
+ * Use when provider is Anthropic and agent needs persistent memory.
+ *
+ * @param store - Storage backend (e.g. InMemoryAgentMemoryStore for dev)
+ * @returns AI SDK tool for use with ToolLoopAgent
+ */
+export declare function createAnthropicMemoryTool(store: AgentMemoryStore): Tool;

package/dist/tools/memory-tools.js

@@ -0,0 +1,45 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/tools/memory-tools.ts
+import { anthropic } from "@ai-sdk/anthropic";
+function createAnthropicMemoryTool(store) {
+  const memory = anthropic.tools.memory_20250818({
+    execute: async (action) => {
+      switch (action.command) {
+        case "view":
+          return store.view(action.path ?? "/memories", action.view_range);
+        case "create":
+          return store.create(action.path ?? "/memories/untitled", action.file_text ?? "");
+        case "str_replace":
+          return store.strReplace(action.path ?? "/memories", action.old_str ?? "", action.new_str ?? "");
+        case "insert":
+          return store.insert(action.path ?? "/memories", action.insert_line ?? 0, action.insert_text ?? "");
+        case "delete":
+          return store.delete(action.path ?? "/memories");
+        case "rename":
+          return store.rename(action.old_path ?? "/memories", action.new_path ?? "/memories");
+        default:
+          return `Unknown command: ${action.command}`;
+      }
+    }
+  });
+  return memory;
+}
+var init_memory_tools = () => {};
+init_memory_tools();
+
+export {
+  createAnthropicMemoryTool
+};

package/dist/tools/operation-tool-handler.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Operation-as-tool: creates a ToolHandler that executes a ContractSpec operation.
+ *
+ * One contract → REST, GraphQL, MCP, agent tool. When an agent tool has
+ * operationRef, this module provides the handler that delegates to
+ * OperationSpecRegistry.execute.
+ */
+import type { OperationSpecRegistry } from '@contractspec/lib.contracts-spec/operations/registry';
+import type { OperationRef } from '../spec/spec';
+import type { ToolHandler } from '../types';
+/**
+ * Create a ToolHandler that executes a ContractSpec operation.
+ *
+ * @param registry - OperationSpecRegistry with the operation registered and handler bound
+ * @param operationRef - Reference to the operation (key, optional version)
+ * @returns ToolHandler that delegates to registry.execute
+ *
+ * @example
+ * ```typescript
+ * const handler = createOperationToolHandler(opsRegistry, { key: 'knowledge.search', version: '1.0.0' });
+ * toolHandlers.set('search_knowledge', handler);
+ * ```
+ */
+export declare function createOperationToolHandler(registry: OperationSpecRegistry, operationRef: OperationRef): ToolHandler;

package/dist/tools/operation-tool-handler.js

@@ -0,0 +1,35 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/tools/operation-tool-handler.ts
+function toolCtxToHandlerCtx(ctx) {
+  return {
+    traceId: ctx.metadata?.traceId,
+    organizationId: ctx.tenantId ?? null,
+    userId: ctx.actorId ?? null,
+    actor: ctx.actorId ? "user" : "anonymous",
+    channel: "agent",
+    roles: []
+  };
+}
+function createOperationToolHandler(registry, operationRef) {
+  return async (input, context) => {
+    const handlerCtx = toolCtxToHandlerCtx(context);
+    const result = await registry.execute(operationRef.key, operationRef.version, input ?? {}, handlerCtx);
+    return result;
+  };
+}
+export {
+  createOperationToolHandler
+};

package/dist/tools/subagent-tool.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Subagent tool factory for AI SDK parent-child agent delegation.
+ *
+ * Creates a tool whose execute calls a subagent, optionally streaming
+ * preliminary results and controlling what the model sees via toModelOutput.
+ *
+ * @see https://ai-sdk.dev/docs/agents/subagents
+ */
+import { type Tool } from 'ai';
+/** Subagent interface compatible with ToolLoopAgent stream. */
+export interface SubagentLike {
+    stream(params: {
+        prompt: string;
+        abortSignal?: AbortSignal;
+    }): Promise<{
+        toUIMessageStream(): AsyncIterable<unknown> | ReadableStream<unknown>;
+    }>;
+    /** Optional: for passConversationHistory; when present, used instead of stream when messages are passed */
+    generate?(params: {
+        messages: {
+            role: string;
+            content: string | unknown[];
+        }[];
+        abortSignal?: AbortSignal;
+    }): Promise<{
+        text: string;
+    }>;
+}
+export interface CreateSubagentToolOptions {
+    /** Subagent to delegate to (ToolLoopAgent or compatible) */
+    subagent: SubagentLike;
+    /** Tool name (unique within the parent agent) */
+    name?: string;
+    /** Human-readable description for the LLM */
+    description?: string;
+    /** Input parameter name for the task (default: 'task') */
+    taskParam?: string;
+    /** Whether to extract summary for toModelOutput (default: true) */
+    toModelSummary?: boolean;
+    /** Pass full conversation history to subagent (opt-in; defeats context isolation; disables streaming) */
+    passConversationHistory?: boolean;
+}
+/**
+ * Create an AI SDK tool that delegates to a subagent.
+ *
+ * Supports streaming preliminary results via async generator execute.
+ * When toModelSummary is true, toModelOutput extracts the last text part
+ * so the parent model sees only a summary.
+ *
+ * @example
+ * ```ts
+ * const researchSubagent = new ToolLoopAgent({ model, instructions, tools });
+ * const researchTool = createSubagentTool({
+ *   subagent: researchSubagent,
+ *   name: 'research',
+ *   description: 'Research a topic in depth.',
+ * });
+ * const mainAgent = new ToolLoopAgent({
+ *   model,
+ *   tools: { research: researchTool },
+ * });
+ * ```
+ */
+export declare function createSubagentTool(options: CreateSubagentToolOptions): Tool<{
+    task: string;
+}, unknown>;

package/dist/tools/subagent-tool.js

@@ -0,0 +1,95 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/tools/subagent-tool.ts
+import { readUIMessageStream, tool } from "ai";
+import { z } from "zod";
+function toReadableStream(iterable) {
+  if (iterable instanceof ReadableStream) {
+    return iterable;
+  }
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const chunk of iterable) {
+          controller.enqueue(chunk);
+        }
+      } finally {
+        controller.close();
+      }
+    }
+  });
+}
+function createSubagentTool(options) {
+  const {
+    subagent,
+    description = "Research a topic or question in depth.",
+    taskParam = "task",
+    toModelSummary = true,
+    passConversationHistory = false
+  } = options;
+  const inputSchema = z.object({
+    [taskParam]: z.string().describe("The research task to complete")
+  });
+  const execute = async function* (input, options2) {
+    const task = String(input[taskParam] ?? input.task ?? "");
+    const { abortSignal, messages } = options2 ?? {};
+    if (passConversationHistory && messages && messages.length > 0 && typeof subagent.generate === "function") {
+      const result2 = await subagent.generate({
+        messages: [...messages, { role: "user", content: task }],
+        abortSignal
+      });
+      yield { parts: [{ type: "text", text: result2.text }] };
+      return;
+    }
+    const result = await subagent.stream({
+      prompt: task,
+      abortSignal
+    });
+    const uiStream = result.toUIMessageStream();
+    const stream = toReadableStream(uiStream);
+    for await (const message of readUIMessageStream({
+      stream
+    })) {
+      yield message;
+    }
+  };
+  const toolOptions = {
+    description,
+    inputSchema,
+    execute,
+    ...toModelSummary && {
+      toModelOutput: ({
+        output
+      }) => {
+        const parts = output?.parts;
+        if (!Array.isArray(parts)) {
+          return { type: "text", value: "Task completed." };
+        }
+        const lastTextPart = [...parts].reverse().find((p) => p?.type === "text");
+        return {
+          type: "text",
+          value: lastTextPart?.text ?? "Task completed."
+        };
+      }
+    }
+  };
+  return tool(toolOptions);
+}
+var init_subagent_tool = () => {};
+init_subagent_tool();
+
+export {
+  createSubagentTool
+};

package/dist/tools/tool-adapter.d.ts

@@ -1,24 +1,40 @@
 import { type Tool } from 'ai';
+import * as z from 'zod';
+import type { OperationSpecRegistry } from '@contractspec/lib.contracts-spec/operations/registry';
+import type { AnyOperationSpec } from '@contractspec/lib.contracts-spec/operations/operation';
 import type { AgentToolConfig } from '../spec/spec';
 import type { ToolExecutionContext, ToolHandler } from '../types';
+import { type SubagentLike } from './subagent-tool';
+export declare function specToolToAISDKTool(specTool: AgentToolConfig, handler: ToolHandler, context?: Partial<ToolExecutionContext>, effectiveInputSchema?: z.ZodType, 
+/** Optional operation spec for output ref fallback when specTool has no output refs */
+operationSpec?: AnyOperationSpec): Tool<any, any>;
 /**
- * Convert ContractSpec AgentToolConfig to AI SDK CoreTool.
- *
- * @param specTool - The tool configuration from AgentSpec
- * @param handler - The handler function for the tool
- * @param context - Partial context to inject into handler calls
- * @returns AI SDK CoreTool
+ * Registry for resolving subagents by agentId.
  */
-export declare function specToolToAISDKTool(specTool: AgentToolConfig, handler: ToolHandler, context?: Partial<ToolExecutionContext>): Tool<any, any>;
+export type SubagentRegistry = Map<string, SubagentLike>;
+/**
+ * Options for specToolsToAISDKTools.
+ */
+export interface SpecToolsToAISDKToolsOptions {
+    /** Optional OperationSpecRegistry for operation-backed tools (operationRef) */
+    operationRegistry?: OperationSpecRegistry;
+    /** Optional registry for subagent-backed tools (subagentRef) */
+    subagentRegistry?: SubagentRegistry;
+}
 /**
  * Convert multiple ContractSpec tool configs to AI SDK tools.
  *
+ * When a tool has operationRef and operationRegistry is provided, the handler
+ * and input schema are derived from the operation. Otherwise, handlers must
+ * be supplied for each tool.
+ *
  * @param specTools - Array of tool configurations
- * @param handlers - Map of tool name to handler function
+ * @param handlers - Map of tool name to handler function (for inline tools)
  * @param context - Partial context to inject into handler calls
+ * @param options - Optional operationRegistry for operation-backed tools
  * @returns Record of AI SDK tools keyed by name
  */
-export declare function specToolsToAISDKTools(specTools: AgentToolConfig[], handlers: Map<string, ToolHandler>, context?: Partial<ToolExecutionContext>): Record<string, Tool<any, any>>;
+export declare function specToolsToAISDKTools(specTools: AgentToolConfig[], handlers: Map<string, ToolHandler>, context?: Partial<ToolExecutionContext>, options?: SpecToolsToAISDKToolsOptions): Record<string, Tool<any, any>>;
 /**
  * Type-safe tool handler builder.
  *
@@ -29,7 +45,7 @@ export declare function specToolsToAISDKTools(specTools: AgentToolConfig[], hand
  * });
  * ```
  */
-export declare function createToolHandler<TInput = unknown, TOutput = string>(handler: (input: TInput, context: ToolExecutionContext) => Promise<TOutput> | TOutput): ToolHandler<TInput, TOutput>;
+export declare function createToolHandler<TInput = unknown, TOutput = string>(handler: (input: TInput, context: ToolExecutionContext) => Promise<TOutput> | TOutput | AsyncGenerator<TOutput>): ToolHandler<TInput, TOutput>;
 /**
  * Build a tool handlers map from an object.
  *

package/dist/tools/tool-adapter.js

@@ -2260,15 +2260,124 @@ function jsonSchemaToZodSafe(schema) {
 }
 var init_json_schema_to_zod = () => {};
 
+// src/tools/operation-tool-handler.ts
+function toolCtxToHandlerCtx(ctx) {
+  return {
+    traceId: ctx.metadata?.traceId,
+    organizationId: ctx.tenantId ?? null,
+    userId: ctx.actorId ?? null,
+    actor: ctx.actorId ? "user" : "anonymous",
+    channel: "agent",
+    roles: []
+  };
+}
+function createOperationToolHandler(registry, operationRef) {
+  return async (input, context) => {
+    const handlerCtx = toolCtxToHandlerCtx(context);
+    const result = await registry.execute(operationRef.key, operationRef.version, input ?? {}, handlerCtx);
+    return result;
+  };
+}
+
+// src/tools/subagent-tool.ts
+import { readUIMessageStream, tool } from "ai";
+import { z as z2 } from "zod";
+function toReadableStream(iterable) {
+  if (iterable instanceof ReadableStream) {
+    return iterable;
+  }
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const chunk of iterable) {
+          controller.enqueue(chunk);
+        }
+      } finally {
+        controller.close();
+      }
+    }
+  });
+}
+function createSubagentTool(options) {
+  const {
+    subagent,
+    description = "Research a topic or question in depth.",
+    taskParam = "task",
+    toModelSummary = true,
+    passConversationHistory = false
+  } = options;
+  const inputSchema = z2.object({
+    [taskParam]: z2.string().describe("The research task to complete")
+  });
+  const execute = async function* (input, options2) {
+    const task = String(input[taskParam] ?? input.task ?? "");
+    const { abortSignal, messages } = options2 ?? {};
+    if (passConversationHistory && messages && messages.length > 0 && typeof subagent.generate === "function") {
+      const result2 = await subagent.generate({
+        messages: [...messages, { role: "user", content: task }],
+        abortSignal
+      });
+      yield { parts: [{ type: "text", text: result2.text }] };
+      return;
+    }
+    const result = await subagent.stream({
+      prompt: task,
+      abortSignal
+    });
+    const uiStream = result.toUIMessageStream();
+    const stream = toReadableStream(uiStream);
+    for await (const message of readUIMessageStream({
+      stream
+    })) {
+      yield message;
+    }
+  };
+  const toolOptions = {
+    description,
+    inputSchema,
+    execute,
+    ...toModelSummary && {
+      toModelOutput: ({
+        output
+      }) => {
+        const parts = output?.parts;
+        if (!Array.isArray(parts)) {
+          return { type: "text", value: "Task completed." };
+        }
+        const lastTextPart = [...parts].reverse().find((p) => p?.type === "text");
+        return {
+          type: "text",
+          value: lastTextPart?.text ?? "Task completed."
+        };
+      }
+    }
+  };
+  return tool(toolOptions);
+}
+var init_subagent_tool = () => {};
+
 // src/tools/tool-adapter.ts
-import { tool } from "ai";
-function specToolToAISDKTool(specTool, handler, context = {}) {
+import { tool as tool2 } from "ai";
+function isAsyncGenerator(value) {
+  return typeof value === "object" && value !== null && typeof value.next === "function" && typeof value[Symbol.asyncIterator] === "function";
+}
+function specToolToAISDKTool(specTool, handler, context = {}, effectiveInputSchema, operationSpec) {
   let lastInvocationAt;
-  return tool({
+  const inputSchema = effectiveInputSchema ?? jsonSchemaToZodSafe(specTool.schema);
+  const buildContext = (signal) => ({
+    agentId: context.agentId ?? "unknown",
+    sessionId: context.sessionId ?? "unknown",
+    tenantId: context.tenantId,
+    actorId: context.actorId,
+    locale: context.locale,
+    metadata: context.metadata,
+    signal
+  });
+  return tool2({
     description: specTool.description ?? specTool.name,
-    inputSchema: jsonSchemaToZodSafe(specTool.schema),
+    inputSchema,
     needsApproval: specTool.requiresApproval ?? !specTool.automationSafe,
-    execute: async (input) => {
+    execute: async function* (input, options) {
       const now = Date.now();
       const cooldownMs = normalizeDuration(specTool.cooldownMs);
       if (cooldownMs && lastInvocationAt !== undefined) {
@@ -2279,19 +2388,20 @@ function specToolToAISDKTool(specTool, handler, context = {}) {
         }
       }
       const timeoutMs = normalizeDuration(specTool.timeoutMs);
-      const { signal, dispose } = createTimeoutSignal(context.signal, timeoutMs);
+      const signal = options?.abortSignal ?? context.signal;
+      const { signal: timeoutSignal, dispose } = createTimeoutSignal(signal, timeoutMs);
       try {
-        const execution = handler(input, {
-          agentId: context.agentId ?? "unknown",
-          sessionId: context.sessionId ?? "unknown",
-          tenantId: context.tenantId,
-          actorId: context.actorId,
-          locale: context.locale,
-          metadata: context.metadata,
-          signal
-        });
-        const result = timeoutMs ? await withTimeout(execution, timeoutMs, specTool.name) : await execution;
-        return typeof result === "string" ? result : JSON.stringify(result);
+        const execution = handler(input, buildContext(timeoutSignal));
+        if (isAsyncGenerator(execution)) {
+          for await (const raw of execution) {
+            const wrapped = wrapToolOutputForRendering(specTool, raw, operationSpec);
+            yield typeof wrapped === "string" ? wrapped : wrapped;
+          }
+        } else {
+          const raw = timeoutMs ? await withTimeout(Promise.resolve(execution), timeoutMs, specTool.name) : await Promise.resolve(execution);
+          const wrapped = wrapToolOutputForRendering(specTool, raw, operationSpec);
+          yield typeof wrapped === "string" ? wrapped : wrapped;
+        }
       } finally {
         dispose();
         lastInvocationAt = Date.now();
@@ -2299,27 +2409,83 @@ function specToolToAISDKTool(specTool, handler, context = {}) {
     }
   });
 }
-function specToolsToAISDKTools(specTools, handlers, context = {}) {
+function specToolsToAISDKTools(specTools, handlers, context = {}, options) {
   const tools = {};
   for (const specTool of specTools) {
-    const handler = handlers.get(specTool.name);
-    if (!handler) {
-      throw new Error(createAgentI18n(context.locale).t("error.missingToolHandler", {
-        name: specTool.name
-      }));
+    if (specTool.subagentRef && options?.subagentRegistry) {
+      const subagent = options.subagentRegistry.get(specTool.subagentRef.agentId);
+      if (!subagent) {
+        throw new Error(`Subagent not found: ${specTool.subagentRef.agentId}. Register it in subagentRegistry.`);
+      }
+      if (specTool.requiresApproval === true || specTool.automationSafe === false) {
+        console.warn(`[ContractSpec] Subagent tool "${specTool.name}" cannot use needsApproval. ` + `requiresApproval and automationSafe are ignored for subagent tools (AI SDK limitation). ` + `See https://ai-sdk.dev/docs/agents/subagents#no-tool-approvals-in-subagents`);
+      }
+      tools[specTool.name] = createSubagentTool({
+        subagent,
+        description: specTool.description ?? specTool.name,
+        toModelSummary: specTool.subagentRef.toModelSummary ?? true,
+        passConversationHistory: specTool.subagentRef.passConversationHistory
+      });
+      continue;
     }
-    tools[specTool.name] = specToolToAISDKTool(specTool, handler, context);
+    let handler;
+    let effectiveInputSchema;
+    let op;
+    if (specTool.operationRef && options?.operationRegistry) {
+      op = options.operationRegistry.get(specTool.operationRef.key, specTool.operationRef.version);
+      if (!op) {
+        throw new Error(`Operation not found: ${specTool.operationRef.key}${specTool.operationRef.version ? `.v${specTool.operationRef.version}` : ""}`);
+      }
+      handler = createOperationToolHandler(options.operationRegistry, specTool.operationRef);
+      effectiveInputSchema = op.io.input?.getZod?.();
+    } else {
+      const manualHandler = handlers.get(specTool.name);
+      if (!manualHandler) {
+        if (specTool.subagentRef) {
+          throw new Error(`Subagent tool "${specTool.name}" requires subagentRegistry. Pass subagentRegistry in ContractSpecAgentConfig.`);
+        }
+        throw new Error(createAgentI18n(context.locale).t("error.missingToolHandler", {
+          name: specTool.name
+        }));
+      }
+      handler = manualHandler;
+    }
+    tools[specTool.name] = specToolToAISDKTool(specTool, handler, context, effectiveInputSchema, op);
   }
   return tools;
 }
 function createToolHandler(handler) {
-  return async (input, context) => {
+  return (input, context) => {
     return handler(input, context);
   };
 }
 function buildToolHandlers(handlersObj) {
   return new Map(Object.entries(handlersObj));
 }
+function wrapToolOutputForRendering(specTool, result, operationSpec) {
+  const presentation = specTool.outputPresentation ?? operationSpec?.outputPresentation;
+  const form = specTool.outputForm ?? operationSpec?.outputForm;
+  const dataView = specTool.outputDataView ?? operationSpec?.outputDataView;
+  if (presentation) {
+    return {
+      presentationKey: presentation.key,
+      data: result
+    };
+  }
+  if (form) {
+    return {
+      formKey: form.key,
+      defaultValues: typeof result === "object" && result !== null ? result : {}
+    };
+  }
+  if (dataView) {
+    return {
+      dataViewKey: dataView.key,
+      items: Array.isArray(result) ? result : result != null ? [result] : []
+    };
+  }
+  return result;
+}
 function normalizeDuration(value) {
   if (value === undefined) {
     return;
@@ -2381,6 +2547,7 @@ function createToolExecutionError(message, code, retryAfterMs) {
 var init_tool_adapter = __esm(() => {
   init_json_schema_to_zod();
   init_i18n();
+  init_subagent_tool();
 });
 init_tool_adapter();
 

package/dist/types.d.ts

@@ -90,8 +90,13 @@ export interface AgentSessionState {
     metadata?: Record<string, string>;
 }
 export interface AgentGenerateParams {
-    /** User prompt or message */
-    prompt: string;
+    /** User prompt (required when messages is not provided) */
+    prompt?: string;
+    /** Full conversation history (for subagent passConversationHistory; when set, prompt is ignored) */
+    messages?: {
+        role: string;
+        content: string | unknown[];
+    }[];
     /** System prompt override (appended to agent instructions) */
     systemOverride?: string;
     /** Runtime context options */
@@ -144,8 +149,9 @@ export interface ToolExecutionContext {
 }
 /**
  * Handler function for a tool.
+ * May return a Promise (single result) or AsyncGenerator (streaming preliminary results).
  */
-export type ToolHandler<TInput = unknown, TOutput = string> = (input: TInput, context: ToolExecutionContext) => Promise<TOutput>;
+export type ToolHandler<TInput = unknown, TOutput = string> = (input: TInput, context: ToolExecutionContext) => Promise<TOutput> | TOutput | AsyncGenerator<TOutput>;
 export interface AgentStepMetrics {
     agentId: string;
     stepIndex: number;