@opperai/agents 0.1.3 → 0.3.0-beta

package/dist/index.cjs

@@ -394,7 +394,11 @@ var HookEvents = {
   ToolError: "tool:error",
   MemoryRead: "memory:read",
   MemoryWrite: "memory:write",
-  MemoryError: "memory:error"
+  MemoryError: "memory:error",
+  StreamStart: "stream:start",
+  StreamChunk: "stream:chunk",
+  StreamEnd: "stream:end",
+  StreamError: "stream:error"
 };
 var HookManager = class {
   registry = /* @__PURE__ */ new Map();
@@ -466,6 +470,82 @@ 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) {
@@ -825,6 +905,10 @@ var BaseAgent = class {
    * Whether memory is enabled
    */
   enableMemory;
+  /**
+   * Whether streaming is enabled
+   */
+  enableStreaming;
   /**
    * Memory instance for persistent storage (null if disabled or initialization failed)
    */
@@ -837,6 +921,10 @@ var BaseAgent = class {
    * Hook manager for lifecycle events
    */
   hooks;
+  /**
+   * Event dispatcher for runtime events (notably streaming)
+   */
+  events;
   /**
    * Registry of available tools
    */
@@ -857,6 +945,28 @@ var BaseAgent = class {
    * Opper client configuration
    */
   opperConfig;
+  /**
+   * Creates a new BaseAgent instance
+   *
+   * @param config - Agent configuration object
+   * @param config.name - Unique name identifying this agent (required)
+   * @param config.description - Human-readable description of the agent's purpose
+   * @param config.instructions - System instructions guiding agent behavior
+   * @param config.tools - Array of tools or tool providers available to the agent
+   * @param config.maxIterations - Maximum iterations before terminating the agent loop (default: 25)
+   * @param config.model - Model identifier(s). Single model or array for fallback (default: "gcp/gemini-flash-latest")
+   * @param config.inputSchema - Zod schema for input validation
+   * @param config.outputSchema - Zod schema for output validation
+   * @param config.enableStreaming - Enable Opper streaming APIs for LLM calls (default: false)
+   * @param config.enableMemory - Enable memory subsystem (default: false)
+   * @param config.memory - Custom memory implementation (defaults to InMemoryStore if enableMemory is true)
+   * @param config.metadata - Additional metadata for the agent
+   * @param config.opperConfig - Opper API configuration containing apiKey and baseUrl
+   * @param config.onStreamStart - Handler invoked when a streaming call starts
+   * @param config.onStreamChunk - Handler invoked for each streaming chunk
+   * @param config.onStreamEnd - Handler invoked when a streaming call ends
+   * @param config.onStreamError - Handler invoked when streaming encounters an error
+   */
   constructor(config) {
     this.name = config.name;
     this.description = config.description;
@@ -866,12 +976,26 @@ var BaseAgent = class {
     this.inputSchema = config.inputSchema;
     this.outputSchema = config.outputSchema;
     this.enableMemory = config.enableMemory ?? false;
+    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();
     this.providerToolRegistry = /* @__PURE__ */ new Map();
+    if (config.onStreamStart) {
+      this.on(HookEvents.StreamStart, config.onStreamStart);
+    }
+    if (config.onStreamChunk) {
+      this.on(HookEvents.StreamChunk, config.onStreamChunk);
+    }
+    if (config.onStreamEnd) {
+      this.on(HookEvents.StreamEnd, config.onStreamEnd);
+    }
+    if (config.onStreamError) {
+      this.on(HookEvents.StreamError, config.onStreamError);
+    }
     this.opperConfig = {
       apiKey: config.opperConfig?.apiKey ?? process.env["OPPER_API_KEY"],
       baseUrl: config.opperConfig?.baseUrl,
@@ -1053,6 +1177,35 @@ var BaseAgent = class {
   registerHook(event, handler) {
     return this.hooks.on(event, handler);
   }
+  /**
+   * Register an event listener.
+   *
+   * @param event - Event name
+   * @param listener - Listener callback
+   * @returns Cleanup function to unregister the listener
+   */
+  on(event, listener) {
+    return this.events.on(event, listener);
+  }
+  /**
+   * Register a one-time event listener that removes itself after the first call.
+   *
+   * @param event - Event name
+   * @param listener - Listener callback
+   * @returns Cleanup function (no-op once listener fires)
+   */
+  once(event, listener) {
+    return this.events.once(event, listener);
+  }
+  /**
+   * Remove a previously registered event listener.
+   *
+   * @param event - Event name
+   * @param listener - Listener callback to remove
+   */
+  off(event, listener) {
+    this.events.off(event, listener);
+  }
   /**
    * Trigger a hook event with a payload.
    * Swallows errors to prevent hook failures from breaking agent execution.
@@ -1067,6 +1220,15 @@ 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.
    *
@@ -1305,6 +1467,10 @@ var AgentDecisionSchema = zod.z.object({
    * Agent's internal reasoning
    */
   reasoning: zod.z.string(),
+  /**
+   * Status message for the user (e.g., "Searching for information...", "Processing results...")
+   */
+  userMessage: zod.z.string().default("Working on it..."),
   /**
    * Tool calls to execute (if any)
    * Empty array signals task completion
@@ -1317,8 +1483,34 @@ var AgentDecisionSchema = zod.z.object({
   /**
    * Memory entries to write/update (key -> payload)
    */
-  memoryUpdates: zod.z.record(MemoryUpdateSchema).default({})
+  memoryUpdates: zod.z.record(MemoryUpdateSchema).default({}),
+  /**
+   * Whether the task is complete and finalResult is available
+   * (single LLM call pattern)
+   */
+  isComplete: zod.z.boolean().default(false),
+  /**
+   * The final result when isComplete=true
+   * Should match outputSchema if specified
+   */
+  finalResult: zod.z.unknown().optional()
 });
+function createAgentDecisionWithOutputSchema(outputSchema) {
+  if (!outputSchema) {
+    return AgentDecisionSchema;
+  }
+  const finalResultSchema = outputSchema.optional();
+  const dynamicSchema = zod.z.object({
+    reasoning: zod.z.string(),
+    userMessage: zod.z.string().default("Working on it..."),
+    toolCalls: zod.z.array(ToolCallSchema).default([]),
+    memoryReads: zod.z.array(zod.z.string()).default([]),
+    memoryUpdates: zod.z.record(MemoryUpdateSchema).default({}),
+    isComplete: zod.z.boolean().default(false),
+    finalResult: finalResultSchema
+  });
+  return dynamicSchema;
+}
 var ToolExecutionSummarySchema = zod.z.object({
   /**
    * Tool name
@@ -1340,7 +1532,7 @@ var ToolExecutionSummarySchema = zod.z.object({
 
 // package.json
 var package_default = {
-  version: "0.1.3"};
+  version: "0.3.0-beta"};
 
 // src/utils/version.ts
 var SDK_NAME = "@opperai/agents";
@@ -1403,7 +1595,7 @@ var OpperClient = class {
     return this.withRetry(async () => {
       const inputSchema = this.toJsonSchema(options.inputSchema);
       const outputSchema = this.toJsonSchema(options.outputSchema);
-      const response = await this.client.call({
+      const callPayload = {
         name: options.name,
         instructions: options.instructions,
         input: options.input,
@@ -1411,7 +1603,8 @@ var OpperClient = class {
         ...outputSchema && { outputSchema },
         ...options.model && { model: options.model },
         ...options.parentSpanId && { parentSpanId: options.parentSpanId }
-      });
+      };
+      const response = options.signal ? await this.client.call(callPayload, { signal: options.signal }) : await this.client.call(callPayload);
       const usagePayload = extractUsage(response);
       const costPayload = extractCost(response);
       const usage = {
@@ -1429,6 +1622,36 @@ var OpperClient = class {
       return result;
     }, options.name);
   }
+  /**
+   * Stream a call to Opper with retry logic
+   */
+  async stream(options) {
+    return this.withRetry(async () => {
+      const inputSchema = this.toJsonSchema(options.inputSchema);
+      const outputSchema = this.toJsonSchema(options.outputSchema);
+      const streamPayload = {
+        name: options.name,
+        instructions: options.instructions,
+        input: options.input,
+        ...inputSchema && { inputSchema },
+        ...outputSchema && { outputSchema },
+        ...options.model && { model: options.model },
+        ...options.parentSpanId && { parentSpanId: options.parentSpanId }
+      };
+      const response = options.signal ? await this.client.stream(streamPayload, { signal: options.signal }) : await this.client.stream(streamPayload);
+      const iterable = {
+        async *[Symbol.asyncIterator]() {
+          for await (const event of response.result) {
+            yield event;
+          }
+        }
+      };
+      return {
+        headers: response.headers,
+        result: iterable
+      };
+    }, `stream:${options.name}`);
+  }
   /**
    * Create a span for tracing
    */
@@ -1437,7 +1660,8 @@ var OpperClient = class {
       const span = await this.client.spans.create({
         name: options.name,
         ...options.input !== void 0 && { input: options.input },
-        ...options.parentSpanId && { parentId: options.parentSpanId }
+        ...options.parentSpanId && { parentId: options.parentSpanId },
+        ...options.type && { type: options.type }
       });
       return {
         id: span.id,
@@ -1454,7 +1678,11 @@ var OpperClient = class {
       const serializedOutput = output !== void 0 && output !== null ? typeof output === "object" ? JSON.stringify(output) : String(output) : void 0;
       await this.client.spans.update(spanId, {
         ...serializedOutput !== void 0 && { output: serializedOutput },
-        ...options?.error && { error: options.error }
+        ...options?.error && { error: options.error },
+        ...options?.startTime && { startTime: options.startTime },
+        ...options?.endTime && { endTime: options.endTime },
+        ...options?.meta && { meta: options.meta },
+        ...options?.name && { name: options.name }
       });
     }, `update-span:${spanId}`);
   }
@@ -1597,6 +1825,193 @@ var mergeSchemaDefaults = (schema, value) => {
   return validateSchema(schema, value);
 };
 
+// src/utils/streaming.ts
+var STREAM_ROOT_PATH = "_root";
+var NUMERIC_TOKEN_PATTERN = /^\d+$/;
+var BRACKET_TOKEN_PATTERN = /\[(\d+)\]/g;
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var coercePrimitive = (value) => {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    return value;
+  }
+  const lower = trimmed.toLowerCase();
+  if (lower === "true") {
+    return true;
+  }
+  if (lower === "false") {
+    return false;
+  }
+  if (lower === "null") {
+    return null;
+  }
+  if (/^-?\d+$/.test(trimmed)) {
+    const intValue = Number.parseInt(trimmed, 10);
+    return Number.isNaN(intValue) ? value : intValue;
+  }
+  if (/^-?\d+\.\d+$/.test(trimmed)) {
+    const floatValue = Number.parseFloat(trimmed);
+    return Number.isNaN(floatValue) ? value : floatValue;
+  }
+  return value;
+};
+var toDisplayString = (value) => {
+  if (value === null || value === void 0) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return String(value);
+};
+var parsePathSegments = (path) => {
+  return path.replace(BRACKET_TOKEN_PATTERN, (_, index) => `.${index}`).split(".").map((segment) => segment.trim()).filter((segment) => segment.length > 0);
+};
+var setNestedValue = (target, path, value) => {
+  const segments = parsePathSegments(path);
+  if (segments.length === 0) {
+    return;
+  }
+  let current = target;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i];
+    if (segment === void 0) {
+      return;
+    }
+    const existing = current[segment];
+    if (!isRecord(existing)) {
+      const nextLevel = {};
+      current[segment] = nextLevel;
+      current = nextLevel;
+      continue;
+    }
+    current = existing;
+  }
+  const lastSegment = segments[segments.length - 1];
+  if (lastSegment === void 0) {
+    return;
+  }
+  current[lastSegment] = value;
+};
+var normalizeIndexed = (value) => {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeIndexed(item));
+  }
+  if (!isRecord(value)) {
+    return value;
+  }
+  const normalizedEntries = {};
+  for (const [key, entryValue] of Object.entries(value)) {
+    normalizedEntries[key] = normalizeIndexed(entryValue);
+  }
+  const keys = Object.keys(normalizedEntries);
+  if (keys.length > 0 && keys.every((key) => NUMERIC_TOKEN_PATTERN.test(key))) {
+    const parsedIndices = keys.map((key) => Number.parseInt(key, 10)).filter((index) => Number.isFinite(index) && index >= 0);
+    if (parsedIndices.length === 0) {
+      return normalizedEntries;
+    }
+    const maxIndex = Math.max(...parsedIndices);
+    const result = new Array(maxIndex + 1).fill(void 0);
+    for (const [key, entryValue] of Object.entries(normalizedEntries)) {
+      const index = Number.parseInt(key, 10);
+      if (!Number.isFinite(index) || index < 0) {
+        continue;
+      }
+      result[index] = entryValue;
+    }
+    return result.map(
+      (item) => item === void 0 ? null : item
+    );
+  }
+  return normalizedEntries;
+};
+var resolveFieldValue = (path, displayBuffers, valueBuffers) => {
+  const values = valueBuffers.get(path) ?? [];
+  if (values.length === 0) {
+    return displayBuffers.get(path) ?? "";
+  }
+  const last = values[values.length - 1];
+  if (typeof last === "number" || typeof last === "boolean") {
+    return last;
+  }
+  if (last === null) {
+    return null;
+  }
+  const joined = displayBuffers.get(path) ?? values.map((value) => toDisplayString(value)).join("");
+  return coercePrimitive(joined);
+};
+var StreamAssembler = class {
+  displayBuffers = /* @__PURE__ */ new Map();
+  valueBuffers = /* @__PURE__ */ new Map();
+  schema;
+  constructor(options = {}) {
+    this.schema = options.schema;
+  }
+  feed(chunk) {
+    const { delta } = chunk;
+    if (delta === null || delta === void 0) {
+      return null;
+    }
+    const path = chunk.jsonPath === null || chunk.jsonPath === void 0 ? STREAM_ROOT_PATH : chunk.jsonPath;
+    const existingDisplay = this.displayBuffers.get(path) ?? "";
+    const nextDisplay = `${existingDisplay}${toDisplayString(delta)}`;
+    this.displayBuffers.set(path, nextDisplay);
+    const existingValues = this.valueBuffers.get(path) ?? [];
+    existingValues.push(delta);
+    this.valueBuffers.set(path, existingValues);
+    return {
+      path,
+      accumulated: nextDisplay,
+      snapshot: this.snapshot()
+    };
+  }
+  snapshot() {
+    return Object.fromEntries(this.displayBuffers.entries());
+  }
+  hasStructuredFields() {
+    const keys = Array.from(this.displayBuffers.keys());
+    return keys.some((key) => key !== STREAM_ROOT_PATH);
+  }
+  finalize() {
+    if (this.displayBuffers.size === 0) {
+      return { type: "empty" };
+    }
+    if (!this.hasStructuredFields()) {
+      const root = this.displayBuffers.get(STREAM_ROOT_PATH) ?? "";
+      return { type: "root", rootText: root };
+    }
+    const structured = this.reconstructStructured();
+    let coerced = structured;
+    if (this.schema !== void 0) {
+      try {
+        coerced = this.schema.parse(structured);
+      } catch {
+        coerced = structured;
+      }
+    }
+    return { type: "structured", structured: coerced };
+  }
+  getFieldBuffers() {
+    return new Map(this.displayBuffers);
+  }
+  reconstructStructured() {
+    const result = {};
+    for (const path of this.valueBuffers.keys()) {
+      if (path === STREAM_ROOT_PATH) {
+        continue;
+      }
+      const value = resolveFieldValue(
+        path,
+        this.displayBuffers,
+        this.valueBuffers
+      );
+      setNestedValue(result, path, value);
+    }
+    return normalizeIndexed(result);
+  }
+};
+var createStreamAssembler = (options) => new StreamAssembler(options);
+
 // src/core/agent.ts
 var isToolSuccessResult = (value) => {
   if (typeof value !== "object" || value === null) {
@@ -1609,6 +2024,31 @@ var Agent = class extends BaseAgent {
   opperClient;
   logger;
   verbose;
+  /**
+   * Creates a new Agent instance
+   *
+   * @param config - Agent configuration object
+   * @param config.name - Unique name identifying this agent (required)
+   * @param config.description - Human-readable description of the agent's purpose
+   * @param config.instructions - System instructions guiding agent behavior
+   * @param config.tools - Array of tools or tool providers available to the agent
+   * @param config.maxIterations - Maximum iterations before terminating (default: 25)
+   * @param config.model - Model identifier(s) as string or array for fallback (default: "gcp/gemini-flash-latest")
+   * @param config.inputSchema - Zod schema for input validation
+   * @param config.outputSchema - Zod schema for output validation
+   * @param config.enableStreaming - Enable streaming for LLM calls (default: false)
+   * @param config.enableMemory - Enable memory subsystem (default: false)
+   * @param config.memory - Custom memory implementation (defaults to InMemoryStore if enableMemory is true)
+   * @param config.metadata - Additional metadata for the agent
+   * @param config.opperConfig - Opper API configuration (apiKey, baseUrl)
+   * @param config.opperClient - Custom Opper client instance (for testing or custom configuration)
+   * @param config.logger - Logger instance for debugging
+   * @param config.verbose - Enable verbose logging (default: false)
+   * @param config.onStreamStart - Handler invoked when streaming starts
+   * @param config.onStreamChunk - Handler invoked for each streaming chunk
+   * @param config.onStreamEnd - Handler invoked when streaming ends
+   * @param config.onStreamError - Handler invoked on streaming errors
+   */
   constructor(config) {
     super(config);
     this.logger = config.logger ?? getDefaultLogger();
@@ -1644,6 +2084,7 @@ var Agent = class extends BaseAgent {
       maxIterations: this.maxIterations,
       tools: Array.from(this.tools.keys())
     });
+    const executionStartTime = /* @__PURE__ */ new Date();
     const parentSpan = await this.opperClient.createSpan({
       name: `${this.name}_execution`,
       input: this.serializeInput(input),
@@ -1663,6 +2104,47 @@ var Agent = class extends BaseAgent {
             input,
             context
           );
+          if (decision.isComplete && decision.finalResult !== void 0) {
+            this.log("Task completed with final result in single call", {
+              iteration: currentIteration
+            });
+            let finalResult;
+            if (this.outputSchema) {
+              const parseResult = this.outputSchema.safeParse(
+                decision.finalResult
+              );
+              if (parseResult.success) {
+                finalResult = parseResult.data;
+              } else {
+                this.logger.warn(
+                  "Final result validation against output schema failed, falling back to generate_final_result",
+                  { error: parseResult.error.message }
+                );
+                break;
+              }
+            } else {
+              const rawResult = decision.finalResult;
+              if (typeof rawResult === "string") {
+                finalResult = rawResult;
+              } else if (rawResult === null || rawResult === void 0) {
+                finalResult = "";
+              } else if (typeof rawResult === "object") {
+                finalResult = JSON.stringify(rawResult);
+              } else {
+                finalResult = String(rawResult);
+              }
+            }
+            const executionEndTime2 = /* @__PURE__ */ new Date();
+            await this.opperClient.updateSpan(parentSpan.id, finalResult, {
+              startTime: executionStartTime,
+              endTime: executionEndTime2,
+              meta: {
+                durationMs: executionEndTime2.getTime() - executionStartTime.getTime()
+              }
+            });
+            await this.triggerHook(HookEvents.LoopEnd, { context });
+            return finalResult;
+          }
           const memoryResults = await this.handleMemoryActions(
             decision,
             context,
@@ -1672,7 +2154,7 @@ var Agent = class extends BaseAgent {
           const toolResults = await this.executeToolCalls(
             decision,
             context,
-            thinkSpanId
+            context.parentSpanId ?? void 0
           );
           const combinedResults = [...memoryResults, ...toolResults];
           const newToolCalls = context.toolCalls.slice(toolCallStartIndex);
@@ -1707,11 +2189,24 @@ var Agent = class extends BaseAgent {
         );
       }
       const result = await this.generateFinalResult(input, context);
-      await this.opperClient.updateSpan(parentSpan.id, result);
+      const executionEndTime = /* @__PURE__ */ new Date();
+      await this.opperClient.updateSpan(parentSpan.id, result, {
+        startTime: executionStartTime,
+        endTime: executionEndTime,
+        meta: {
+          durationMs: executionEndTime.getTime() - executionStartTime.getTime()
+        }
+      });
       return result;
     } catch (error) {
+      const executionEndTime = /* @__PURE__ */ new Date();
       await this.opperClient.updateSpan(parentSpan.id, void 0, {
-        error: error instanceof Error ? error.message : String(error)
+        error: error instanceof Error ? error.message : String(error),
+        startTime: executionStartTime,
+        endTime: executionEndTime,
+        meta: {
+          durationMs: executionEndTime.getTime() - executionStartTime.getTime()
+        }
       });
       throw error;
     }
@@ -1720,9 +2215,16 @@ var Agent = class extends BaseAgent {
    * Think step: Call LLM to decide next action
    */
   async think(input, context) {
-    const spanName = "think";
+    const sanitizedName = this.name.toLowerCase().replace(/[\s-]/g, "_");
+    const spanName = `think_${sanitizedName}`;
     this.log("Think step", { iteration: context.iteration });
     await this.triggerHook(HookEvents.LlmCall, { context, callType: "think" });
+    const decisionSchema = createAgentDecisionWithOutputSchema(
+      this.outputSchema
+    );
+    if (this.enableStreaming) {
+      return this.thinkStreaming(input, context, decisionSchema, spanName);
+    }
     try {
       const instructions = this.buildThinkInstructions();
       const thinkContext = await this.buildThinkContext(input, context);
@@ -1730,7 +2232,7 @@ var Agent = class extends BaseAgent {
         name: spanName,
         instructions,
         input: thinkContext,
-        outputSchema: AgentDecisionSchema,
+        outputSchema: decisionSchema,
         model: this.model,
         ...context.parentSpanId && { parentSpanId: context.parentSpanId }
       });
@@ -1741,15 +2243,25 @@ var Agent = class extends BaseAgent {
         totalTokens: response.usage.totalTokens,
         cost: response.usage.cost
       });
-      const decision = AgentDecisionSchema.parse(response.jsonPayload);
+      const decision = decisionSchema.parse(
+        response.jsonPayload
+      );
       await this.triggerHook(HookEvents.LlmResponse, {
         context,
         callType: "think",
         response
       });
+      if (response.spanId) {
+        await this.opperClient.updateSpan(response.spanId, void 0, {
+          name: "think"
+        });
+      }
       await this.triggerHook(HookEvents.ThinkEnd, {
         context,
-        thought: { reasoning: decision.reasoning }
+        thought: {
+          reasoning: decision.reasoning,
+          userMessage: decision.userMessage
+        }
       });
       this.log("Think result", {
         reasoning: decision.reasoning,
@@ -1765,6 +2277,139 @@ var Agent = class extends BaseAgent {
       );
     }
   }
+  async thinkStreaming(input, context, decisionSchema, spanName) {
+    const instructions = this.buildThinkInstructions();
+    const thinkContext = await this.buildThinkContext(input, context);
+    const assembler = createStreamAssembler({
+      schema: decisionSchema
+    });
+    let streamSpanId;
+    await this.triggerHook(HookEvents.StreamStart, {
+      context,
+      callType: "think"
+    });
+    this.emitAgentEvent(HookEvents.StreamStart, {
+      context,
+      callType: "think"
+    });
+    try {
+      const streamResponse = await this.opperClient.stream({
+        name: spanName,
+        instructions,
+        input: thinkContext,
+        outputSchema: decisionSchema,
+        model: this.model,
+        ...context.parentSpanId && { parentSpanId: context.parentSpanId }
+      });
+      for await (const event of streamResponse.result) {
+        const data = event?.data;
+        if (!data) {
+          continue;
+        }
+        if (!streamSpanId && typeof data.spanId === "string" && data.spanId) {
+          streamSpanId = data.spanId;
+        }
+        const feedResult = assembler.feed({
+          delta: data.delta,
+          jsonPath: data.jsonPath
+        });
+        if (!feedResult) {
+          continue;
+        }
+        const chunkPayload = {
+          context,
+          callType: "think",
+          chunkData: {
+            delta: data.delta,
+            jsonPath: data.jsonPath ?? null,
+            chunkType: data.chunkType ?? null
+          },
+          accumulated: feedResult.accumulated,
+          fieldBuffers: feedResult.snapshot
+        };
+        await this.triggerHook(HookEvents.StreamChunk, chunkPayload);
+        this.emitAgentEvent(HookEvents.StreamChunk, chunkPayload);
+      }
+      const fieldBuffers = assembler.snapshot();
+      const endPayload = {
+        context,
+        callType: "think",
+        fieldBuffers
+      };
+      await this.triggerHook(HookEvents.StreamEnd, endPayload);
+      this.emitAgentEvent(HookEvents.StreamEnd, endPayload);
+      const finalize = assembler.finalize();
+      let decision;
+      if (finalize.type === "structured" && finalize.structured) {
+        decision = decisionSchema.parse(
+          finalize.structured
+        );
+      } else {
+        decision = decisionSchema.parse({
+          reasoning: finalize.type === "root" ? finalize.rootText ?? "" : ""
+        });
+      }
+      const usageTracked = await this.trackStreamingUsageBySpan(
+        context,
+        streamSpanId
+      );
+      if (!usageTracked) {
+        context.updateUsage({
+          requests: 1,
+          inputTokens: 0,
+          outputTokens: 0,
+          totalTokens: 0,
+          cost: { generation: 0, platform: 0, total: 0 }
+        });
+      }
+      await this.triggerHook(HookEvents.LlmResponse, {
+        context,
+        callType: "think",
+        response: streamResponse,
+        parsed: decision
+      });
+      if (streamSpanId) {
+        await this.opperClient.updateSpan(streamSpanId, void 0, {
+          name: "think"
+        });
+      }
+      await this.triggerHook(HookEvents.ThinkEnd, {
+        context,
+        thought: {
+          reasoning: decision.reasoning,
+          userMessage: decision.userMessage
+        }
+      });
+      this.log("Think result", {
+        reasoning: decision.reasoning,
+        toolCalls: decision.toolCalls.length,
+        memoryReads: decision.memoryReads?.length ?? 0,
+        memoryWrites: Object.keys(decision.memoryUpdates ?? {}).length
+      });
+      const resultPayload = {
+        decision
+      };
+      if (streamSpanId) {
+        resultPayload.spanId = streamSpanId;
+      }
+      return resultPayload;
+    } catch (error) {
+      await this.triggerHook(HookEvents.StreamError, {
+        context,
+        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)}`
+      );
+    }
+  }
   /**
    * Build static instructions for the think step
    */
@@ -1775,12 +2420,22 @@ YOUR TASK:
 1. Analyze the current situation
 2. Decide if the goal is complete or more actions are needed
 3. If more actions needed: specify tools to call
-4. If goal complete: return empty tool_calls list
+4. If goal complete:
+   - Set isComplete=true
+   - Provide the complete answer/output in finalResult
+   - Leave toolCalls empty
 
 IMPORTANT:
-- Return empty toolCalls array when task is COMPLETE
+- When task is COMPLETE, you MUST set isComplete=true AND provide finalResult
+- The finalResult should be a complete, well-structured answer based on all work done
 - Only use available tools
-- Provide clear reasoning for each decision`;
+- Provide clear reasoning for each decision
+- If an outputSchema was specified, ensure finalResult matches that schema
+
+USER MESSAGE:
+- Always provide a brief, user-friendly status in userMessage
+- This message is shown to users to indicate progress (e.g., "Searching for weather data...", "Calculating results...", "Done!")
+- Keep it concise and informative`;
     if (this.enableMemory) {
       instructions += `
 
@@ -1864,9 +2519,14 @@ The memory you write persists across all process() calls on this agent.`;
       this.log(`Action: ${toolCall.toolName}`, {
         parameters: toolCall.arguments
       });
+      const startTime = /* @__PURE__ */ new Date();
+      const tool2 = this.tools.get(toolCall.toolName);
+      const isAgentTool = tool2?.metadata?.["isAgent"] === true;
+      const spanType = isAgentTool ? "\u{1F916} agent" : "\u{1F527} tool";
       const toolSpan = await this.opperClient.createSpan({
         name: `tool_${toolCall.toolName}`,
         input: toolCall.arguments,
+        type: spanType,
         ...parentSpanId ? { parentSpanId } : context.parentSpanId ? { parentSpanId: context.parentSpanId } : {}
       });
       try {
@@ -1876,11 +2536,20 @@ The memory you write persists across all process() calls on this agent.`;
           context,
           { spanId: toolSpan.id }
         );
+        const endTime = /* @__PURE__ */ new Date();
+        const durationMs = endTime.getTime() - startTime.getTime();
         if (result.success) {
-          await this.opperClient.updateSpan(toolSpan.id, result.output);
+          await this.opperClient.updateSpan(toolSpan.id, result.output, {
+            startTime,
+            endTime,
+            meta: { durationMs }
+          });
         } else {
           await this.opperClient.updateSpan(toolSpan.id, void 0, {
-            error: result.error instanceof Error ? result.error.message : String(result.error)
+            error: result.error instanceof Error ? result.error.message : String(result.error),
+            startTime,
+            endTime,
+            meta: { durationMs }
           });
         }
         const summary = {
@@ -1895,12 +2564,18 @@ The memory you write persists across all process() calls on this agent.`;
         this.log(
           `Tool ${toolCall.toolName} ${result.success ? "succeeded" : "failed"}`,
           {
-            success: result.success
+            success: result.success,
+            durationMs
           }
         );
       } catch (error) {
+        const endTime = /* @__PURE__ */ new Date();
+        const durationMs = endTime.getTime() - startTime.getTime();
         await this.opperClient.updateSpan(toolSpan.id, void 0, {
-          error: error instanceof Error ? error.message : String(error)
+          error: error instanceof Error ? error.message : String(error),
+          startTime,
+          endTime,
+          meta: { durationMs }
         });
         const summary = {
           toolName: toolCall.toolName,
@@ -1909,7 +2584,8 @@ The memory you write persists across all process() calls on this agent.`;
         };
         results.push(ToolExecutionSummarySchema.parse(summary));
         this.logger.warn(`Tool ${toolCall.toolName} threw error`, {
-          error: error instanceof Error ? error.message : String(error)
+          error: error instanceof Error ? error.message : String(error),
+          durationMs
         });
       }
     }
@@ -1938,6 +2614,7 @@ The memory you write persists across all process() calls on this agent.`;
     const spanParentId = parentSpanId ?? context.parentSpanId ?? void 0;
     const summaries = [];
     if (hasReads) {
+      const startTime = /* @__PURE__ */ new Date();
       try {
         const keySet = new Set(
           decision.memoryReads.filter(
@@ -1949,10 +2626,17 @@ The memory you write persists across all process() calls on this agent.`;
           const memoryReadSpan = await this.opperClient.createSpan({
             name: "memory_read",
             input: keys,
+            type: "\u{1F9E0} memory",
             ...spanParentId && { parentSpanId: spanParentId }
           });
           const memoryData = await this.memory.read(keys);
-          await this.opperClient.updateSpan(memoryReadSpan.id, memoryData);
+          const endTime = /* @__PURE__ */ new Date();
+          const durationMs = endTime.getTime() - startTime.getTime();
+          await this.opperClient.updateSpan(memoryReadSpan.id, memoryData, {
+            startTime,
+            endTime,
+            meta: { durationMs }
+          });
           context.setMetadata("current_memory", memoryData);
           this.log(`Loaded ${Object.keys(memoryData).length} memory entries`, {
             keys
@@ -1991,10 +2675,12 @@ The memory you write persists across all process() calls on this agent.`;
       }
     }
     if (hasWrites) {
+      const startTime = /* @__PURE__ */ new Date();
       try {
         const memoryWriteSpan = await this.opperClient.createSpan({
           name: "memory_write",
           input: updateEntries.map(([key]) => key),
+          type: "\u{1F9E0} memory",
           ...spanParentId && { parentSpanId: spanParentId }
         });
         for (const [key, update] of updateEntries) {
@@ -2011,9 +2697,16 @@ The memory you write persists across all process() calls on this agent.`;
             value: castUpdate.value
           });
         }
+        const endTime = /* @__PURE__ */ new Date();
+        const durationMs = endTime.getTime() - startTime.getTime();
         await this.opperClient.updateSpan(
           memoryWriteSpan.id,
-          `Successfully wrote ${updateEntries.length} keys`
+          `Successfully wrote ${updateEntries.length} keys`,
+          {
+            startTime,
+            endTime,
+            meta: { durationMs }
+          }
         );
         this.log(`Wrote ${updateEntries.length} memory entries`);
         summaries.push(
@@ -2078,9 +2771,18 @@ The memory you write persists across all process() calls on this agent.`;
     };
     const instructions = `Generate the final result based on the execution history.
 Follow any instructions provided for formatting and style.`;
+    if (this.enableStreaming) {
+      return this.generateFinalResultStreaming(
+        context,
+        finalContext,
+        instructions
+      );
+    }
     try {
+      const sanitizedName = this.name.toLowerCase().replace(/[\s-]/g, "_");
+      const functionName = `generate_final_result_${sanitizedName}`;
       const callOptions = {
-        name: "generate_final_result",
+        name: functionName,
         instructions,
         input: finalContext,
         model: this.model
@@ -2113,6 +2815,172 @@ Follow any instructions provided for formatting and style.`;
       );
     }
   }
+  async generateFinalResultStreaming(context, finalContext, instructions) {
+    const assembler = createStreamAssembler(
+      this.outputSchema ? { schema: this.outputSchema } : void 0
+    );
+    let streamSpanId;
+    await this.triggerHook(HookEvents.StreamStart, {
+      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}`;
+      const streamResponse = await this.opperClient.stream({
+        name: functionName,
+        instructions,
+        input: finalContext,
+        model: this.model,
+        ...context.parentSpanId && { parentSpanId: context.parentSpanId },
+        ...this.outputSchema && { outputSchema: this.outputSchema }
+      });
+      for await (const event of streamResponse.result) {
+        const data = event?.data;
+        if (!data) {
+          continue;
+        }
+        if (!streamSpanId && typeof data.spanId === "string" && data.spanId) {
+          streamSpanId = data.spanId;
+        }
+        const feedResult = assembler.feed({
+          delta: data.delta,
+          jsonPath: data.jsonPath
+        });
+        if (!feedResult) {
+          continue;
+        }
+        const chunkPayload = {
+          context,
+          callType: "final_result",
+          chunkData: {
+            delta: data.delta,
+            jsonPath: data.jsonPath ?? null,
+            chunkType: data.chunkType ?? null
+          },
+          accumulated: feedResult.accumulated,
+          fieldBuffers: feedResult.snapshot
+        };
+        await this.triggerHook(HookEvents.StreamChunk, chunkPayload);
+        this.emitAgentEvent(HookEvents.StreamChunk, chunkPayload);
+      }
+      const fieldBuffers = assembler.snapshot();
+      const endPayload = {
+        context,
+        callType: "final_result",
+        fieldBuffers
+      };
+      await this.triggerHook(HookEvents.StreamEnd, endPayload);
+      this.emitAgentEvent(HookEvents.StreamEnd, endPayload);
+      const finalize = assembler.finalize();
+      let result;
+      if (this.outputSchema) {
+        if (finalize.type !== "structured" || finalize.structured === void 0) {
+          throw new Error(
+            "Streaming response did not provide structured data for the configured output schema."
+          );
+        }
+        result = this.outputSchema.parse(
+          finalize.structured
+        );
+      } else if (finalize.type === "root") {
+        result = finalize.rootText ?? "";
+      } else if (finalize.type === "structured" && finalize.structured) {
+        result = JSON.stringify(finalize.structured);
+      } else {
+        result = "";
+      }
+      const usageTracked = await this.trackStreamingUsageBySpan(
+        context,
+        streamSpanId
+      );
+      if (!usageTracked) {
+        context.updateUsage({
+          requests: 1,
+          inputTokens: 0,
+          outputTokens: 0,
+          totalTokens: 0,
+          cost: { generation: 0, platform: 0, total: 0 }
+        });
+      }
+      await this.triggerHook(HookEvents.LlmResponse, {
+        context,
+        callType: "final_result",
+        response: streamResponse,
+        parsed: result
+      });
+      this.log(
+        this.outputSchema ? "Final result generated (streaming, schema-validated)" : "Final result generated (streaming)"
+      );
+      return result;
+    } catch (error) {
+      await this.triggerHook(HookEvents.StreamError, {
+        context,
+        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)}`
+      );
+    }
+  }
+  async trackStreamingUsageBySpan(context, spanId) {
+    if (!spanId) {
+      return false;
+    }
+    try {
+      const span = await this.opperClient.getClient().spans.get(spanId);
+      const traceId = span?.traceId ?? span?.trace_id;
+      if (!traceId) {
+        return false;
+      }
+      const trace = await this.opperClient.getClient().traces.get(traceId);
+      const spans = trace?.spans;
+      if (!Array.isArray(spans)) {
+        return false;
+      }
+      for (const entry of spans) {
+        const entryId = entry?.id ?? entry["id"];
+        if (entryId !== spanId) {
+          continue;
+        }
+        const data = entry?.data;
+        if (!data) {
+          continue;
+        }
+        const record = data;
+        const primaryTotal = record["totalTokens"];
+        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({
+            requests: 1,
+            inputTokens: 0,
+            outputTokens: 0,
+            totalTokens: totalTokensRaw,
+            cost: { generation: 0, platform: 0, total: 0 }
+          });
+          return true;
+        }
+      }
+    } catch (error) {
+      this.logger.warn("Could not fetch streaming usage", {
+        spanId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+    return false;
+  }
   /**
    * Log helper
    */
@@ -2329,7 +3197,7 @@ var createMCPServerConfig = MCPconfig;
 
 // src/mcp/provider.ts
 init_tool();
-var isRecord = (value) => typeof value === "object" && value !== null;
+var isRecord2 = (value) => typeof value === "object" && value !== null;
 var MCPToolProvider = class {
   configs;
   namePrefix;
@@ -2420,7 +3288,7 @@ var MCPToolProvider = class {
       },
       execute: async (input, context) => {
         const startedAt = Date.now();
-        const args = isRecord(input) ? input : input === void 0 ? {} : { value: input };
+        const args = isRecord2(input) ? input : input === void 0 ? {} : { value: input };
         try {
           const result = await client.callTool(mcpTool.name, args);
           return exports.ToolResultFactory.success(toolName, result, {
@@ -2880,6 +3748,8 @@ var ToolRunner = class {
 
 exports.Agent = Agent;
 exports.AgentDecisionSchema = AgentDecisionSchema;
+exports.AgentEventEmitter = AgentEventEmitter;
+exports.AgentEvents = AgentEvents;
 exports.BaseAgent = BaseAgent;
 exports.ConsoleLogger = ConsoleLogger;
 exports.DEFAULT_MODEL = DEFAULT_MODEL;
@@ -2896,17 +3766,21 @@ exports.MemoryEntryMetadataSchema = MemoryEntryMetadataSchema;
 exports.MemoryEntrySchema = MemoryEntrySchema;
 exports.MemoryUpdateSchema = MemoryUpdateSchema;
 exports.OpperClient = OpperClient;
+exports.STREAM_ROOT_PATH = STREAM_ROOT_PATH;
 exports.SchemaValidationError = SchemaValidationError;
 exports.SilentLogger = SilentLogger;
+exports.StreamAssembler = StreamAssembler;
 exports.ThoughtSchema = ThoughtSchema;
 exports.ToolCallSchema = ToolCallSchema;
 exports.ToolExecutionSummarySchema = ToolExecutionSummarySchema;
 exports.ToolRunner = ToolRunner;
+exports.createAgentDecisionWithOutputSchema = createAgentDecisionWithOutputSchema;
 exports.createFunctionTool = createFunctionTool;
 exports.createHookManager = createHookManager;
 exports.createInMemoryStore = createInMemoryStore;
 exports.createMCPServerConfig = createMCPServerConfig;
 exports.createOpperClient = createOpperClient;
+exports.createStreamAssembler = createStreamAssembler;
 exports.extractTools = extractTools;
 exports.generateAgentFlowDiagram = generateAgentFlowDiagram;
 exports.getDefaultLogger = getDefaultLogger;