@opperai/agents 0.3.0-beta.1 → 0.4.0

package/README.md

@@ -48,10 +48,13 @@ const agent = new Agent<string, OutputType>({
   outputSchema: Output,
 });
 
-const result = await agent.process("Say hi to Ada");
-// => { message: "Hi Ada!" }
+const { result, usage } = await agent.run("Say hi to Ada");
+// result => { message: "Hi Ada!" }
+// usage => { requests, inputTokens, outputTokens, totalTokens }
 ```
 
+> **Note:** `agent.process(input)` also works if you only need the result without usage stats.
+
 ## Tools
 
 Define tools with Zod schemas. Results are discriminated unions that never throw.
@@ -72,7 +75,7 @@ const agent = new Agent<string, { answer: number }>({
   outputSchema: z.object({ answer: z.number() }),
 });
 
-const res = await agent.process("What is (5 + 3)? Return JSON with answer.");
+const { result } = await agent.run("What is (5 + 3)? Return JSON with answer.");
 ```
 
 Decorator tools and extraction:
@@ -111,9 +114,10 @@ const Coordinator = new Agent<string, string>({
   tools: [Summarize.asTool("summarize")],
 });
 
-const answer = await Coordinator.process(
+const { result, usage } = await Coordinator.run(
   "Summarize: Opper helps you build agents.",
 );
+// usage includes aggregated stats from nested Summarize agent
 ```
 
 ## MCP Integration
@@ -131,7 +135,7 @@ const agent = new Agent<string, string>({
   tools: [mcp(fsServer)],
 });
 
-const out = await agent.process("Read README.md and summarize it.");
+const { result } = await agent.run("Read README.md and summarize it.");
 ```
 
 ## Hooks & Context

package/dist/index.cjs

@@ -121,7 +121,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 }
         };
         exports.ToolResultSuccessSchema.parse(result);
         return result;
@@ -133,7 +134,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 }
         };
         exports.ToolResultFailureSchema.parse(result);
         return result;
@@ -188,14 +190,43 @@ var init_tool = __esm({
 var context_exports = {};
 __export(context_exports, {
   AgentContext: () => exports.AgentContext,
+  BaseUsageSchema: () => exports.BaseUsageSchema,
   ExecutionCycleSchema: () => exports.ExecutionCycleSchema,
-  UsageSchema: () => exports.UsageSchema
+  UsageSchema: () => exports.UsageSchema,
+  addUsage: () => addUsage,
+  createEmptyUsage: () => createEmptyUsage
 });
-exports.UsageSchema = void 0; exports.ExecutionCycleSchema = void 0; exports.AgentContext = void 0;
+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
+    }
+  };
+}
+exports.BaseUsageSchema = void 0; exports.UsageSchema = void 0; exports.ExecutionCycleSchema = void 0; exports.AgentContext = void 0;
 var init_context = __esm({
   "src/base/context.ts"() {
     init_tool();
-    exports.UsageSchema = zod.z.object({
+    exports.BaseUsageSchema = zod.z.object({
       requests: zod.z.number().int().nonnegative().default(0),
       inputTokens: zod.z.number().int().nonnegative().default(0),
       outputTokens: zod.z.number().int().nonnegative().default(0),
@@ -206,6 +237,13 @@ var init_context = __esm({
         total: zod.z.number().nonnegative().default(0)
       }).default({ generation: 0, platform: 0, total: 0 })
     });
+    exports.UsageSchema = exports.BaseUsageSchema.extend({
+      /**
+       * Optional breakdown of usage by source (agent name).
+       * Only present when nested agents are used.
+       */
+      breakdown: zod.z.record(zod.z.string(), zod.z.lazy(() => exports.BaseUsageSchema)).optional()
+    });
     exports.ExecutionCycleSchema = zod.z.object({
       iteration: zod.z.number().int().nonnegative(),
       thought: zod.z.unknown().nullable().optional(),
@@ -247,10 +285,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 = exports.ExecutionCycleSchema.parse(cycle);
         this.executionHistory.push(parsed);
@@ -296,6 +366,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,
@@ -303,7 +385,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,
@@ -490,82 +572,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) {
@@ -950,10 +956,6 @@ var BaseAgent = class {
    * Hook manager for lifecycle events
    */
   hooks;
-  /**
-   * Event dispatcher for runtime events (notably streaming)
-   */
-  events;
   /**
    * Registry of available tools
    */
@@ -1008,7 +1010,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();
@@ -1059,11 +1060,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 {
@@ -1075,7 +1102,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,
@@ -1165,6 +1193,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)
@@ -1184,8 +1214,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 exports.ToolResultFactory.success(tool2.name, result);
+          const { result, usage } = await this.run(input, parentSpanId);
+          return exports.ToolResultFactory.success(tool2.name, result, { usage });
         } catch (error) {
           return exports.ToolResultFactory.failure(
             tool2.name,
@@ -1208,32 +1238,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.
@@ -1249,15 +1281,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.
    *
@@ -1443,6 +1466,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 = zod.z.object({
@@ -1611,7 +1639,7 @@ var mergeSchemaDefaults = (schema, value) => {
 
 // package.json
 var package_default = {
-  version: "0.3.0-beta.1"};
+  version: "0.4.0"};
 
 // src/utils/version.ts
 var SDK_NAME = "@opperai/agents";
@@ -2281,7 +2309,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,
@@ -2333,10 +2361,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,
@@ -2373,7 +2397,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 = {
@@ -2382,7 +2405,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) {
@@ -2399,7 +2421,7 @@ var Agent = class extends BaseAgent {
         streamSpanId
       );
       if (!usageTracked) {
-        context.updateUsage({
+        context.updateUsageWithSource(this.name, {
           requests: 1,
           inputTokens: 0,
           outputTokens: 0,
@@ -2444,11 +2466,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)}`
@@ -2506,12 +2523,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) => {
@@ -2581,6 +2616,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) {
@@ -2839,7 +2877,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,
@@ -2869,10 +2907,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}`;
@@ -2911,7 +2945,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 = {
@@ -2920,7 +2953,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) {
@@ -2944,7 +2976,7 @@ Follow any instructions provided for formatting and style.`;
         streamSpanId
       );
       if (!usageTracked) {
-        context.updateUsage({
+        context.updateUsageWithSource(this.name, {
           requests: 1,
           inputTokens: 0,
           outputTokens: 0,
@@ -2968,11 +3000,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)}`
@@ -3008,7 +3035,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,
@@ -3460,6 +3487,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,
@@ -3476,6 +3505,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,
@@ -3793,7 +3824,6 @@ var ToolRunner = class {
 
 exports.Agent = Agent;
 exports.AgentDecisionSchema = AgentDecisionSchema;
-exports.AgentEventEmitter = AgentEventEmitter;
 exports.AgentEvents = AgentEvents;
 exports.BaseAgent = BaseAgent;
 exports.ConsoleLogger = ConsoleLogger;
@@ -3819,7 +3849,9 @@ exports.ThoughtSchema = ThoughtSchema;
 exports.ToolCallSchema = ToolCallSchema;
 exports.ToolExecutionSummarySchema = ToolExecutionSummarySchema;
 exports.ToolRunner = ToolRunner;
+exports.addUsage = addUsage;
 exports.createAgentDecisionWithOutputSchema = createAgentDecisionWithOutputSchema;
+exports.createEmptyUsage = createEmptyUsage;
 exports.createFunctionTool = createFunctionTool;
 exports.createHookManager = createHookManager;
 exports.createInMemoryStore = createInMemoryStore;