@providerprotocol/agents 0.0.1 → 0.0.3

package/dist/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/middleware/logging.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { Middleware, LoggingOptions, MiddlewareContext } from './types.ts';\nimport type { GenerateResult } from '../execution/types.ts';\n\nconst DEFAULT_LOGGING_OPTIONS: Required<LoggingOptions> = {\n  level: 'info',\n  logger: console.log,\n  includeMessages: false,\n  includeTiming: true,\n};\n\nconst LOG_LEVELS = {\n  debug: 0,\n  info: 1,\n  warn: 2,\n  error: 3,\n} as const;\n\n/**\n * Create a logging middleware.\n *\n * Logs agent execution with configurable detail level:\n * - Execution start/end\n * - Timing information (if enabled)\n * - Message content (if enabled)\n * - Errors\n *\n * @param options - Logging configuration options\n * @returns Middleware\n */\nexport function logging(options: LoggingOptions = {}): Middleware {\n  const opts = { ...DEFAULT_LOGGING_OPTIONS, ...options };\n  const currentLevel = LOG_LEVELS[opts.level];\n\n  function shouldLog(level: keyof typeof LOG_LEVELS): boolean {\n    return LOG_LEVELS[level] >= currentLevel;\n  }\n\n  function log(level: keyof typeof LOG_LEVELS, message: string): void {\n    if (shouldLog(level)) {\n      const prefix = `[UAP:${level.toUpperCase()}]`;\n      opts.logger(`${prefix} ${message}`);\n    }\n  }\n\n  function formatContext(context: MiddlewareContext): string {\n    const parts = [`agent=${context.agent.id}`];\n\n    if (opts.includeMessages) {\n      parts.push(`messages=${context.state.messages.length}`);\n    }\n\n    return parts.join(' ');\n  }\n\n  return {\n    name: 'logging',\n\n    async before(context: MiddlewareContext): Promise<MiddlewareContext | void> {\n      log('info', `Execution started: ${formatContext(context)}`);\n\n      if (opts.includeTiming) {\n        context.metadata.set('_logging_startTime', Date.now());\n      }\n\n      if (opts.includeMessages && shouldLog('debug')) {\n        log('debug', `Input: ${JSON.stringify(context.input)}`);\n      }\n\n      return context;\n    },\n\n    async after(\n      context: MiddlewareContext,\n      result: GenerateResult,\n    ): Promise<GenerateResult> {\n      let message = 'Execution completed';\n\n      if (opts.includeTiming) {\n        const startTime = context.metadata.get('_logging_startTime') as number | undefined;\n        if (startTime) {\n          const duration = Date.now() - startTime;\n          message += ` in ${duration}ms`;\n        }\n      }\n\n      message += `: ${formatContext(context)}`;\n\n      if (result.turn.usage) {\n        message += ` tokens=${result.turn.usage.totalTokens}`;\n      }\n\n      log('info', message);\n\n      if (opts.includeMessages && shouldLog('debug')) {\n        log('debug', `Response: ${result.turn.response.text.substring(0, 200)}...`);\n      }\n\n      return result;\n    },\n\n    async onError(\n      context: MiddlewareContext,\n      error: Error,\n    ): Promise<GenerateResult | void> {\n      let message = `Execution failed: ${error.message}`;\n\n      if (opts.includeTiming) {\n        const startTime = context.metadata.get('_logging_startTime') as number | undefined;\n        if (startTime) {\n          const duration = Date.now() - startTime;\n          message += ` after ${duration}ms`;\n        }\n      }\n\n      message += `: ${formatContext(context)}`;\n\n      log('error', message);\n\n      // Let the error propagate\n      return undefined;\n    },\n  };\n}\n"]}

package/dist/thread-tree/index.d.ts

@@ -0,0 +1,115 @@
+import { A as AgentState } from '../index-qsPwbY86.js';
+import { a as AgentStateJSON } from '../types-2Vsthzyu.js';
+import '@providerprotocol/ai';
+
+/**
+ * Serialized form of a ThreadNode.
+ */
+interface ThreadNodeJSON {
+    /** Node ID */
+    id: string;
+    /** Parent node ID (null for root) */
+    parentId: string | null;
+    /** State snapshot at this node */
+    state: AgentStateJSON;
+    /** Optional branch name */
+    name?: string;
+    /** Child node IDs */
+    children: string[];
+}
+/**
+ * Serialized form of a ThreadTree.
+ */
+interface ThreadTreeJSON {
+    /** Root node ID */
+    rootId: string;
+    /** Current (active) node ID */
+    currentId: string;
+    /** All nodes */
+    nodes: ThreadNodeJSON[];
+}
+
+/**
+ * A node in the thread tree representing a conversation state snapshot.
+ */
+declare class ThreadNode {
+    /** Node ID (UUIDv4) */
+    readonly id: string;
+    /** Parent node ID (null for root) */
+    readonly parentId: string | null;
+    /** State snapshot at this node */
+    state: AgentState;
+    /** Optional branch name */
+    name?: string;
+    /** Child node IDs */
+    readonly children: string[];
+    constructor(id: string, parentId: string | null, state: AgentState, name?: string, children?: string[]);
+    /**
+     * Serialize to JSON.
+     */
+    toJSON(): ThreadNodeJSON;
+    /**
+     * Deserialize from JSON.
+     */
+    static fromJSON(json: ThreadNodeJSON): ThreadNode;
+}
+/**
+ * A tree-structured collection of conversation threads with parent-child relationships.
+ * Enables branching conversations and easy switching between alternative paths.
+ */
+declare class ThreadTree {
+    /** Root node */
+    readonly root: ThreadNode;
+    /** Currently active node */
+    private currentNode;
+    /** All nodes by ID */
+    readonly nodes: Map<string, ThreadNode>;
+    constructor(root?: ThreadNode);
+    /**
+     * Get the currently active node.
+     */
+    get current(): ThreadNode;
+    /**
+     * Create a branch from a node.
+     *
+     * @param fromId - ID of the node to branch from
+     * @param name - Optional name for the branch
+     * @returns ID of the new node
+     */
+    branch(fromId: string, name?: string): string;
+    /**
+     * Switch to a different node.
+     *
+     * @param nodeId - ID of the node to switch to
+     */
+    checkout(nodeId: string): void;
+    /**
+     * Get the AgentState representing the full history from root to current node.
+     * Since nodes store full state snapshots, this returns the current node's state.
+     *
+     * @returns AgentState with combined history
+     */
+    history(): AgentState;
+    /**
+     * Get all leaf nodes (nodes with no children).
+     *
+     * @returns Array of leaf node IDs
+     */
+    getLeaves(): string[];
+    /**
+     * Get all branch names.
+     *
+     * @returns Map of node IDs to branch names
+     */
+    getBranches(): Map<string, string | undefined>;
+    /**
+     * Serialize to JSON.
+     */
+    toJSON(): ThreadTreeJSON;
+    /**
+     * Deserialize from JSON.
+     */
+    static fromJSON(json: ThreadTreeJSON): ThreadTree;
+}
+
+export { ThreadNode, type ThreadNodeJSON, ThreadTree, type ThreadTreeJSON };

package/dist/thread-tree/index.js

@@ -0,0 +1,4 @@
+export { ThreadNode, ThreadTree } from '../chunk-PHI5ULBV.js';
+import '../chunk-EKRXMSDX.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/thread-tree/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/types-2Vsthzyu.d.ts

@@ -0,0 +1,163 @@
+import { Message, TokenUsage, MessageMetadata } from '@providerprotocol/ai';
+
+/**
+ * Status of a plan step during execution.
+ */
+type PlanStepStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
+/**
+ * A single tool execution trace from a sub-agent.
+ * Per UAP spec Section 8.8.
+ */
+interface ToolExecutionTrace {
+    /** Name of the tool */
+    toolName: string;
+    /** Tool call ID */
+    toolCallId?: string;
+    /** Arguments passed to the tool */
+    arguments: Record<string, unknown>;
+    /** Tool result */
+    result: string;
+    /** Whether the tool errored */
+    isError?: boolean;
+    /** Execution time in milliseconds */
+    duration?: number;
+}
+/**
+ * Sub-agent execution trace for checkpoint persistence.
+ * Per UAP spec Section 8.8.
+ */
+interface SubagentExecutionTrace {
+    /** Unique ID of the sub-agent instance */
+    subagentId: string;
+    /** Type/name of the sub-agent */
+    subagentType: string;
+    /** Tool call ID that spawned this sub-agent */
+    parentToolCallId: string;
+    /** The task given to the sub-agent */
+    prompt: string;
+    /** Start timestamp (ms since epoch) */
+    startTime: number;
+    /** End timestamp (ms since epoch) */
+    endTime: number;
+    /** Whether execution succeeded */
+    success: boolean;
+    /** Sub-agent's response (if successful) */
+    result?: string;
+    /** Error message (if failed) */
+    error?: string;
+    /** Tools used by sub-agent */
+    toolExecutions?: ToolExecutionTrace[];
+    /** Token usage for sub-agent */
+    usage?: TokenUsage;
+}
+/**
+ * Serialized form of SubagentExecutionTrace.
+ */
+interface SubagentExecutionTraceJSON {
+    subagentId: string;
+    subagentType: string;
+    parentToolCallId: string;
+    prompt: string;
+    startTime: number;
+    endTime: number;
+    success: boolean;
+    result?: string;
+    error?: string;
+    toolExecutions?: ToolExecutionTrace[];
+    usage?: TokenUsage;
+}
+/**
+ * A single step in an execution plan.
+ */
+interface PlanStep {
+    /** Unique step identifier */
+    id: string;
+    /** Description of what this step does */
+    description: string;
+    /** Tool to use (if applicable) */
+    tool?: string;
+    /** IDs of steps this depends on */
+    dependsOn: string[];
+    /** Current status */
+    status: PlanStepStatus;
+}
+/**
+ * Serialized form of a PlanStep.
+ */
+interface PlanStepJSON {
+    id: string;
+    description: string;
+    tool?: string;
+    dependsOn: string[];
+    status: PlanStepStatus;
+}
+/**
+ * Serialized form of AgentState for persistence.
+ */
+interface AgentStateJSON {
+    /** UAP version */
+    version: string;
+    /** State snapshot ID */
+    id: string;
+    /** Serialized messages */
+    messages: MessageJSON[];
+    /** Current step number */
+    step: number;
+    /** User-defined metadata */
+    metadata: Record<string, unknown>;
+    /** Reasoning traces (for ReAct) */
+    reasoning: string[];
+    /** Execution plan (for Plan strategy) */
+    plan?: PlanStepJSON[];
+    /** Sub-agent execution traces (per UAP spec Section 8.8) */
+    subagentTraces?: SubagentExecutionTraceJSON[];
+}
+/**
+ * Serialized form of a Message.
+ * This preserves the UPP Message structure for serialization.
+ */
+interface MessageJSON {
+    role: 'user' | 'assistant' | 'tool_result';
+    content: unknown;
+    metadata?: MessageMetadata;
+}
+/**
+ * Interface for AgentState operations.
+ * All operations return new instances (immutable).
+ */
+interface AgentStateInterface {
+    /** State snapshot ID (UUIDv4) */
+    readonly id: string;
+    /** Conversation history (UPP Messages) */
+    readonly messages: readonly Message[];
+    /** Current step number */
+    readonly step: number;
+    /** User-defined metadata */
+    readonly metadata: Readonly<Record<string, unknown>>;
+    /** Reasoning traces (for ReAct) */
+    readonly reasoning: readonly string[];
+    /** Execution plan (for Plan strategy) */
+    readonly plan: readonly PlanStep[] | undefined;
+    /** Sub-agent execution traces (per UAP spec Section 8.8) */
+    readonly subagentTraces: readonly SubagentExecutionTrace[];
+    /** Return new state with message added */
+    withMessage(message: Message): AgentStateInterface;
+    /** Return new state with messages added */
+    withMessages(messages: Message[]): AgentStateInterface;
+    /** Return new state with context replaced (all messages) */
+    withContext(messages: Message[]): AgentStateInterface;
+    /** Return new state with updated step */
+    withStep(step: number): AgentStateInterface;
+    /** Return new state with metadata entry */
+    withMetadata(key: string, value: unknown): AgentStateInterface;
+    /** Return new state with reasoning added */
+    withReasoning(reasoning: string): AgentStateInterface;
+    /** Return new state with plan set */
+    withPlan(plan: PlanStep[]): AgentStateInterface;
+    /** Return new state with sub-agent trace added */
+    withSubagentTrace(trace: SubagentExecutionTrace): AgentStateInterface;
+    /** Serialize to JSON */
+    toJSON(): AgentStateJSON;
+}
+
+export type { AgentStateInterface as A, PlanStep as P, SubagentExecutionTrace as S, ToolExecutionTrace as T, AgentStateJSON as a, PlanStepStatus as b, SubagentExecutionTraceJSON as c };

package/dist/types-BhX9uD_d.d.ts

@@ -0,0 +1,91 @@
+import { a as AgentStateJSON } from './types-2Vsthzyu.js';
+
+/**
+ * Checkpoint Types
+ *
+ * Type definitions for step-level persistence and session resume.
+ *
+ * @see UAP-1.0 Spec Section 12.4
+ */
+
+/**
+ * Checkpoint store interface.
+ *
+ * Implementations handle persistence of agent state at step boundaries
+ * for crash recovery and session resume.
+ *
+ * @example
+ * ```typescript
+ * const store = fileCheckpoints({ dir: './checkpoints' });
+ *
+ * // Save checkpoint
+ * await store.save('session-123', state.toJSON());
+ *
+ * // Load checkpoint
+ * const saved = await store.load('session-123');
+ * if (saved) {
+ *   const restored = AgentState.fromJSON(saved);
+ * }
+ * ```
+ */
+interface CheckpointStore {
+    /**
+     * Save a checkpoint at the current state.
+     *
+     * @param sessionId - Session identifier
+     * @param state - Serialized agent state
+     */
+    save(sessionId: string, state: AgentStateJSON): Promise<void>;
+    /**
+     * Load the most recent checkpoint for a session.
+     *
+     * @param sessionId - Session identifier
+     * @returns Serialized state or null if not found
+     */
+    load(sessionId: string): Promise<AgentStateJSON | null>;
+    /**
+     * Delete all checkpoints for a session.
+     *
+     * @param sessionId - Session identifier
+     */
+    delete(sessionId: string): Promise<void>;
+    /**
+     * List all session IDs with checkpoints.
+     *
+     * @returns Array of session IDs
+     */
+    list(): Promise<string[]>;
+}
+/**
+ * Options for file-based checkpoint store.
+ */
+interface FileCheckpointOptions {
+    /** Directory for checkpoint files. Default: ".checkpoints" */
+    dir?: string;
+}
+/**
+ * Checkpoint metadata stored alongside state.
+ */
+interface CheckpointMetadata {
+    /** Session identifier */
+    sessionId: string;
+    /** Unique checkpoint ID */
+    checkpointId: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Step number at checkpoint */
+    step: number;
+    /** Agent instance ID */
+    agentId: string;
+}
+/**
+ * Full checkpoint data including state and metadata.
+ */
+interface CheckpointData {
+    /** Checkpoint metadata */
+    metadata: CheckpointMetadata;
+    /** Serialized agent state */
+    state: AgentStateJSON;
+}
+
+export type { CheckpointStore as C, FileCheckpointOptions as F, CheckpointMetadata as a, CheckpointData as b };

package/dist/types-DR02gtFv.d.ts

@@ -0,0 +1,270 @@
+import { LLMInstance, Message, Tool, ToolCall, ToolExecution, Turn, StreamEvent, TokenUsage } from '@providerprotocol/ai';
+import { A as AgentState } from './index-qsPwbY86.js';
+import { C as CheckpointStore } from './types-BhX9uD_d.js';
+
+/**
+ * Result of agent generation.
+ */
+interface GenerateResult {
+    /** Standard UPP Turn */
+    turn: Turn;
+    /** New immutable state */
+    state: AgentState;
+}
+/**
+ * Agent lifecycle hooks for execution control.
+ */
+interface AgentStrategy {
+    /** Evaluate if execution should stop */
+    stopCondition?: (state: AgentState) => boolean | Promise<boolean>;
+    /** Called when step begins */
+    onStepStart?: (step: number, state: AgentState) => void;
+    /** Called during reasoning phase (ReAct) */
+    onReason?: (step: number, reasoning: string) => void;
+    /** Called during action phase */
+    onAct?: (step: number, actions: ToolCall[]) => void;
+    /** Called during observation phase */
+    onObserve?: (step: number, observations: ToolExecution[]) => void;
+    /** Called when step completes */
+    onStepEnd?: (step: number, result: {
+        turn: Turn;
+        state: AgentState;
+    }) => void;
+    /** Called when execution completes */
+    onComplete?: (result: GenerateResult) => void;
+    /** Called on execution error */
+    onError?: (error: Error, state: AgentState) => void | GenerateResult;
+}
+/**
+ * Forward declaration of Agent for use in ExecutionContext.
+ * The actual Agent interface is defined in agent/types.ts.
+ */
+interface AgentRef {
+    id: string;
+    system?: string;
+}
+/**
+ * Context passed to execution strategies.
+ */
+interface ExecutionContext {
+    /** The agent being executed */
+    agent: AgentRef;
+    /** The bound LLM instance */
+    llm: LLMInstance;
+    /** The user input message */
+    input: Message;
+    /** Current immutable state */
+    state: AgentState;
+    /** Resolved tools */
+    tools: Tool[];
+    /** Agent lifecycle hooks */
+    strategy: AgentStrategy;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Checkpoint store for persistence (optional) */
+    checkpoints?: CheckpointStore;
+    /** Session ID for checkpointing */
+    sessionId?: string;
+}
+/**
+ * Result from execution strategy.
+ */
+interface ExecutionResult {
+    /** The complete UPP Turn */
+    turn: Turn;
+    /** New immutable state */
+    state: AgentState;
+}
+/**
+ * UAP-level event types for streaming.
+ */
+type UAPEventType = 'step_start' | 'step_end' | 'reasoning' | 'action' | 'observation' | 'plan_created' | 'plan_step_start' | 'plan_step_end' | 'subagent_start' | 'subagent_event' | 'subagent_end';
+/**
+ * Agent stream event - wraps both UAP and UPP events.
+ */
+interface AgentStreamEvent {
+    /** Event source */
+    source: 'uap' | 'upp';
+    /** Present when source === 'uap' */
+    uap?: {
+        type: UAPEventType;
+        step: number;
+        agentId: string;
+        data: Record<string, unknown>;
+    };
+    /** Present when source === 'upp' */
+    upp?: StreamEvent;
+}
+/**
+ * Streaming result from agent execution.
+ */
+interface AgentStreamResult {
+    /** Async iterator for stream events */
+    [Symbol.asyncIterator](): AsyncIterator<AgentStreamEvent>;
+    /** Resolves to final result after stream completes */
+    result: Promise<GenerateResult>;
+    /** Abort the stream */
+    abort(): void;
+}
+/**
+ * Execution strategy interface.
+ * Strategies define HOW an agent executes (loop, react, plan).
+ */
+interface ExecutionStrategy {
+    /** Strategy name */
+    name: string;
+    /** Execute the strategy */
+    execute(context: ExecutionContext): Promise<ExecutionResult>;
+    /** Execute with streaming */
+    stream(context: ExecutionContext): AgentStreamResult;
+}
+/**
+ * Options for loop() strategy.
+ */
+interface LoopOptions {
+    /** Maximum tool execution rounds. Default: Infinity */
+    maxIterations?: number;
+}
+/**
+ * Options for react() strategy.
+ */
+interface ReactOptions {
+    /** Maximum reason-act-observe cycles. Default: Infinity */
+    maxSteps?: number;
+    /** Prompt suffix for reasoning phase */
+    reasoningPrompt?: string;
+}
+/**
+ * Options for plan() strategy.
+ */
+interface PlanOptions {
+    /** Maximum steps in a plan. Default: Infinity */
+    maxPlanSteps?: number;
+    /** Allow replanning on failure. Default: true */
+    allowReplan?: boolean;
+    /** Schema for plan structure */
+    planSchema?: Record<string, unknown>;
+}
+/**
+ * Tool dependency options for execution ordering.
+ * These extend the base UPP Tool interface with UAP-specific fields.
+ *
+ * @see UAP-1.0 Spec Section 8.5
+ */
+interface ToolDependencyOptions {
+    /**
+     * If true, this tool must complete before other tools start.
+     * Sequential tools create a barrier in parallel execution.
+     */
+    sequential?: boolean;
+    /**
+     * Tool names that must complete before this tool can execute.
+     * Used for explicit dependency chains.
+     */
+    dependsOn?: string[];
+}
+/**
+ * Extended Tool interface with UAP dependency options.
+ * Use this type when defining tools that need execution ordering.
+ *
+ * @example
+ * ```typescript
+ * const readTool: ToolWithDependencies = {
+ *   name: 'read_file',
+ *   description: 'Read a file',
+ *   parameters: { ... },
+ *   sequential: true, // Must complete before other tools
+ *   run: async (params) => { ... },
+ * };
+ *
+ * const writeTool: ToolWithDependencies = {
+ *   name: 'write_file',
+ *   description: 'Write a file',
+ *   parameters: { ... },
+ *   dependsOn: ['read_file'], // Waits for read_file to complete
+ *   run: async (params) => { ... },
+ * };
+ * ```
+ */
+interface ToolWithDependencies extends Tool, ToolDependencyOptions {
+}
+/**
+ * Model-driven tool call with optional execution order hint.
+ * Models MAY include an `after` field to signal dependencies.
+ *
+ * @see UAP-1.0 Spec Section 8.6
+ */
+interface OrderedToolCall extends ToolCall {
+    /** Tool call IDs that must complete before this call executes */
+    after?: string[];
+}
+/**
+ * Sub-agent event types for hierarchical agent execution.
+ *
+ * @see UAP-1.0 Spec Section 8.7
+ */
+type SubagentEventType = 'subagent_start' | 'subagent_event' | 'subagent_end';
+/**
+ * Base fields present in all subagent events.
+ */
+interface SubagentEventBase {
+    /** Unique ID of the sub-agent instance */
+    subagentId: string;
+    /** Type/name of the sub-agent (e.g., "explorer", "planner") */
+    subagentType: string;
+    /** The parent tool call ID that spawned this sub-agent */
+    parentToolCallId: string;
+}
+/**
+ * Event emitted when a sub-agent starts execution.
+ */
+interface SubagentStartEvent extends SubagentEventBase {
+    type: 'subagent_start';
+    /** The task/prompt given to the sub-agent */
+    prompt: string;
+    /** Start timestamp in milliseconds */
+    timestamp: number;
+}
+/**
+ * Event emitted for forwarded events from sub-agent execution.
+ */
+interface SubagentInnerEvent extends SubagentEventBase {
+    type: 'subagent_event';
+    /** The actual event from the sub-agent */
+    innerEvent: AgentStreamEvent;
+}
+/**
+ * Event emitted when a sub-agent completes execution.
+ */
+interface SubagentEndEvent extends SubagentEventBase {
+    type: 'subagent_end';
+    /** Whether the sub-agent completed successfully */
+    success: boolean;
+    /** Sub-agent's response text (if successful) */
+    result?: string;
+    /** Error message (if failed) */
+    error?: string;
+    /** End timestamp in milliseconds */
+    timestamp: number;
+    /** Tools used by the sub-agent */
+    toolExecutions?: Array<{
+        toolName: string;
+        arguments: Record<string, unknown>;
+        result: string;
+    }>;
+    /** Token usage for this sub-agent run */
+    usage?: TokenUsage;
+}
+/**
+ * Union type for all sub-agent events.
+ *
+ * @see UAP-1.0 Spec Section 8.7
+ */
+type SubagentEvent = SubagentStartEvent | SubagentInnerEvent | SubagentEndEvent;
+/**
+ * Callback type for receiving sub-agent events.
+ * Tools that spawn sub-agents SHOULD accept this callback.
+ */
+type OnSubagentEvent = (event: SubagentEvent) => void;
+
+export type { AgentStrategy as A, ExecutionStrategy as E, GenerateResult as G, LoopOptions as L, OnSubagentEvent as O, PlanOptions as P, ReactOptions as R, SubagentEventType as S, ToolDependencyOptions as T, UAPEventType as U, AgentStreamResult as a, AgentStreamEvent as b, SubagentEventBase as c, SubagentStartEvent as d, SubagentInnerEvent as e, SubagentEndEvent as f, SubagentEvent as g, ExecutionContext as h, ExecutionResult as i, ToolWithDependencies as j, OrderedToolCall as k };