@mixrpay/agent-sdk 0.3.3 → 0.3.4

package/dist/index.cjs

@@ -1616,6 +1616,319 @@ Timestamp: ${timestamp}`;
       latencyMs: mixrpay.latencyMs
     };
   }
+  // ===========================================================================
+  // Agent Runtime API
+  // ===========================================================================
+  /**
+   * Run an AI agent with LLM and tool execution.
+   * 
+   * This method orchestrates a full agentic loop:
+   * - Multi-turn reasoning with LLM
+   * - Automatic tool execution
+   * - Bundled billing (single charge at end)
+   * - Optional streaming via SSE
+   * 
+   * @param options - Agent run options
+   * @returns Agent run result with response and cost breakdown
+   * 
+   * @example Basic usage
+   * ```typescript
+   * const result = await wallet.runAgent({
+   *   sessionId: 'sess_abc123',
+   *   messages: [{ role: 'user', content: 'Find AI startups in SF' }],
+   * });
+   * 
+   * console.log(result.response);
+   * console.log(`Cost: $${result.cost.totalUsd.toFixed(4)}`);
+   * ```
+   * 
+   * @example With custom config
+   * ```typescript
+   * const result = await wallet.runAgent({
+   *   sessionId: 'sess_abc123',
+   *   messages: [{ role: 'user', content: 'Research quantum computing' }],
+   *   config: {
+   *     model: 'gpt-4o',
+   *     maxIterations: 15,
+   *     tools: ['platform/exa-search', 'platform/firecrawl-scrape'],
+   *     systemPrompt: 'You are a research assistant.',
+   *   },
+   * });
+   * ```
+   * 
+   * @example With streaming
+   * ```typescript
+   * await wallet.runAgent({
+   *   sessionId: 'sess_abc123',
+   *   messages: [{ role: 'user', content: 'Analyze this company' }],
+   *   stream: true,
+   *   onEvent: (event) => {
+   *     if (event.type === 'llm_chunk') {
+   *       process.stdout.write(event.delta);
+   *     } else if (event.type === 'tool_call') {
+   *       console.log(`Calling tool: ${event.tool}`);
+   *     }
+   *   },
+   * });
+   * ```
+   */
+  async runAgent(options) {
+    const {
+      sessionId,
+      messages,
+      config = {},
+      stream = false,
+      idempotencyKey,
+      onEvent
+    } = options;
+    this.logger.debug("runAgent", { sessionId, messageCount: messages.length, config, stream });
+    const body = {
+      session_id: sessionId,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+      config: {
+        model: config.model,
+        max_iterations: config.maxIterations,
+        tools: config.tools,
+        system_prompt: config.systemPrompt
+      },
+      stream,
+      idempotency_key: idempotencyKey
+    };
+    const AGENT_RUN_TIMEOUT = 18e4;
+    if (!stream) {
+      const response = await fetch(`${this.baseUrl}/api/v2/agent/run`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Mixr-Session": sessionId
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(AGENT_RUN_TIMEOUT)
+      });
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new MixrPayError(error.error || `Agent run failed: ${response.status}`);
+      }
+      const data = await response.json();
+      if (data.cost?.total_usd > 0) {
+        const payment = {
+          amountUsd: data.cost.total_usd,
+          recipient: "mixrpay-agent-run",
+          txHash: data.tx_hash,
+          timestamp: /* @__PURE__ */ new Date(),
+          description: `Agent run: ${data.run_id}`,
+          url: `${this.baseUrl}/api/v2/agent/run`
+        };
+        this.payments.push(payment);
+        this.totalSpentUsd += data.cost.total_usd;
+        this.logger.payment(data.cost.total_usd, "agent-run", data.run_id);
+        if (this.onPayment) {
+          this.onPayment(payment);
+        }
+      }
+      return {
+        runId: data.run_id,
+        status: data.status,
+        response: data.response,
+        iterations: data.iterations,
+        toolsUsed: data.tools_used,
+        cost: {
+          llmUsd: data.cost.llm_usd,
+          toolsUsd: data.cost.tools_usd,
+          totalUsd: data.cost.total_usd
+        },
+        tokens: data.tokens,
+        sessionRemainingUsd: data.session_remaining_usd,
+        txHash: data.tx_hash
+      };
+    }
+    return this.runAgentStreaming(sessionId, body, onEvent);
+  }
+  /**
+   * Internal: Handle streaming agent run via SSE
+   */
+  async runAgentStreaming(sessionId, body, onEvent) {
+    const STREAMING_TIMEOUT = 3e5;
+    const response = await fetch(`${this.baseUrl}/api/v2/agent/run`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Mixr-Session": sessionId
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(STREAMING_TIMEOUT)
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Agent run failed: ${response.status}`);
+    }
+    const reader = response.body?.getReader();
+    if (!reader) {
+      throw new MixrPayError("No response body for streaming");
+    }
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let result = null;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      let currentEvent = "";
+      for (const line of lines) {
+        if (line.startsWith("event: ")) {
+          currentEvent = line.slice(7).trim();
+        } else if (line.startsWith("data: ") && currentEvent) {
+          try {
+            const data = JSON.parse(line.slice(6));
+            const event = this.parseSSEEvent(currentEvent, data);
+            if (event) {
+              onEvent?.(event);
+              if (currentEvent === "complete") {
+                result = {
+                  runId: data.run_id,
+                  status: "completed",
+                  response: data.response,
+                  iterations: data.iterations,
+                  toolsUsed: data.tools_used,
+                  cost: {
+                    llmUsd: 0,
+                    // Not provided in streaming complete
+                    toolsUsd: 0,
+                    totalUsd: data.total_cost_usd
+                  },
+                  tokens: { prompt: 0, completion: 0 },
+                  sessionRemainingUsd: 0,
+                  txHash: data.tx_hash
+                };
+                if (data.total_cost_usd > 0) {
+                  const payment = {
+                    amountUsd: data.total_cost_usd,
+                    recipient: "mixrpay-agent-run",
+                    txHash: data.tx_hash,
+                    timestamp: /* @__PURE__ */ new Date(),
+                    description: `Agent run: ${data.run_id}`,
+                    url: `${this.baseUrl}/api/v2/agent/run`
+                  };
+                  this.payments.push(payment);
+                  this.totalSpentUsd += data.total_cost_usd;
+                  if (this.onPayment) {
+                    this.onPayment(payment);
+                  }
+                }
+              }
+              if (currentEvent === "error") {
+                throw new MixrPayError(data.error || "Agent run failed");
+              }
+            }
+          } catch (e) {
+            if (e instanceof MixrPayError) throw e;
+            this.logger.warn("Failed to parse SSE event:", e);
+          }
+          currentEvent = "";
+        }
+      }
+    }
+    if (!result) {
+      throw new MixrPayError("Agent run completed without final result");
+    }
+    return result;
+  }
+  /**
+   * Internal: Parse SSE event into typed event object
+   */
+  parseSSEEvent(eventType, data) {
+    switch (eventType) {
+      case "run_start":
+        return { type: "run_start", runId: data.run_id };
+      case "iteration_start":
+        return { type: "iteration_start", iteration: data.iteration };
+      case "llm_chunk":
+        return { type: "llm_chunk", delta: data.delta };
+      case "tool_call":
+        return { type: "tool_call", tool: data.tool, arguments: data.arguments };
+      case "tool_result":
+        return {
+          type: "tool_result",
+          tool: data.tool,
+          success: data.success,
+          costUsd: data.cost_usd,
+          error: data.error
+        };
+      case "iteration_complete":
+        return {
+          type: "iteration_complete",
+          iteration: data.iteration,
+          tokens: data.tokens,
+          costUsd: data.cost_usd
+        };
+      case "complete":
+        return {
+          type: "complete",
+          runId: data.run_id,
+          response: data.response,
+          totalCostUsd: data.total_cost_usd,
+          txHash: data.tx_hash,
+          iterations: data.iterations,
+          toolsUsed: data.tools_used
+        };
+      case "error":
+        return {
+          type: "error",
+          error: data.error,
+          partialCostUsd: data.partial_cost_usd
+        };
+      default:
+        return null;
+    }
+  }
+  /**
+   * Get the status of an agent run by ID.
+   * 
+   * @param runId - The agent run ID
+   * @param sessionId - The session ID (for authentication)
+   * @returns Agent run status and results
+   * 
+   * @example
+   * ```typescript
+   * const status = await wallet.getAgentRunStatus('run_abc123', 'sess_xyz789');
+   * console.log(`Status: ${status.status}`);
+   * if (status.status === 'completed') {
+   *   console.log(status.response);
+   * }
+   * ```
+   */
+  async getAgentRunStatus(runId, sessionId) {
+    this.logger.debug("getAgentRunStatus", { runId, sessionId });
+    const response = await fetch(`${this.baseUrl}/api/v2/agent/run/${runId}`, {
+      headers: {
+        "X-Mixr-Session": sessionId
+      }
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to get run status: ${response.status}`);
+    }
+    const data = await response.json();
+    return {
+      runId: data.run_id,
+      status: data.status,
+      response: data.response,
+      iterations: data.iterations,
+      toolsUsed: data.tools_used,
+      cost: {
+        llmUsd: data.cost.llm_usd,
+        toolsUsd: data.cost.tools_usd,
+        totalUsd: data.cost.total_usd
+      },
+      tokens: data.tokens,
+      txHash: data.tx_hash,
+      error: data.error,
+      startedAt: new Date(data.started_at),
+      completedAt: data.completed_at ? new Date(data.completed_at) : void 0
+    };
+  }
   /**
    * Call an MCP tool using session authorization (pre-authorized spending limit).
    * 

package/dist/index.d.cts

@@ -808,6 +808,85 @@ declare class AgentWallet {
      * ```
      */
     callMCPTool(toolName: string, args?: Record<string, unknown>): Promise<MCPToolResult>;
+    /**
+     * Run an AI agent with LLM and tool execution.
+     *
+     * This method orchestrates a full agentic loop:
+     * - Multi-turn reasoning with LLM
+     * - Automatic tool execution
+     * - Bundled billing (single charge at end)
+     * - Optional streaming via SSE
+     *
+     * @param options - Agent run options
+     * @returns Agent run result with response and cost breakdown
+     *
+     * @example Basic usage
+     * ```typescript
+     * const result = await wallet.runAgent({
+     *   sessionId: 'sess_abc123',
+     *   messages: [{ role: 'user', content: 'Find AI startups in SF' }],
+     * });
+     *
+     * console.log(result.response);
+     * console.log(`Cost: $${result.cost.totalUsd.toFixed(4)}`);
+     * ```
+     *
+     * @example With custom config
+     * ```typescript
+     * const result = await wallet.runAgent({
+     *   sessionId: 'sess_abc123',
+     *   messages: [{ role: 'user', content: 'Research quantum computing' }],
+     *   config: {
+     *     model: 'gpt-4o',
+     *     maxIterations: 15,
+     *     tools: ['platform/exa-search', 'platform/firecrawl-scrape'],
+     *     systemPrompt: 'You are a research assistant.',
+     *   },
+     * });
+     * ```
+     *
+     * @example With streaming
+     * ```typescript
+     * await wallet.runAgent({
+     *   sessionId: 'sess_abc123',
+     *   messages: [{ role: 'user', content: 'Analyze this company' }],
+     *   stream: true,
+     *   onEvent: (event) => {
+     *     if (event.type === 'llm_chunk') {
+     *       process.stdout.write(event.delta);
+     *     } else if (event.type === 'tool_call') {
+     *       console.log(`Calling tool: ${event.tool}`);
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    runAgent(options: AgentRunOptions): Promise<AgentRunResult>;
+    /**
+     * Internal: Handle streaming agent run via SSE
+     */
+    private runAgentStreaming;
+    /**
+     * Internal: Parse SSE event into typed event object
+     */
+    private parseSSEEvent;
+    /**
+     * Get the status of an agent run by ID.
+     *
+     * @param runId - The agent run ID
+     * @param sessionId - The session ID (for authentication)
+     * @returns Agent run status and results
+     *
+     * @example
+     * ```typescript
+     * const status = await wallet.getAgentRunStatus('run_abc123', 'sess_xyz789');
+     * console.log(`Status: ${status.status}`);
+     * if (status.status === 'completed') {
+     *   console.log(status.response);
+     * }
+     * ```
+     */
+    getAgentRunStatus(runId: string, sessionId: string): Promise<AgentRunStatusResult>;
     /**
      * Call an MCP tool using session authorization (pre-authorized spending limit).
      *
@@ -869,6 +948,157 @@ interface MCPToolResult {
     /** Execution latency in milliseconds */
     latencyMs?: number;
 }
+/**
+ * Message in an agent conversation
+ */
+interface AgentMessage {
+    /** Message role */
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    /** Message content */
+    content: string;
+}
+/**
+ * Configuration for an agent run
+ */
+interface AgentRunConfig {
+    /** LLM model to use (default: gpt-4o-mini) */
+    model?: string;
+    /** Maximum iterations before stopping (default: 10, max: 25) */
+    maxIterations?: number;
+    /** Specific tools to enable (e.g., ['platform/exa-search', 'platform/firecrawl-scrape']) */
+    tools?: string[];
+    /** Custom system prompt for the agent */
+    systemPrompt?: string;
+}
+/**
+ * Options for running an agent
+ */
+interface AgentRunOptions {
+    /** Session ID for authentication and billing */
+    sessionId: string;
+    /** Conversation messages */
+    messages: AgentMessage[];
+    /** Agent configuration */
+    config?: AgentRunConfig;
+    /** Enable SSE streaming (default: false) */
+    stream?: boolean;
+    /** Unique key for idempotency */
+    idempotencyKey?: string;
+    /** Callback for streaming events */
+    onEvent?: (event: AgentRunEvent) => void;
+}
+/**
+ * Result from an agent run
+ */
+interface AgentRunResult {
+    /** Unique run ID */
+    runId: string;
+    /** Run status */
+    status: 'completed' | 'failed';
+    /** Final response from the agent */
+    response: string;
+    /** Number of iterations performed */
+    iterations: number;
+    /** Tools used during the run */
+    toolsUsed: string[];
+    /** Cost breakdown */
+    cost: {
+        /** LLM cost in USD */
+        llmUsd: number;
+        /** Tool execution cost in USD */
+        toolsUsd: number;
+        /** Total cost in USD */
+        totalUsd: number;
+    };
+    /** Token usage */
+    tokens: {
+        /** Prompt tokens used */
+        prompt: number;
+        /** Completion tokens used */
+        completion: number;
+    };
+    /** Remaining session balance in USD */
+    sessionRemainingUsd: number;
+    /** On-chain transaction hash for payment */
+    txHash?: string;
+}
+/**
+ * Streaming events from an agent run
+ */
+type AgentRunEvent = {
+    type: 'run_start';
+    runId: string;
+} | {
+    type: 'iteration_start';
+    iteration: number;
+} | {
+    type: 'llm_chunk';
+    delta: string;
+} | {
+    type: 'tool_call';
+    tool: string;
+    arguments: unknown;
+} | {
+    type: 'tool_result';
+    tool: string;
+    success: boolean;
+    costUsd: number;
+    error?: string;
+} | {
+    type: 'iteration_complete';
+    iteration: number;
+    tokens?: {
+        prompt?: number;
+        completion?: number;
+    };
+    costUsd?: number;
+} | {
+    type: 'complete';
+    runId: string;
+    response: string;
+    totalCostUsd: number;
+    txHash?: string;
+    iterations: number;
+    toolsUsed: string[];
+} | {
+    type: 'error';
+    error: string;
+    partialCostUsd?: number;
+};
+/**
+ * Result from getting agent run status
+ */
+interface AgentRunStatusResult {
+    /** Unique run ID */
+    runId: string;
+    /** Run status */
+    status: 'running' | 'completed' | 'failed' | 'interrupted';
+    /** Final response (if completed) */
+    response?: string;
+    /** Number of iterations performed */
+    iterations: number;
+    /** Tools used during the run */
+    toolsUsed: string[];
+    /** Cost breakdown */
+    cost: {
+        llmUsd: number;
+        toolsUsd: number;
+        totalUsd: number;
+    };
+    /** Token usage */
+    tokens: {
+        prompt: number;
+        completion: number;
+    };
+    /** On-chain transaction hash */
+    txHash?: string;
+    /** Error message (if failed) */
+    error?: string;
+    /** When the run started */
+    startedAt: Date;
+    /** When the run completed */
+    completedAt?: Date;
+}
 
 /**
  * MixrPay Agent SDK - Custom Errors
@@ -1198,4 +1428,4 @@ declare class SessionRevokedError extends MixrPayError {
  */
 declare function isMixrPayError(error: unknown): error is MixrPayError;
 
-export { AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, isMixrPayError };
+export { type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, isMixrPayError };

package/dist/index.d.ts

@@ -808,6 +808,85 @@ declare class AgentWallet {
      * ```
      */
     callMCPTool(toolName: string, args?: Record<string, unknown>): Promise<MCPToolResult>;
+    /**
+     * Run an AI agent with LLM and tool execution.
+     *
+     * This method orchestrates a full agentic loop:
+     * - Multi-turn reasoning with LLM
+     * - Automatic tool execution
+     * - Bundled billing (single charge at end)
+     * - Optional streaming via SSE
+     *
+     * @param options - Agent run options
+     * @returns Agent run result with response and cost breakdown
+     *
+     * @example Basic usage
+     * ```typescript
+     * const result = await wallet.runAgent({
+     *   sessionId: 'sess_abc123',
+     *   messages: [{ role: 'user', content: 'Find AI startups in SF' }],
+     * });
+     *
+     * console.log(result.response);
+     * console.log(`Cost: $${result.cost.totalUsd.toFixed(4)}`);
+     * ```
+     *
+     * @example With custom config
+     * ```typescript
+     * const result = await wallet.runAgent({
+     *   sessionId: 'sess_abc123',
+     *   messages: [{ role: 'user', content: 'Research quantum computing' }],
+     *   config: {
+     *     model: 'gpt-4o',
+     *     maxIterations: 15,
+     *     tools: ['platform/exa-search', 'platform/firecrawl-scrape'],
+     *     systemPrompt: 'You are a research assistant.',
+     *   },
+     * });
+     * ```
+     *
+     * @example With streaming
+     * ```typescript
+     * await wallet.runAgent({
+     *   sessionId: 'sess_abc123',
+     *   messages: [{ role: 'user', content: 'Analyze this company' }],
+     *   stream: true,
+     *   onEvent: (event) => {
+     *     if (event.type === 'llm_chunk') {
+     *       process.stdout.write(event.delta);
+     *     } else if (event.type === 'tool_call') {
+     *       console.log(`Calling tool: ${event.tool}`);
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    runAgent(options: AgentRunOptions): Promise<AgentRunResult>;
+    /**
+     * Internal: Handle streaming agent run via SSE
+     */
+    private runAgentStreaming;
+    /**
+     * Internal: Parse SSE event into typed event object
+     */
+    private parseSSEEvent;
+    /**
+     * Get the status of an agent run by ID.
+     *
+     * @param runId - The agent run ID
+     * @param sessionId - The session ID (for authentication)
+     * @returns Agent run status and results
+     *
+     * @example
+     * ```typescript
+     * const status = await wallet.getAgentRunStatus('run_abc123', 'sess_xyz789');
+     * console.log(`Status: ${status.status}`);
+     * if (status.status === 'completed') {
+     *   console.log(status.response);
+     * }
+     * ```
+     */
+    getAgentRunStatus(runId: string, sessionId: string): Promise<AgentRunStatusResult>;
     /**
      * Call an MCP tool using session authorization (pre-authorized spending limit).
      *
@@ -869,6 +948,157 @@ interface MCPToolResult {
     /** Execution latency in milliseconds */
     latencyMs?: number;
 }
+/**
+ * Message in an agent conversation
+ */
+interface AgentMessage {
+    /** Message role */
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    /** Message content */
+    content: string;
+}
+/**
+ * Configuration for an agent run
+ */
+interface AgentRunConfig {
+    /** LLM model to use (default: gpt-4o-mini) */
+    model?: string;
+    /** Maximum iterations before stopping (default: 10, max: 25) */
+    maxIterations?: number;
+    /** Specific tools to enable (e.g., ['platform/exa-search', 'platform/firecrawl-scrape']) */
+    tools?: string[];
+    /** Custom system prompt for the agent */
+    systemPrompt?: string;
+}
+/**
+ * Options for running an agent
+ */
+interface AgentRunOptions {
+    /** Session ID for authentication and billing */
+    sessionId: string;
+    /** Conversation messages */
+    messages: AgentMessage[];
+    /** Agent configuration */
+    config?: AgentRunConfig;
+    /** Enable SSE streaming (default: false) */
+    stream?: boolean;
+    /** Unique key for idempotency */
+    idempotencyKey?: string;
+    /** Callback for streaming events */
+    onEvent?: (event: AgentRunEvent) => void;
+}
+/**
+ * Result from an agent run
+ */
+interface AgentRunResult {
+    /** Unique run ID */
+    runId: string;
+    /** Run status */
+    status: 'completed' | 'failed';
+    /** Final response from the agent */
+    response: string;
+    /** Number of iterations performed */
+    iterations: number;
+    /** Tools used during the run */
+    toolsUsed: string[];
+    /** Cost breakdown */
+    cost: {
+        /** LLM cost in USD */
+        llmUsd: number;
+        /** Tool execution cost in USD */
+        toolsUsd: number;
+        /** Total cost in USD */
+        totalUsd: number;
+    };
+    /** Token usage */
+    tokens: {
+        /** Prompt tokens used */
+        prompt: number;
+        /** Completion tokens used */
+        completion: number;
+    };
+    /** Remaining session balance in USD */
+    sessionRemainingUsd: number;
+    /** On-chain transaction hash for payment */
+    txHash?: string;
+}
+/**
+ * Streaming events from an agent run
+ */
+type AgentRunEvent = {
+    type: 'run_start';
+    runId: string;
+} | {
+    type: 'iteration_start';
+    iteration: number;
+} | {
+    type: 'llm_chunk';
+    delta: string;
+} | {
+    type: 'tool_call';
+    tool: string;
+    arguments: unknown;
+} | {
+    type: 'tool_result';
+    tool: string;
+    success: boolean;
+    costUsd: number;
+    error?: string;
+} | {
+    type: 'iteration_complete';
+    iteration: number;
+    tokens?: {
+        prompt?: number;
+        completion?: number;
+    };
+    costUsd?: number;
+} | {
+    type: 'complete';
+    runId: string;
+    response: string;
+    totalCostUsd: number;
+    txHash?: string;
+    iterations: number;
+    toolsUsed: string[];
+} | {
+    type: 'error';
+    error: string;
+    partialCostUsd?: number;
+};
+/**
+ * Result from getting agent run status
+ */
+interface AgentRunStatusResult {
+    /** Unique run ID */
+    runId: string;
+    /** Run status */
+    status: 'running' | 'completed' | 'failed' | 'interrupted';
+    /** Final response (if completed) */
+    response?: string;
+    /** Number of iterations performed */
+    iterations: number;
+    /** Tools used during the run */
+    toolsUsed: string[];
+    /** Cost breakdown */
+    cost: {
+        llmUsd: number;
+        toolsUsd: number;
+        totalUsd: number;
+    };
+    /** Token usage */
+    tokens: {
+        prompt: number;
+        completion: number;
+    };
+    /** On-chain transaction hash */
+    txHash?: string;
+    /** Error message (if failed) */
+    error?: string;
+    /** When the run started */
+    startedAt: Date;
+    /** When the run completed */
+    completedAt?: Date;
+}
 
 /**
  * MixrPay Agent SDK - Custom Errors
@@ -1198,4 +1428,4 @@ declare class SessionRevokedError extends MixrPayError {
  */
 declare function isMixrPayError(error: unknown): error is MixrPayError;
 
-export { AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, isMixrPayError };
+export { type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, isMixrPayError };

package/dist/index.js

@@ -1582,6 +1582,319 @@ Timestamp: ${timestamp}`;
       latencyMs: mixrpay.latencyMs
     };
   }
+  // ===========================================================================
+  // Agent Runtime API
+  // ===========================================================================
+  /**
+   * Run an AI agent with LLM and tool execution.
+   * 
+   * This method orchestrates a full agentic loop:
+   * - Multi-turn reasoning with LLM
+   * - Automatic tool execution
+   * - Bundled billing (single charge at end)
+   * - Optional streaming via SSE
+   * 
+   * @param options - Agent run options
+   * @returns Agent run result with response and cost breakdown
+   * 
+   * @example Basic usage
+   * ```typescript
+   * const result = await wallet.runAgent({
+   *   sessionId: 'sess_abc123',
+   *   messages: [{ role: 'user', content: 'Find AI startups in SF' }],
+   * });
+   * 
+   * console.log(result.response);
+   * console.log(`Cost: $${result.cost.totalUsd.toFixed(4)}`);
+   * ```
+   * 
+   * @example With custom config
+   * ```typescript
+   * const result = await wallet.runAgent({
+   *   sessionId: 'sess_abc123',
+   *   messages: [{ role: 'user', content: 'Research quantum computing' }],
+   *   config: {
+   *     model: 'gpt-4o',
+   *     maxIterations: 15,
+   *     tools: ['platform/exa-search', 'platform/firecrawl-scrape'],
+   *     systemPrompt: 'You are a research assistant.',
+   *   },
+   * });
+   * ```
+   * 
+   * @example With streaming
+   * ```typescript
+   * await wallet.runAgent({
+   *   sessionId: 'sess_abc123',
+   *   messages: [{ role: 'user', content: 'Analyze this company' }],
+   *   stream: true,
+   *   onEvent: (event) => {
+   *     if (event.type === 'llm_chunk') {
+   *       process.stdout.write(event.delta);
+   *     } else if (event.type === 'tool_call') {
+   *       console.log(`Calling tool: ${event.tool}`);
+   *     }
+   *   },
+   * });
+   * ```
+   */
+  async runAgent(options) {
+    const {
+      sessionId,
+      messages,
+      config = {},
+      stream = false,
+      idempotencyKey,
+      onEvent
+    } = options;
+    this.logger.debug("runAgent", { sessionId, messageCount: messages.length, config, stream });
+    const body = {
+      session_id: sessionId,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+      config: {
+        model: config.model,
+        max_iterations: config.maxIterations,
+        tools: config.tools,
+        system_prompt: config.systemPrompt
+      },
+      stream,
+      idempotency_key: idempotencyKey
+    };
+    const AGENT_RUN_TIMEOUT = 18e4;
+    if (!stream) {
+      const response = await fetch(`${this.baseUrl}/api/v2/agent/run`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Mixr-Session": sessionId
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(AGENT_RUN_TIMEOUT)
+      });
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new MixrPayError(error.error || `Agent run failed: ${response.status}`);
+      }
+      const data = await response.json();
+      if (data.cost?.total_usd > 0) {
+        const payment = {
+          amountUsd: data.cost.total_usd,
+          recipient: "mixrpay-agent-run",
+          txHash: data.tx_hash,
+          timestamp: /* @__PURE__ */ new Date(),
+          description: `Agent run: ${data.run_id}`,
+          url: `${this.baseUrl}/api/v2/agent/run`
+        };
+        this.payments.push(payment);
+        this.totalSpentUsd += data.cost.total_usd;
+        this.logger.payment(data.cost.total_usd, "agent-run", data.run_id);
+        if (this.onPayment) {
+          this.onPayment(payment);
+        }
+      }
+      return {
+        runId: data.run_id,
+        status: data.status,
+        response: data.response,
+        iterations: data.iterations,
+        toolsUsed: data.tools_used,
+        cost: {
+          llmUsd: data.cost.llm_usd,
+          toolsUsd: data.cost.tools_usd,
+          totalUsd: data.cost.total_usd
+        },
+        tokens: data.tokens,
+        sessionRemainingUsd: data.session_remaining_usd,
+        txHash: data.tx_hash
+      };
+    }
+    return this.runAgentStreaming(sessionId, body, onEvent);
+  }
+  /**
+   * Internal: Handle streaming agent run via SSE
+   */
+  async runAgentStreaming(sessionId, body, onEvent) {
+    const STREAMING_TIMEOUT = 3e5;
+    const response = await fetch(`${this.baseUrl}/api/v2/agent/run`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Mixr-Session": sessionId
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(STREAMING_TIMEOUT)
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Agent run failed: ${response.status}`);
+    }
+    const reader = response.body?.getReader();
+    if (!reader) {
+      throw new MixrPayError("No response body for streaming");
+    }
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let result = null;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      let currentEvent = "";
+      for (const line of lines) {
+        if (line.startsWith("event: ")) {
+          currentEvent = line.slice(7).trim();
+        } else if (line.startsWith("data: ") && currentEvent) {
+          try {
+            const data = JSON.parse(line.slice(6));
+            const event = this.parseSSEEvent(currentEvent, data);
+            if (event) {
+              onEvent?.(event);
+              if (currentEvent === "complete") {
+                result = {
+                  runId: data.run_id,
+                  status: "completed",
+                  response: data.response,
+                  iterations: data.iterations,
+                  toolsUsed: data.tools_used,
+                  cost: {
+                    llmUsd: 0,
+                    // Not provided in streaming complete
+                    toolsUsd: 0,
+                    totalUsd: data.total_cost_usd
+                  },
+                  tokens: { prompt: 0, completion: 0 },
+                  sessionRemainingUsd: 0,
+                  txHash: data.tx_hash
+                };
+                if (data.total_cost_usd > 0) {
+                  const payment = {
+                    amountUsd: data.total_cost_usd,
+                    recipient: "mixrpay-agent-run",
+                    txHash: data.tx_hash,
+                    timestamp: /* @__PURE__ */ new Date(),
+                    description: `Agent run: ${data.run_id}`,
+                    url: `${this.baseUrl}/api/v2/agent/run`
+                  };
+                  this.payments.push(payment);
+                  this.totalSpentUsd += data.total_cost_usd;
+                  if (this.onPayment) {
+                    this.onPayment(payment);
+                  }
+                }
+              }
+              if (currentEvent === "error") {
+                throw new MixrPayError(data.error || "Agent run failed");
+              }
+            }
+          } catch (e) {
+            if (e instanceof MixrPayError) throw e;
+            this.logger.warn("Failed to parse SSE event:", e);
+          }
+          currentEvent = "";
+        }
+      }
+    }
+    if (!result) {
+      throw new MixrPayError("Agent run completed without final result");
+    }
+    return result;
+  }
+  /**
+   * Internal: Parse SSE event into typed event object
+   */
+  parseSSEEvent(eventType, data) {
+    switch (eventType) {
+      case "run_start":
+        return { type: "run_start", runId: data.run_id };
+      case "iteration_start":
+        return { type: "iteration_start", iteration: data.iteration };
+      case "llm_chunk":
+        return { type: "llm_chunk", delta: data.delta };
+      case "tool_call":
+        return { type: "tool_call", tool: data.tool, arguments: data.arguments };
+      case "tool_result":
+        return {
+          type: "tool_result",
+          tool: data.tool,
+          success: data.success,
+          costUsd: data.cost_usd,
+          error: data.error
+        };
+      case "iteration_complete":
+        return {
+          type: "iteration_complete",
+          iteration: data.iteration,
+          tokens: data.tokens,
+          costUsd: data.cost_usd
+        };
+      case "complete":
+        return {
+          type: "complete",
+          runId: data.run_id,
+          response: data.response,
+          totalCostUsd: data.total_cost_usd,
+          txHash: data.tx_hash,
+          iterations: data.iterations,
+          toolsUsed: data.tools_used
+        };
+      case "error":
+        return {
+          type: "error",
+          error: data.error,
+          partialCostUsd: data.partial_cost_usd
+        };
+      default:
+        return null;
+    }
+  }
+  /**
+   * Get the status of an agent run by ID.
+   * 
+   * @param runId - The agent run ID
+   * @param sessionId - The session ID (for authentication)
+   * @returns Agent run status and results
+   * 
+   * @example
+   * ```typescript
+   * const status = await wallet.getAgentRunStatus('run_abc123', 'sess_xyz789');
+   * console.log(`Status: ${status.status}`);
+   * if (status.status === 'completed') {
+   *   console.log(status.response);
+   * }
+   * ```
+   */
+  async getAgentRunStatus(runId, sessionId) {
+    this.logger.debug("getAgentRunStatus", { runId, sessionId });
+    const response = await fetch(`${this.baseUrl}/api/v2/agent/run/${runId}`, {
+      headers: {
+        "X-Mixr-Session": sessionId
+      }
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to get run status: ${response.status}`);
+    }
+    const data = await response.json();
+    return {
+      runId: data.run_id,
+      status: data.status,
+      response: data.response,
+      iterations: data.iterations,
+      toolsUsed: data.tools_used,
+      cost: {
+        llmUsd: data.cost.llm_usd,
+        toolsUsd: data.cost.tools_usd,
+        totalUsd: data.cost.total_usd
+      },
+      tokens: data.tokens,
+      txHash: data.tx_hash,
+      error: data.error,
+      startedAt: new Date(data.started_at),
+      completedAt: data.completed_at ? new Date(data.completed_at) : void 0
+    };
+  }
   /**
    * Call an MCP tool using session authorization (pre-authorized spending limit).
    * 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mixrpay/agent-sdk",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "MixrPay Agent SDK - Enable AI agents to make x402 payments with session keys",
   "type": "module",
   "main": "./dist/index.js",