@opperai/agents 0.1.1 → 0.2.0

package/dist/index.cjs

@@ -2,6 +2,7 @@
 
 var crypto = require('crypto');
 var zod = require('zod');
+var fs = require('fs');
 var opperai = require('opperai');
 var zodToJsonSchema = require('zod-to-json-schema');
 var index_js = require('@modelcontextprotocol/sdk/client/index.js');
@@ -393,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();
@@ -465,8 +470,307 @@ 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) {
+  return name.replace(/\s/g, "_").replace(/-/g, "_").replace(/\./g, "_").replace(/[()]/g, "");
+}
+function sanitizeLabel(text) {
+  let cleaned = text.replace(/"/g, "'").replace(/\n/g, " ").replace(/`/g, "");
+  cleaned = cleaned.split(".")[0]?.trim() || cleaned.trim();
+  if (cleaned.length > 45) {
+    cleaned = cleaned.substring(0, 42) + "...";
+  }
+  return cleaned;
+}
+function getSchemaName(schema) {
+  if (!schema) {
+    return "N/A";
+  }
+  try {
+    const schemaAny = schema;
+    if (schemaAny.description) {
+      return schemaAny.description;
+    }
+    if (schemaAny._def?.description) {
+      return schemaAny._def.description;
+    }
+    const typeName = schemaAny._def?.typeName;
+    if (typeName === "ZodObject" && schemaAny._def) {
+      const shape = schemaAny._def.shape?.();
+      if (shape && typeof shape === "object") {
+        const keys = Object.keys(shape);
+        if (keys.length > 0) {
+          const keyStr = keys.length > 3 ? `{${keys.slice(0, 3).join(", ")}...}` : `{${keys.join(", ")}}`;
+          return keyStr;
+        }
+      }
+      return "Object";
+    }
+    if (typeName) {
+      return typeName.replace("Zod", "").replace("Type", "");
+    }
+    return "Any";
+  } catch {
+    return "Any";
+  }
+}
+function extractParameters(schema) {
+  if (!schema) {
+    return null;
+  }
+  try {
+    const schemaAny = schema;
+    if (schemaAny._def?.typeName === "ZodObject") {
+      const shape = schemaAny._def.shape?.();
+      if (shape && typeof shape === "object") {
+        const params = [];
+        for (const [key, value] of Object.entries(shape)) {
+          const fieldType = value?._def?.typeName;
+          if (fieldType) {
+            const cleanType = fieldType.replace("Zod", "").toLowerCase();
+            params.push(`${key}: ${cleanType}`);
+          } else {
+            params.push(key);
+          }
+        }
+        return params.length > 0 ? params : null;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function getRegisteredHooks(hooks) {
+  const events = [];
+  const allEvents = Object.values(HookEvents);
+  for (const event of allEvents) {
+    if (hooks.listenerCount(event) > 0) {
+      events.push(event);
+    }
+  }
+  return events;
+}
+function getWrappedAgent(tool2) {
+  const wrapped = tool2.metadata?.["wrappedAgent"];
+  if (wrapped && typeof wrapped === "object" && "name" in wrapped) {
+    return wrapped;
+  }
+  return null;
+}
+function isMcpTool(tool2) {
+  return tool2.metadata?.["provider"] === "mcp";
+}
+async function generateAgentFlowDiagram(agent, options = {}) {
+  const visited = options._visited ?? /* @__PURE__ */ new Set();
+  const isRoot = visited.size === 0;
+  const lines = [];
+  if (isRoot) {
+    lines.push("```mermaid");
+    lines.push("graph TB");
+  }
+  const agentId = sanitizeId(agent.name);
+  if (visited.has(agentId)) {
+    return "";
+  }
+  visited.add(agentId);
+  let agentLabel = `\u{1F916} ${agent.name}`;
+  if (agent.description && agent.description !== `Agent: ${agent.name}` && agent.description !== agent.name) {
+    const desc = sanitizeLabel(agent.description);
+    agentLabel += `<br/><i>${desc}</i>`;
+  }
+  const inputSchemaName = getSchemaName(agent.inputSchema);
+  const outputSchemaName = getSchemaName(agent.outputSchema);
+  agentLabel += `<br/>In: ${inputSchemaName} | Out: ${outputSchemaName}`;
+  lines.push(`    ${agentId}["${agentLabel}"]:::agent`);
+  const agentWithHooks = agent;
+  const registeredHooks = getRegisteredHooks(agentWithHooks.hooks);
+  if (registeredHooks.length > 0) {
+    const hookId = `${agentId}_hooks`;
+    const hookNames = registeredHooks.slice(0, 3).join(", ");
+    const hookLabel = registeredHooks.length > 3 ? `${hookNames} +${registeredHooks.length - 3}` : hookNames;
+    lines.push(`    ${hookId}["\u{1FA9D} ${hookLabel}"]:::hook`);
+    lines.push(`    ${agentId} -.-> ${hookId}`);
+  }
+  const tools = agent.getTools();
+  const regularTools = [];
+  const mcpToolsByServer = /* @__PURE__ */ new Map();
+  const agentTools = [];
+  for (const tool2 of tools) {
+    const wrappedAgent = getWrappedAgent(tool2);
+    if (wrappedAgent) {
+      agentTools.push(tool2);
+    } else if (isMcpTool(tool2)) {
+      const serverName = tool2.metadata?.["server"] ?? "unknown";
+      const serverTools = mcpToolsByServer.get(serverName) ?? [];
+      serverTools.push(tool2);
+      mcpToolsByServer.set(serverName, serverTools);
+    } else {
+      regularTools.push(tool2);
+    }
+  }
+  for (const tool2 of regularTools) {
+    const toolId = sanitizeId(`${agentId}_${tool2.name}`);
+    let toolLabel = `\u2699\uFE0F ${sanitizeLabel(tool2.name)}`;
+    if (tool2.description) {
+      const desc = sanitizeLabel(tool2.description);
+      toolLabel += `<br/><i>${desc}</i>`;
+    }
+    const params = extractParameters(tool2.schema);
+    if (params && params.length > 0) {
+      const paramsStr = params.length > 3 ? `${params.slice(0, 3).join(", ")}...` : params.join(", ");
+      toolLabel += `<br/>(${paramsStr})`;
+    }
+    lines.push(`    ${toolId}["${toolLabel}"]:::tool`);
+    lines.push(`    ${agentId} --> ${toolId}`);
+  }
+  if (mcpToolsByServer.size > 0) {
+    for (const [serverName, serverTools] of mcpToolsByServer.entries()) {
+      if (options.includeMcpTools) {
+        for (const tool2 of serverTools) {
+          const toolId = sanitizeId(`${agentId}_${tool2.name}`);
+          let toolLabel = `\u2699\uFE0F ${sanitizeLabel(tool2.name)}`;
+          if (tool2.description) {
+            const desc = sanitizeLabel(tool2.description);
+            toolLabel += `<br/><i>${desc}</i>`;
+          }
+          toolLabel += `<br/>(MCP: ${sanitizeLabel(serverName)})`;
+          lines.push(`    ${toolId}["${toolLabel}"]:::tool`);
+          lines.push(`    ${agentId} --> ${toolId}`);
+        }
+      } else {
+        const providerId = sanitizeId(`${agentId}_provider_${serverName}`);
+        lines.push(`    ${providerId}["\u{1F50C} ${serverName}"]:::provider`);
+        lines.push(`    ${agentId} --> ${providerId}`);
+      }
+    }
+  }
+  for (const tool2 of agentTools) {
+    const wrappedAgent = getWrappedAgent(tool2);
+    if (wrappedAgent) {
+      const subAgentId = sanitizeId(wrappedAgent.name);
+      lines.push(`    ${agentId} --> ${subAgentId}`);
+      const subDiagram = await generateAgentFlowDiagram(wrappedAgent, {
+        ...options,
+        _visited: visited
+      });
+      const subLines = subDiagram.split("\n").filter(
+        (line) => line && !line.includes("```mermaid") && !line.includes("```") && !line.includes("%% Styling") && !line.includes("classDef")
+      );
+      lines.push(...subLines);
+    }
+  }
+  if (isRoot) {
+    lines.push("");
+    lines.push("    %% Styling - Opper Brand Colors");
+    lines.push(
+      "    classDef agent fill:#8CF0DC,stroke:#1B2E40,stroke-width:3px,color:#1B2E40"
+    );
+    lines.push(
+      "    classDef tool fill:#FFD7D7,stroke:#3C3CAF,stroke-width:2px,color:#1B2E40"
+    );
+    lines.push(
+      "    classDef schema fill:#F8F8F8,stroke:#3C3CAF,stroke-width:2px,color:#1B2E40"
+    );
+    lines.push(
+      "    classDef hook fill:#FFB186,stroke:#3C3CAF,stroke-width:2px,color:#1B2E40"
+    );
+    lines.push(
+      "    classDef provider fill:#8CECF2,stroke:#1B2E40,stroke-width:2px,color:#1B2E40"
+    );
+    lines.push("```");
+  }
+  const diagram = lines.join("\n");
+  if (options.outputPath && isRoot) {
+    let filePath = options.outputPath;
+    if (!filePath.endsWith(".md")) {
+      filePath += ".md";
+    }
+    const fileContent = `# Agent Flow: ${agent.name}
+
+${diagram}`;
+    await fs.promises.writeFile(filePath, fileContent, "utf-8");
+    return filePath;
+  }
+  return diagram;
+}
 var MemoryEntryMetadataSchema = zod.z.object({
   createdAt: zod.z.number(),
   updatedAt: zod.z.number(),
@@ -601,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)
    */
@@ -613,6 +921,10 @@ var BaseAgent = class {
    * Hook manager for lifecycle events
    */
   hooks;
+  /**
+   * Event dispatcher for runtime events (notably streaming)
+   */
+  events;
   /**
    * Registry of available tools
    */
@@ -642,12 +954,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,
@@ -800,7 +1126,9 @@ var BaseAgent = class {
       ...this.inputSchema && { schema: this.inputSchema },
       metadata: {
         isAgent: true,
-        agentName: this.name
+        agentName: this.name,
+        wrappedAgent: this
+        // Store reference to this agent for visualization
       },
       execute: async (input, executionContext) => {
         try {
@@ -827,6 +1155,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.
@@ -841,6 +1198,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.
    *
@@ -998,6 +1364,30 @@ var BaseAgent = class {
     });
     await Promise.allSettled(teardownPromises);
   }
+  /**
+   * Generate a Mermaid flowchart diagram visualizing the agent's structure and flow.
+   * Shows tools, hooks, schemas, providers, and nested agents.
+   *
+   * @param options - Visualization options
+   * @returns Mermaid markdown string, or file path if outputPath was provided
+   *
+   * @example
+   * ```typescript
+   * // Generate diagram string
+   * const diagram = await agent.visualizeFlow();
+   * console.log(diagram);
+   *
+   * // Save to file
+   * const path = await agent.visualizeFlow({ outputPath: "agent_flow.md" });
+   * console.log(`Saved to ${path}`);
+   *
+   * // Include MCP tools details
+   * const diagram = await agent.visualizeFlow({ includeMcpTools: true });
+   * ```
+   */
+  async visualizeFlow(options) {
+    return generateAgentFlowDiagram(this, options);
+  }
 };
 
 // src/index.ts
@@ -1090,7 +1480,7 @@ var ToolExecutionSummarySchema = zod.z.object({
 
 // package.json
 var package_default = {
-  version: "0.1.1"};
+  version: "0.2.0"};
 
 // src/utils/version.ts
 var SDK_NAME = "@opperai/agents";
@@ -1153,7 +1543,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,
@@ -1161,7 +1551,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 = {
@@ -1179,6 +1570,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
    */
@@ -1347,6 +1768,189 @@ 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) {
@@ -1473,6 +2077,9 @@ var Agent = class extends BaseAgent {
     const spanName = "think";
     this.log("Think step", { iteration: context.iteration });
     await this.triggerHook(HookEvents.LlmCall, { context, callType: "think" });
+    if (this.enableStreaming) {
+      return this.thinkStreaming(input, context);
+    }
     try {
       const instructions = this.buildThinkInstructions();
       const thinkContext = await this.buildThinkContext(input, context);
@@ -1515,6 +2122,132 @@ var Agent = class extends BaseAgent {
       );
     }
   }
+  async thinkStreaming(input, context) {
+    const spanName = "think";
+    const instructions = this.buildThinkInstructions();
+    const thinkContext = await this.buildThinkContext(input, context);
+    const assembler = createStreamAssembler({
+      schema: AgentDecisionSchema
+    });
+    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: AgentDecisionSchema,
+        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 = AgentDecisionSchema.parse(
+          finalize.structured
+        );
+      } else {
+        decision = AgentDecisionSchema.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
+      });
+      await this.triggerHook(HookEvents.ThinkEnd, {
+        context,
+        thought: { reasoning: decision.reasoning }
+      });
+      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
    */
@@ -1828,6 +2561,13 @@ 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 callOptions = {
         name: "generate_final_result",
@@ -1863,6 +2603,170 @@ 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 streamResponse = await this.opperClient.stream({
+        name: "generate_final_result",
+        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
    */
@@ -2079,7 +2983,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;
@@ -2170,7 +3074,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, {
@@ -2630,6 +3534,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;
@@ -2646,8 +3552,10 @@ 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;
@@ -2657,7 +3565,9 @@ exports.createHookManager = createHookManager;
 exports.createInMemoryStore = createInMemoryStore;
 exports.createMCPServerConfig = createMCPServerConfig;
 exports.createOpperClient = createOpperClient;
+exports.createStreamAssembler = createStreamAssembler;
 exports.extractTools = extractTools;
+exports.generateAgentFlowDiagram = generateAgentFlowDiagram;
 exports.getDefaultLogger = getDefaultLogger;
 exports.getSchemaDefault = getSchemaDefault;
 exports.isSchemaValid = isSchemaValid;