@opperai/agents 0.3.0 → 0.4.0

package/dist/index.js

@@ -100,7 +100,8 @@ var init_tool = __esm({
           output,
           ...init.startedAt !== void 0 && { startedAt: init.startedAt },
           finishedAt: init.finishedAt ?? Date.now(),
-          metadata: init.metadata ?? {}
+          metadata: init.metadata ?? {},
+          ...init.usage !== void 0 && { usage: init.usage }
         };
         ToolResultSuccessSchema.parse(result);
         return result;
@@ -112,7 +113,8 @@ var init_tool = __esm({
           error,
           ...init.startedAt !== void 0 && { startedAt: init.startedAt },
           finishedAt: init.finishedAt ?? Date.now(),
-          metadata: init.metadata ?? {}
+          metadata: init.metadata ?? {},
+          ...init.usage !== void 0 && { usage: init.usage }
         };
         ToolResultFailureSchema.parse(result);
         return result;
@@ -167,14 +169,43 @@ var init_tool = __esm({
 var context_exports = {};
 __export(context_exports, {
   AgentContext: () => AgentContext,
+  BaseUsageSchema: () => BaseUsageSchema,
   ExecutionCycleSchema: () => ExecutionCycleSchema,
-  UsageSchema: () => UsageSchema
+  UsageSchema: () => UsageSchema,
+  addUsage: () => addUsage,
+  createEmptyUsage: () => createEmptyUsage
 });
-var UsageSchema, ExecutionCycleSchema, AgentContext;
+function createEmptyUsage() {
+  return {
+    requests: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+    cost: {
+      generation: 0,
+      platform: 0,
+      total: 0
+    }
+  };
+}
+function addUsage(a, b) {
+  return {
+    requests: a.requests + b.requests,
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    totalTokens: a.totalTokens + b.totalTokens,
+    cost: {
+      generation: a.cost.generation + b.cost.generation,
+      platform: a.cost.platform + b.cost.platform,
+      total: a.cost.total + b.cost.total
+    }
+  };
+}
+var BaseUsageSchema, UsageSchema, ExecutionCycleSchema, AgentContext;
 var init_context = __esm({
   "src/base/context.ts"() {
     init_tool();
-    UsageSchema = z.object({
+    BaseUsageSchema = z.object({
       requests: z.number().int().nonnegative().default(0),
       inputTokens: z.number().int().nonnegative().default(0),
       outputTokens: z.number().int().nonnegative().default(0),
@@ -185,6 +216,13 @@ var init_context = __esm({
         total: z.number().nonnegative().default(0)
       }).default({ generation: 0, platform: 0, total: 0 })
     });
+    UsageSchema = BaseUsageSchema.extend({
+      /**
+       * Optional breakdown of usage by source (agent name).
+       * Only present when nested agents are used.
+       */
+      breakdown: z.record(z.string(), z.lazy(() => BaseUsageSchema)).optional()
+    });
     ExecutionCycleSchema = z.object({
       iteration: z.number().int().nonnegative(),
       thought: z.unknown().nullable().optional(),
@@ -226,10 +264,42 @@ var init_context = __esm({
             generation: this.usage.cost.generation + next.cost.generation,
             platform: this.usage.cost.platform + next.cost.platform,
             total: this.usage.cost.total + next.cost.total
-          }
+          },
+          // Preserve existing breakdown
+          ...this.usage.breakdown && { breakdown: this.usage.breakdown }
         };
         this.touch();
       }
+      /**
+       * Update usage with source tracking for nested agent aggregation.
+       * This method updates the total usage AND tracks it by source in the breakdown.
+       *
+       * @param source - The source name (typically the agent/tool name)
+       * @param delta - The usage to add
+       */
+      updateUsageWithSource(source, delta) {
+        this.updateUsage(delta);
+        if (!this.usage.breakdown) {
+          this.usage.breakdown = {};
+        }
+        const existing = this.usage.breakdown[source] ?? createEmptyUsage();
+        this.usage.breakdown[source] = addUsage(existing, delta);
+      }
+      /**
+       * Clean up the usage breakdown if it only contains the parent agent.
+       * This ensures breakdown is only present when there are nested agents.
+       *
+       * @param parentAgentName - The name of the parent agent to check for
+       */
+      cleanupBreakdownIfOnlyParent(parentAgentName) {
+        if (!this.usage.breakdown) {
+          return;
+        }
+        const sources = Object.keys(this.usage.breakdown);
+        if (sources.length === 1 && sources[0] === parentAgentName) {
+          delete this.usage.breakdown;
+        }
+      }
       addCycle(cycle) {
         const parsed = ExecutionCycleSchema.parse(cycle);
         this.executionHistory.push(parsed);
@@ -275,6 +345,18 @@ var init_context = __esm({
         this.touch();
       }
       snapshot() {
+        const usageCopy = {
+          ...this.usage,
+          cost: { ...this.usage.cost },
+          ...this.usage.breakdown && {
+            breakdown: Object.fromEntries(
+              Object.entries(this.usage.breakdown).map(([key, value]) => [
+                key,
+                { ...value, cost: { ...value.cost } }
+              ])
+            )
+          }
+        };
         return {
           agentName: this.agentName,
           sessionId: this.sessionId,
@@ -282,7 +364,7 @@ var init_context = __esm({
           iteration: this.iteration,
           goal: this.goal,
           executionHistory: [...this.executionHistory],
-          usage: { ...this.usage },
+          usage: usageCopy,
           toolCalls: [...this.toolCalls],
           metadata: { ...this.metadata },
           startedAt: this.startedAt,
@@ -469,82 +551,6 @@ var HookManager = class {
 };
 var createHookManager = (logger) => new HookManager(logger);
 
-// src/base/events.ts
-var AgentEvents = {
-  StreamStart: HookEvents.StreamStart,
-  StreamChunk: HookEvents.StreamChunk,
-  StreamEnd: HookEvents.StreamEnd,
-  StreamError: HookEvents.StreamError
-};
-var AgentEventEmitter = class {
-  registry = /* @__PURE__ */ new Map();
-  logger;
-  constructor(logger) {
-    this.logger = logger ?? getDefaultLogger();
-  }
-  on(event, listener) {
-    const listeners = this.registry.get(event) ?? /* @__PURE__ */ new Set();
-    listeners.add(listener);
-    this.registry.set(event, listeners);
-    return () => this.off(event, listener);
-  }
-  once(event, listener) {
-    const wrapper = (payload) => {
-      try {
-        listener(payload);
-      } finally {
-        this.off(event, wrapper);
-      }
-    };
-    return this.on(event, wrapper);
-  }
-  off(event, listener) {
-    const listeners = this.registry.get(event);
-    if (!listeners) {
-      return;
-    }
-    listeners.delete(listener);
-    if (listeners.size === 0) {
-      this.registry.delete(event);
-    }
-  }
-  emit(event, payload) {
-    const listeners = Array.from(
-      this.registry.get(event) ?? /* @__PURE__ */ new Set()
-    );
-    if (listeners.length === 0) {
-      return;
-    }
-    for (const listener of listeners) {
-      try {
-        listener(payload);
-      } catch (error) {
-        this.logger.warn(`Agent event listener failed for "${event}"`, {
-          event,
-          error: error instanceof Error ? error.message : String(error)
-        });
-      }
-    }
-  }
-  removeAllListeners(event) {
-    if (event) {
-      this.registry.delete(event);
-      return;
-    }
-    this.registry.clear();
-  }
-  listenerCount(event) {
-    if (event) {
-      return this.registry.get(event)?.size ?? 0;
-    }
-    let total = 0;
-    for (const listeners of this.registry.values()) {
-      total += listeners.size;
-    }
-    return total;
-  }
-};
-
 // src/base/agent.ts
 init_tool();
 function sanitizeId(name) {
@@ -929,10 +935,6 @@ var BaseAgent = class {
    * Hook manager for lifecycle events
    */
   hooks;
-  /**
-   * Event dispatcher for runtime events (notably streaming)
-   */
-  events;
   /**
    * Registry of available tools
    */
@@ -987,7 +989,6 @@ var BaseAgent = class {
     this.enableStreaming = config.enableStreaming ?? false;
     this.metadata = { ...config.metadata ?? {} };
     this.hooks = new HookManager();
-    this.events = new AgentEventEmitter();
     this.tools = /* @__PURE__ */ new Map();
     this.baseTools = /* @__PURE__ */ new Map();
     this.toolProviders = /* @__PURE__ */ new Set();
@@ -1038,11 +1039,37 @@ var BaseAgent = class {
    * Main entry point for agent execution.
    * Orchestrates lifecycle: context initialization, hook triggering, loop execution, teardown.
    *
+   * **Note:** This method will be removed in a future update.
+   * Consider using {@link run} instead, which returns both result and usage statistics.
+   *
    * @param input - Input to process
    * @param parentSpanId - Optional parent span ID for tracing
    * @returns Processed output
    */
   async process(input, parentSpanId) {
+    const { result } = await this.executeProcess(input, parentSpanId);
+    return result;
+  }
+  /**
+   * Process input and return both result and usage statistics.
+   * This is the recommended method for agent execution.
+   *
+   * @param input - Input to process
+   * @param parentSpanId - Optional parent span ID for tracing
+   * @returns Object containing the result and usage statistics
+   */
+  async run(input, parentSpanId) {
+    return this.executeProcess(input, parentSpanId);
+  }
+  /**
+   * Internal method that executes the process and returns both result and usage.
+   * This is the core implementation shared by process() and run().
+   *
+   * @param input - Input to process
+   * @param parentSpanId - Optional parent span ID for tracing
+   * @returns Object containing the result and usage statistics
+   */
+  async executeProcess(input, parentSpanId) {
     const validatedInput = this.inputSchema ? this.inputSchema.parse(input) : input;
     const context = await this.initializeContext(validatedInput, parentSpanId);
     try {
@@ -1054,7 +1081,8 @@ var BaseAgent = class {
         context,
         result: validatedOutput
       });
-      return validatedOutput;
+      context.cleanupBreakdownIfOnlyParent(this.name);
+      return { result: validatedOutput, usage: context.usage };
     } catch (error) {
       await this.triggerHook(HookEvents.AgentEnd, {
         context,
@@ -1144,6 +1172,8 @@ var BaseAgent = class {
   }
   /**
    * Convert this agent into a tool that can be used by other agents.
+   * When used as a tool, the nested agent's usage statistics are propagated
+   * back to the parent agent for aggregation.
    *
    * @param toolName - Optional custom name for the tool (defaults to agent name)
    * @param toolDescription - Optional custom description (defaults to agent description)
@@ -1163,8 +1193,8 @@ var BaseAgent = class {
       execute: async (input, executionContext) => {
         try {
           const parentSpanId = executionContext.spanId ?? executionContext.agentContext.parentSpanId ?? void 0;
-          const result = await this.process(input, parentSpanId);
-          return ToolResultFactory.success(tool2.name, result);
+          const { result, usage } = await this.run(input, parentSpanId);
+          return ToolResultFactory.success(tool2.name, result, { usage });
         } catch (error) {
           return ToolResultFactory.failure(
             tool2.name,
@@ -1187,32 +1217,34 @@ var BaseAgent = class {
   }
   /**
    * Register an event listener.
+   * This is equivalent to registerHook() - both methods use the unified hook system.
    *
-   * @param event - Event name
+   * @param event - Event name (any HookEvents value)
    * @param listener - Listener callback
    * @returns Cleanup function to unregister the listener
    */
   on(event, listener) {
-    return this.events.on(event, listener);
+    return this.hooks.on(event, listener);
   }
   /**
    * Register a one-time event listener that removes itself after the first call.
+   * This is equivalent to calling registerHook() with a self-removing handler.
    *
-   * @param event - Event name
+   * @param event - Event name (any HookEvents value)
    * @param listener - Listener callback
    * @returns Cleanup function (no-op once listener fires)
    */
   once(event, listener) {
-    return this.events.once(event, listener);
+    return this.hooks.once(event, listener);
   }
   /**
    * Remove a previously registered event listener.
    *
-   * @param event - Event name
+   * @param event - Event name (any HookEvents value)
    * @param listener - Listener callback to remove
    */
   off(event, listener) {
-    this.events.off(event, listener);
+    this.hooks.off(event, listener);
   }
   /**
    * Trigger a hook event with a payload.
@@ -1228,15 +1260,6 @@ var BaseAgent = class {
       console.warn(`Hook error for event ${event}:`, error);
     }
   }
-  /**
-   * Emit a runtime event to listeners.
-   *
-   * @param event - Event name
-   * @param payload - Event payload
-   */
-  emitAgentEvent(event, payload) {
-    this.events.emit(event, payload);
-  }
   /**
    * Execute a tool with proper context, hooks, and error handling.
    *
@@ -1422,6 +1445,11 @@ var BaseAgent = class {
 
 // src/index.ts
 init_context();
+
+// src/base/events.ts
+var AgentEvents = HookEvents;
+
+// src/index.ts
 init_result();
 init_tool();
 var ThoughtSchema = z.object({
@@ -1590,7 +1618,7 @@ var mergeSchemaDefaults = (schema, value) => {
 
 // package.json
 var package_default = {
-  version: "0.3.0"};
+  version: "0.4.0"};
 
 // src/utils/version.ts
 var SDK_NAME = "@opperai/agents";
@@ -2260,7 +2288,7 @@ var Agent = class extends BaseAgent {
         model: this.model,
         ...context.parentSpanId && { parentSpanId: context.parentSpanId }
       });
-      context.updateUsage({
+      context.updateUsageWithSource(this.name, {
         requests: 1,
         inputTokens: response.usage.inputTokens,
         outputTokens: response.usage.outputTokens,
@@ -2312,10 +2340,6 @@ var Agent = class extends BaseAgent {
       context,
       callType: "think"
     });
-    this.emitAgentEvent(HookEvents.StreamStart, {
-      context,
-      callType: "think"
-    });
     try {
       const streamResponse = await this.opperClient.stream({
         name: spanName,
@@ -2352,7 +2376,6 @@ var Agent = class extends BaseAgent {
           fieldBuffers: feedResult.snapshot
         };
         await this.triggerHook(HookEvents.StreamChunk, chunkPayload);
-        this.emitAgentEvent(HookEvents.StreamChunk, chunkPayload);
       }
       const fieldBuffers = assembler.snapshot();
       const endPayload = {
@@ -2361,7 +2384,6 @@ var Agent = class extends BaseAgent {
         fieldBuffers
       };
       await this.triggerHook(HookEvents.StreamEnd, endPayload);
-      this.emitAgentEvent(HookEvents.StreamEnd, endPayload);
       const finalize = assembler.finalize();
       let decision;
       if (finalize.type === "structured" && finalize.structured) {
@@ -2378,7 +2400,7 @@ var Agent = class extends BaseAgent {
         streamSpanId
       );
       if (!usageTracked) {
-        context.updateUsage({
+        context.updateUsageWithSource(this.name, {
           requests: 1,
           inputTokens: 0,
           outputTokens: 0,
@@ -2423,11 +2445,6 @@ var Agent = class extends BaseAgent {
         callType: "think",
         error
       });
-      this.emitAgentEvent(HookEvents.StreamError, {
-        context,
-        callType: "think",
-        error
-      });
       this.logger.error("Think step failed", error);
       throw new Error(
         `Think step failed: ${error instanceof Error ? error.message : String(error)}`
@@ -2485,12 +2502,30 @@ The memory you write persists across all process() calls on this agent.`;
    * Build dynamic context for the think step
    */
   async buildThinkContext(input, context) {
-    const availableTools = Array.from(this.tools.values()).map((tool2) => ({
-      name: tool2.name,
-      description: tool2.description || "",
-      // Convert Zod schema to JSON Schema for LLM consumption
-      parameters: tool2.schema ? schemaToJson(tool2.schema) : {}
-    }));
+    const availableTools = Array.from(this.tools.values()).map((tool2) => {
+      let parameters = {};
+      if (tool2.schema) {
+        parameters = schemaToJson(tool2.schema);
+      } else if (tool2.metadata?.["parameters"] && typeof tool2.metadata["parameters"] === "object") {
+        parameters = tool2.metadata["parameters"];
+      }
+      let returns = void 0;
+      if (tool2.outputSchema) {
+        returns = schemaToJson(tool2.outputSchema);
+      } else if (tool2.metadata?.["outputSchema"] && typeof tool2.metadata["outputSchema"] === "object") {
+        returns = tool2.metadata["outputSchema"];
+      }
+      return {
+        name: tool2.name,
+        description: tool2.description || "",
+        // Include parameters (from Zod schema or MCP metadata)
+        parameters,
+        // Include output schema if defined (helps LLM understand what tool returns)
+        ...returns !== void 0 ? { returns } : {},
+        // Include examples if defined (helps LLM understand expected behavior)
+        ...tool2.examples ? { examples: tool2.examples } : {}
+      };
+    });
     const executionHistory = context.getLastNCycles(3).map((cycle) => {
       const thought = typeof cycle.thought === "object" && cycle.thought !== null ? cycle.thought["reasoning"] || "" : String(cycle.thought || "");
       const results = Array.isArray(cycle.results) ? cycle.results.map((r) => {
@@ -2560,6 +2595,9 @@ The memory you write persists across all process() calls on this agent.`;
           context,
           { spanId: toolSpan.id }
         );
+        if (result.usage) {
+          context.updateUsageWithSource(toolCall.toolName, result.usage);
+        }
         const endTime = /* @__PURE__ */ new Date();
         const durationMs = endTime.getTime() - startTime.getTime();
         if (result.success) {
@@ -2818,7 +2856,7 @@ Follow any instructions provided for formatting and style.`;
         callOptions.outputSchema = this.outputSchema;
       }
       const response = await this.opperClient.call(callOptions);
-      context.updateUsage({
+      context.updateUsageWithSource(this.name, {
         requests: 1,
         inputTokens: response.usage.inputTokens,
         outputTokens: response.usage.outputTokens,
@@ -2848,10 +2886,6 @@ Follow any instructions provided for formatting and style.`;
       context,
       callType: "final_result"
     });
-    this.emitAgentEvent(HookEvents.StreamStart, {
-      context,
-      callType: "final_result"
-    });
     try {
       const sanitizedName = this.name.toLowerCase().replace(/[\s-]/g, "_");
       const functionName = `generate_final_result_${sanitizedName}`;
@@ -2890,7 +2924,6 @@ Follow any instructions provided for formatting and style.`;
           fieldBuffers: feedResult.snapshot
         };
         await this.triggerHook(HookEvents.StreamChunk, chunkPayload);
-        this.emitAgentEvent(HookEvents.StreamChunk, chunkPayload);
       }
       const fieldBuffers = assembler.snapshot();
       const endPayload = {
@@ -2899,7 +2932,6 @@ Follow any instructions provided for formatting and style.`;
         fieldBuffers
       };
       await this.triggerHook(HookEvents.StreamEnd, endPayload);
-      this.emitAgentEvent(HookEvents.StreamEnd, endPayload);
       const finalize = assembler.finalize();
       let result;
       if (this.outputSchema) {
@@ -2923,7 +2955,7 @@ Follow any instructions provided for formatting and style.`;
         streamSpanId
       );
       if (!usageTracked) {
-        context.updateUsage({
+        context.updateUsageWithSource(this.name, {
           requests: 1,
           inputTokens: 0,
           outputTokens: 0,
@@ -2947,11 +2979,6 @@ Follow any instructions provided for formatting and style.`;
         callType: "final_result",
         error
       });
-      this.emitAgentEvent(HookEvents.StreamError, {
-        context,
-        callType: "final_result",
-        error
-      });
       this.logger.error("Failed to generate final result", error);
       throw new Error(
         `Failed to generate final result: ${error instanceof Error ? error.message : String(error)}`
@@ -2987,7 +3014,7 @@ Follow any instructions provided for formatting and style.`;
         const fallbackTotal = record["total_tokens"];
         const totalTokensRaw = typeof primaryTotal === "number" && Number.isFinite(primaryTotal) ? primaryTotal : typeof fallbackTotal === "number" && Number.isFinite(fallbackTotal) ? fallbackTotal : void 0;
         if (totalTokensRaw !== void 0) {
-          context.updateUsage({
+          context.updateUsageWithSource(this.name, {
             requests: 1,
             inputTokens: 0,
             outputTokens: 0,
@@ -3439,6 +3466,8 @@ function createToolDefinition(options, methodName, propertyKey, method, callTarg
     name,
     description,
     ...options.schema && { schema: options.schema },
+    ...options.outputSchema && { outputSchema: options.outputSchema },
+    ...options.examples && { examples: options.examples },
     ...options.timeoutMs !== void 0 && { timeoutMs: options.timeoutMs },
     metadata: {
       ...options.metadata,
@@ -3455,6 +3484,8 @@ function createFunctionTool(fn, options = {}) {
     name,
     description,
     ...options.schema && { schema: options.schema },
+    ...options.outputSchema && { outputSchema: options.outputSchema },
+    ...options.examples && { examples: options.examples },
     ...options.timeoutMs !== void 0 && { timeoutMs: options.timeoutMs },
     metadata: {
       ...options.metadata,
@@ -3770,6 +3801,6 @@ var ToolRunner = class {
   }
 };
 
-export { Agent, AgentContext, AgentDecisionSchema, AgentEventEmitter, AgentEvents, BaseAgent, ConsoleLogger, DEFAULT_MODEL, DEFAULT_RETRY_CONFIG, ExecutionCycleSchema, HookEvents, HookManager, InMemoryStore, LogLevel, MCPClient, MCPServerConfigSchema, MCPToolProvider, MCPconfig, MemoryEntryMetadataSchema, MemoryEntrySchema, MemoryUpdateSchema, OpperClient, Result, STREAM_ROOT_PATH, SchemaValidationError, SilentLogger, StreamAssembler, ThoughtSchema, ToolCallRecordSchema, ToolCallSchema, ToolExecutionSummarySchema, ToolMetadataSchema, ToolResultFactory, ToolResultFailureSchema, ToolResultSchema, ToolResultSuccessSchema, ToolRunner, UsageSchema, coerceToolDefinition, createAgentDecisionWithOutputSchema, createFunctionTool, createHookManager, createInMemoryStore, createMCPServerConfig, createOpperClient, createStreamAssembler, createToolCallRecord, err, extractTools, generateAgentFlowDiagram, getDefaultLogger, getSchemaDefault, isSchemaValid, isToolProvider, mcp, mergeSchemaDefaults, normalizeToolEntries, ok, schemaToJson, setDefaultLogger, tool, validateSchema, validateToolInput, zodSchemaToJsonSchema };
+export { Agent, AgentContext, AgentDecisionSchema, AgentEvents, BaseAgent, BaseUsageSchema, ConsoleLogger, DEFAULT_MODEL, DEFAULT_RETRY_CONFIG, ExecutionCycleSchema, HookEvents, HookManager, InMemoryStore, LogLevel, MCPClient, MCPServerConfigSchema, MCPToolProvider, MCPconfig, MemoryEntryMetadataSchema, MemoryEntrySchema, MemoryUpdateSchema, OpperClient, Result, STREAM_ROOT_PATH, SchemaValidationError, SilentLogger, StreamAssembler, ThoughtSchema, ToolCallRecordSchema, ToolCallSchema, ToolExecutionSummarySchema, ToolMetadataSchema, ToolResultFactory, ToolResultFailureSchema, ToolResultSchema, ToolResultSuccessSchema, ToolRunner, UsageSchema, addUsage, coerceToolDefinition, createAgentDecisionWithOutputSchema, createEmptyUsage, createFunctionTool, createHookManager, createInMemoryStore, createMCPServerConfig, createOpperClient, createStreamAssembler, createToolCallRecord, err, extractTools, generateAgentFlowDiagram, getDefaultLogger, getSchemaDefault, isSchemaValid, isToolProvider, mcp, mergeSchemaDefaults, normalizeToolEntries, ok, schemaToJson, setDefaultLogger, tool, validateSchema, validateToolInput, zodSchemaToJsonSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map