@opperai/agents 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -508,6 +508,10 @@ declare const HookEvents: {
     readonly MemoryRead: "memory:read";
     readonly MemoryWrite: "memory:write";
     readonly MemoryError: "memory:error";
+    readonly StreamStart: "stream:start";
+    readonly StreamChunk: "stream:chunk";
+    readonly StreamEnd: "stream:end";
+    readonly StreamError: "stream:error";
 };
 type HookEventName = (typeof HookEvents)[keyof typeof HookEvents];
 interface HookPayloadMap {
@@ -533,6 +537,7 @@ interface HookPayloadMap {
         context: AgentContext;
         callType: string;
         response: unknown;
+        parsed?: unknown;
     };
     [HookEvents.ThinkEnd]: {
         context: AgentContext;
@@ -570,6 +575,31 @@ interface HookPayloadMap {
         operation: "read" | "write" | "delete" | "clear";
         error: unknown;
     };
+    [HookEvents.StreamStart]: {
+        context: AgentContext;
+        callType: string;
+    };
+    [HookEvents.StreamChunk]: {
+        context: AgentContext;
+        callType: string;
+        chunkData: {
+            delta: unknown;
+            jsonPath?: string | null;
+            chunkType?: string | null;
+        };
+        accumulated: string;
+        fieldBuffers: Record<string, string>;
+    };
+    [HookEvents.StreamEnd]: {
+        context: AgentContext;
+        callType: string;
+        fieldBuffers: Record<string, string>;
+    };
+    [HookEvents.StreamError]: {
+        context: AgentContext;
+        callType: string;
+        error: unknown;
+    };
 }
 type HookPayload<E extends HookEventName> = HookPayloadMap[E];
 type HookHandler<E extends HookEventName> = (payload: HookPayload<E>) => void | Promise<void>;
@@ -592,6 +622,60 @@ declare class HookManager {
 }
 declare const createHookManager: (logger?: AgentLogger) => HookManager;
 
+declare const AgentEvents: {
+    readonly StreamStart: "stream:start";
+    readonly StreamChunk: "stream:chunk";
+    readonly StreamEnd: "stream:end";
+    readonly StreamError: "stream:error";
+};
+type AgentEventName = (typeof AgentEvents)[keyof typeof AgentEvents];
+type AgentEventPayloadMap = Pick<HookPayloadMap, AgentEventName>;
+type AgentEventPayload<E extends AgentEventName> = AgentEventPayloadMap[E];
+type AgentEventListener<E extends AgentEventName> = (payload: AgentEventPayload<E>) => void;
+declare class AgentEventEmitter {
+    private readonly registry;
+    private readonly logger;
+    constructor(logger?: AgentLogger);
+    on<E extends AgentEventName>(event: E, listener: AgentEventListener<E>): () => void;
+    once<E extends AgentEventName>(event: E, listener: AgentEventListener<E>): () => void;
+    off<E extends AgentEventName>(event: E, listener: AgentEventListener<E>): void;
+    emit<E extends AgentEventName>(event: E, payload: AgentEventPayload<E>): void;
+    removeAllListeners(event?: AgentEventName): void;
+    listenerCount(event?: AgentEventName): number;
+}
+
+/**
+ * Options for generating agent flow visualization
+ */
+interface VisualizationOptions {
+    /**
+     * Optional file path to save the Mermaid diagram
+     * If provided, the diagram will be saved to this path
+     * .md extension will be added automatically if not present
+     */
+    outputPath?: string;
+    /**
+     * Whether to include MCP tool providers in the visualization
+     * When true, will show expanded tools from providers
+     * When false, will show providers as single nodes
+     * @default false
+     */
+    includeMcpTools?: boolean;
+    /**
+     * Internal parameter to track visited agents (prevents cycles)
+     * @internal
+     */
+    _visited?: Set<string>;
+}
+/**
+ * Generate Mermaid graph diagram for an agent's structure and flow
+ *
+ * @param agent - The agent to visualize
+ * @param options - Visualization options
+ * @returns Mermaid markdown string, or file path if outputPath was provided
+ */
+declare function generateAgentFlowDiagram<I, O>(agent: BaseAgent<I, O>, options?: VisualizationOptions): Promise<string>;
+
 /**
  * Schema for memory entry metadata
  */
@@ -635,8 +719,8 @@ declare const MemoryEntrySchema: z.ZodObject<{
         updatedAt: number;
         accessCount: number;
     };
-    key: string;
     description: string;
+    key: string;
     value?: unknown;
 }, {
     metadata: {
@@ -644,8 +728,8 @@ declare const MemoryEntrySchema: z.ZodObject<{
         updatedAt: number;
         accessCount?: number | undefined;
     };
-    key: string;
     description: string;
+    key: string;
     value?: unknown;
 }>;
 type MemoryEntry = z.infer<typeof MemoryEntrySchema>;
@@ -793,6 +877,27 @@ interface BaseAgentConfig<TInput, TOutput> {
      * Output schema for validation (Zod schema)
      */
     outputSchema?: ZodType<TOutput>;
+    /**
+     * Enable Opper streaming APIs for LLM calls
+     * @default false
+     */
+    enableStreaming?: boolean;
+    /**
+     * Register a handler invoked when a streaming call starts.
+     */
+    onStreamStart?: AgentEventListener<typeof HookEvents.StreamStart>;
+    /**
+     * Register a handler invoked for each streaming chunk.
+     */
+    onStreamChunk?: AgentEventListener<typeof HookEvents.StreamChunk>;
+    /**
+     * Register a handler invoked when a streaming call ends.
+     */
+    onStreamEnd?: AgentEventListener<typeof HookEvents.StreamEnd>;
+    /**
+     * Register a handler invoked when streaming encounters an error.
+     */
+    onStreamError?: AgentEventListener<typeof HookEvents.StreamError>;
     /**
      * Enable memory subsystem
      * @default false
@@ -868,6 +973,10 @@ declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> {
      * Whether memory is enabled
      */
     readonly enableMemory: boolean;
+    /**
+     * Whether streaming is enabled
+     */
+    readonly enableStreaming: boolean;
     /**
      * Memory instance for persistent storage (null if disabled or initialization failed)
      */
@@ -880,6 +989,10 @@ declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> {
      * Hook manager for lifecycle events
      */
     protected readonly hooks: HookManager;
+    /**
+     * Event dispatcher for runtime events (notably streaming)
+     */
+    protected readonly events: AgentEventEmitter;
     /**
      * Registry of available tools
      */
@@ -990,6 +1103,29 @@ declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> {
      * @returns Cleanup function to unregister the hook
      */
     registerHook<E extends HookEventName>(event: E, handler: HookHandler<E>): () => void;
+    /**
+     * Register an event listener.
+     *
+     * @param event - Event name
+     * @param listener - Listener callback
+     * @returns Cleanup function to unregister the listener
+     */
+    on<E extends AgentEventName>(event: E, listener: AgentEventListener<E>): () => void;
+    /**
+     * 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<E extends AgentEventName>(event: E, listener: AgentEventListener<E>): () => void;
+    /**
+     * Remove a previously registered event listener.
+     *
+     * @param event - Event name
+     * @param listener - Listener callback to remove
+     */
+    off<E extends AgentEventName>(event: E, listener: AgentEventListener<E>): void;
     /**
      * Trigger a hook event with a payload.
      * Swallows errors to prevent hook failures from breaking agent execution.
@@ -998,6 +1134,13 @@ declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> {
      * @param payload - Event payload
      */
     protected triggerHook<E extends HookEventName>(event: E, payload: Parameters<HookHandler<E>>[0]): Promise<void>;
+    /**
+     * Emit a runtime event to listeners.
+     *
+     * @param event - Event name
+     * @param payload - Event payload
+     */
+    protected emitAgentEvent<E extends AgentEventName>(event: E, payload: AgentEventPayload<E>): void;
     /**
      * Execute a tool with proper context, hooks, and error handling.
      *
@@ -1014,8 +1157,55 @@ declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> {
     private registerTools;
     private activateToolProviders;
     private deactivateToolProviders;
+    /**
+     * 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 });
+     * ```
+     */
+    visualizeFlow(options?: VisualizationOptions): Promise<string>;
 }
 
+/**
+ * Streaming chunk payload from Opper SSE responses.
+ */
+interface OpperStreamChunk {
+    delta?: string | number | boolean | null | undefined;
+    jsonPath?: string | null | undefined;
+    spanId?: string | null | undefined;
+    chunkType?: string | null | undefined;
+}
+/**
+ * Server-sent event emitted during streaming calls.
+ */
+interface OpperStreamEvent {
+    id?: string;
+    event?: string;
+    retry?: number;
+    data?: OpperStreamChunk;
+}
+/**
+ * Structured response returned by Opper stream endpoints.
+ */
+interface OpperStreamResponse {
+    headers: Record<string, string[]>;
+    result: AsyncIterable<OpperStreamEvent>;
+}
 /**
  * Opper call response
  */
@@ -1079,6 +1269,10 @@ interface OpperCallOptions<TInput = unknown, TOutput = unknown> {
      * Parent span ID for tracing
      */
     parentSpanId?: string;
+    /**
+     * Abort signal used to cancel the underlying HTTP request.
+     */
+    signal?: AbortSignal;
 }
 /**
  * Span information
@@ -1137,6 +1331,10 @@ declare class OpperClient {
      * Make a call to Opper with retry logic
      */
     call<TInput = unknown, TOutput = unknown>(options: OpperCallOptions<TInput, TOutput>): Promise<OpperCallResponse<TOutput>>;
+    /**
+     * Stream a call to Opper with retry logic
+     */
+    stream<TInput = unknown, TOutput = unknown>(options: OpperCallOptions<TInput, TOutput>): Promise<OpperStreamResponse>;
     /**
      * Create a span for tracing
      */
@@ -1214,6 +1412,7 @@ declare class Agent<TInput = unknown, TOutput = unknown> extends BaseAgent<TInpu
      * Think step: Call LLM to decide next action
      */
     private think;
+    private thinkStreaming;
     /**
      * Build static instructions for the think step
      */
@@ -1235,6 +1434,8 @@ declare class Agent<TInput = unknown, TOutput = unknown> extends BaseAgent<TInpu
      * Generate final result based on execution history
      */
     private generateFinalResult;
+    private generateFinalResultStreaming;
+    private trackStreamingUsageBySpan;
     /**
      * Log helper
      */
@@ -1491,9 +1692,9 @@ declare const MCPConfigVariants: z.ZodDiscriminatedUnion<"transport", [z.ZodObje
     method: z.ZodDefault<z.ZodEnum<["GET", "POST"]>>;
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
+    name: string;
     method: "GET" | "POST";
     headers: Record<string, string>;
-    name: string;
     timeout: number;
     transport: "http-sse";
     url: string;
@@ -1516,8 +1717,8 @@ declare const MCPConfigVariants: z.ZodDiscriminatedUnion<"transport", [z.ZodObje
     sessionId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
-    headers: Record<string, string>;
     name: string;
+    headers: Record<string, string>;
     timeout: number;
     transport: "streamable-http";
     url: string;
@@ -1575,9 +1776,9 @@ declare const MCPServerConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"trans
     method: z.ZodDefault<z.ZodEnum<["GET", "POST"]>>;
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
+    name: string;
     method: "GET" | "POST";
     headers: Record<string, string>;
-    name: string;
     timeout: number;
     transport: "http-sse";
     url: string;
@@ -1600,8 +1801,8 @@ declare const MCPServerConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"trans
     sessionId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
-    headers: Record<string, string>;
     name: string;
+    headers: Record<string, string>;
     timeout: number;
     transport: "streamable-http";
     url: string;
@@ -1626,16 +1827,16 @@ declare const MCPServerConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"trans
     stderr?: "inherit" | "pipe" | "ignore" | undefined;
 } | {
     metadata: Record<string, unknown>;
+    name: string;
     method: "GET" | "POST";
     headers: Record<string, string>;
-    name: string;
     timeout: number;
     transport: "http-sse";
     url: string;
 } | {
     metadata: Record<string, unknown>;
-    headers: Record<string, string>;
     name: string;
+    headers: Record<string, string>;
     timeout: number;
     transport: "streamable-http";
     url: string;
@@ -1739,6 +1940,37 @@ declare const schemaToJson: (schema: ZodTypeAny, options?: JsonSchemaOptions) =>
 declare const getSchemaDefault: <T>(schema: Schema<T>) => T | undefined;
 declare const mergeSchemaDefaults: <T extends Record<string, unknown>>(schema: Schema<T>, value: Partial<T>) => T;
 
+declare const STREAM_ROOT_PATH = "_root";
+interface StreamAssemblerOptions {
+    schema?: ZodTypeAny;
+}
+interface StreamFeedResult {
+    path: string;
+    accumulated: string;
+    snapshot: Record<string, string>;
+}
+interface StreamFinalizeResult {
+    type: "root" | "structured" | "empty";
+    rootText?: string;
+    structured?: unknown;
+}
+declare class StreamAssembler {
+    private readonly displayBuffers;
+    private readonly valueBuffers;
+    private readonly schema;
+    constructor(options?: StreamAssemblerOptions);
+    feed(chunk: {
+        delta?: unknown;
+        jsonPath?: string | null | undefined;
+    }): StreamFeedResult | null;
+    snapshot(): Record<string, string>;
+    hasStructuredFields(): boolean;
+    finalize(): StreamFinalizeResult;
+    getFieldBuffers(): Map<string, string>;
+    private reconstructStructured;
+}
+declare const createStreamAssembler: (options?: StreamAssemblerOptions) => StreamAssembler;
+
 /**
  * Options for creating a tool from a function
  */
@@ -1924,4 +2156,4 @@ declare class ToolRunner {
     };
 }
 
-export { Agent, type AgentConfig, AgentContext, type AgentContextOptions, type AgentContextSnapshot, type AgentDecision, AgentDecisionSchema, type AgentLogger, BaseAgent, type BaseAgentConfig, ConsoleLogger, type CreateSpanOptions, DEFAULT_MODEL, DEFAULT_RETRY_CONFIG, type ExecutionCycle, ExecutionCycleSchema, type Failure, type HookEventName, HookEvents, type HookHandler, HookManager, type HookPayload, type HookPayloadMap, type HookRegistration, InMemoryStore, type IterationSummary, type JsonSchemaOptions, LogLevel, MCPClient, type MCPClientOptions, type MCPServerConfig, type MCPServerConfigInput, MCPServerConfigSchema, type MCPTool, MCPToolProvider, type MCPToolProviderOptions, MCPconfig, type MaybePromise, type Memory, type MemoryCatalogEntry, type MemoryEntry, type MemoryEntryMetadata, MemoryEntryMetadataSchema, MemoryEntrySchema, type MemoryUpdate, MemoryUpdateSchema, type OpperCallOptions, type OpperCallResponse, OpperClient, type OpperClientConfig, type OpperSpan, Result, type RetryConfig, type Schema, SchemaValidationError, type SchemaValidationOptions, SilentLogger, type Success, type Thought, ThoughtSchema, type Tool, type ToolCall, type ToolCallRecord, ToolCallRecordSchema, ToolCallSchema, type ToolDefinition, type ToolExecutionContext, type ToolExecutionSummary, ToolExecutionSummarySchema, type ToolFailure, type ToolFunction, ToolMetadataSchema, type ToolOptions, type ToolProvider, type ToolResult, type ToolResultData, ToolResultFactory, ToolResultFailureSchema, type ToolResultInit, ToolResultSchema, ToolResultSuccessSchema, type ToolRunOptions, ToolRunner, type ToolSuccess, type UnregisterHook, type Usage, UsageSchema, coerceToolDefinition, createFunctionTool, createHookManager, createInMemoryStore, createMCPServerConfig, createOpperClient, createToolCallRecord, err, extractTools, getDefaultLogger, getSchemaDefault, isSchemaValid, isToolProvider, mcp, mergeSchemaDefaults, normalizeToolEntries, ok, schemaToJson, setDefaultLogger, tool, validateSchema, validateToolInput };
+export { Agent, type AgentConfig, AgentContext, type AgentContextOptions, type AgentContextSnapshot, type AgentDecision, AgentDecisionSchema, AgentEventEmitter, type AgentEventListener, type AgentEventName, type AgentEventPayload, type AgentEventPayloadMap, AgentEvents, type AgentLogger, BaseAgent, type BaseAgentConfig, ConsoleLogger, type CreateSpanOptions, DEFAULT_MODEL, DEFAULT_RETRY_CONFIG, type ExecutionCycle, ExecutionCycleSchema, type Failure, type HookEventName, HookEvents, type HookHandler, HookManager, type HookPayload, type HookPayloadMap, type HookRegistration, InMemoryStore, type IterationSummary, type JsonSchemaOptions, LogLevel, MCPClient, type MCPClientOptions, type MCPServerConfig, type MCPServerConfigInput, MCPServerConfigSchema, type MCPTool, MCPToolProvider, type MCPToolProviderOptions, MCPconfig, type MaybePromise, type Memory, type MemoryCatalogEntry, type MemoryEntry, type MemoryEntryMetadata, MemoryEntryMetadataSchema, MemoryEntrySchema, type MemoryUpdate, MemoryUpdateSchema, type OpperCallOptions, type OpperCallResponse, OpperClient, type OpperClientConfig, type OpperSpan, type OpperStreamChunk, type OpperStreamEvent, type OpperStreamResponse, Result, type RetryConfig, STREAM_ROOT_PATH, type Schema, SchemaValidationError, type SchemaValidationOptions, SilentLogger, StreamAssembler, type StreamAssemblerOptions, type StreamFeedResult, type StreamFinalizeResult, type Success, type Thought, ThoughtSchema, type Tool, type ToolCall, type ToolCallRecord, ToolCallRecordSchema, ToolCallSchema, type ToolDefinition, type ToolExecutionContext, type ToolExecutionSummary, ToolExecutionSummarySchema, type ToolFailure, type ToolFunction, ToolMetadataSchema, type ToolOptions, type ToolProvider, type ToolResult, type ToolResultData, ToolResultFactory, ToolResultFailureSchema, type ToolResultInit, ToolResultSchema, ToolResultSuccessSchema, type ToolRunOptions, ToolRunner, type ToolSuccess, type UnregisterHook, type Usage, UsageSchema, type VisualizationOptions, coerceToolDefinition, createFunctionTool, createHookManager, createInMemoryStore, createMCPServerConfig, createOpperClient, createStreamAssembler, createToolCallRecord, err, extractTools, generateAgentFlowDiagram, getDefaultLogger, getSchemaDefault, isSchemaValid, isToolProvider, mcp, mergeSchemaDefaults, normalizeToolEntries, ok, schemaToJson, setDefaultLogger, tool, validateSchema, validateToolInput };