@mixrpay/agent-sdk 0.8.6 → 0.8.8

package/dist/index.d.ts

@@ -129,8 +129,14 @@ interface PaymentEvent {
  * Information about a session key.
  */
 interface SessionKeyInfo {
-    /** The session key's address (derived public key) */
+    /** The session key's derived address (used for signing requests) */
     address: string;
+    /**
+     * The wallet address this session key is authorized to spend from.
+     * This is the human's funded wallet, NOT your agent's external wallet.
+     * All charges are deducted from this wallet.
+     */
+    walletAddress: string | null;
     /** Whether the session key is currently valid */
     isValid: boolean;
     /** Spending limits configured for this session key */
@@ -379,7 +385,7 @@ interface SessionStats {
  */
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.8.5";
+declare const SDK_VERSION = "0.8.7";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -1507,6 +1513,165 @@ declare class AgentWallet {
      * Parse Glama server response data.
      */
     private parseGlamaServer;
+    /**
+     * Deploy a JIT Task Agent - a serverless agent that executes a specific task.
+     *
+     * JIT Task Agents run on Cloudflare Workers and execute an agentic loop
+     * (LLM + tools) within a budget cap. They self-destruct when complete.
+     *
+     * @param options - Task agent deployment options
+     * @returns Deployed task agent instance with endpoints
+     *
+     * @example Basic usage
+     * ```typescript
+     * const result = await wallet.deployTaskAgent({
+     *   name: 'Research Agent',
+     *   prompt: 'Research the top 5 AI startups in San Francisco',
+     *   budgetUsd: 5.00,
+     *   tools: ['platform/exa-search', 'platform/firecrawl-scrape'],
+     * });
+     *
+     * console.log('Task ID:', result.instance.id);
+     * console.log('Status URL:', result.instance.statusUrl);
+     * ```
+     *
+     * @example With auto-run
+     * ```typescript
+     * const result = await wallet.deployTaskAgent({
+     *   name: 'Data Collector',
+     *   prompt: 'Collect pricing data from competitor websites',
+     *   budgetUsd: 10.00,
+     *   tools: ['platform/firecrawl-scrape'],
+     *   autoRun: true, // Start immediately
+     * });
+     *
+     * // Wait for completion
+     * const finalResult = await wallet.waitForTaskAgent(result.instance.id);
+     * console.log('Result:', finalResult.result);
+     * ```
+     */
+    deployTaskAgent(options: DeployTaskAgentOptions): Promise<DeployTaskAgentResult>;
+    /**
+     * Get the status of a JIT Task Agent.
+     *
+     * @param instanceId - The task agent instance ID
+     * @returns Current status and details
+     *
+     * @example
+     * ```typescript
+     * const status = await wallet.getTaskAgentStatus('cuid_abc123');
+     * console.log('Status:', status.status);
+     * console.log('Iterations:', status.iterations.current, '/', status.iterations.max);
+     * console.log('Spent:', status.budget.spentUsd, '/', status.budget.totalUsd);
+     * ```
+     */
+    getTaskAgentStatus(instanceId: string): Promise<TaskAgentStatus>;
+    /**
+     * Trigger execution of a JIT Task Agent.
+     *
+     * Only works for agents in 'active' status (not yet started).
+     *
+     * @param instanceId - The task agent instance ID
+     * @returns Trigger result
+     *
+     * @example
+     * ```typescript
+     * // Deploy without auto-run
+     * const { instance } = await wallet.deployTaskAgent({
+     *   name: 'Research',
+     *   prompt: 'Research AI trends',
+     *   budgetUsd: 5.00,
+     * });
+     *
+     * // Later, trigger execution
+     * await wallet.triggerTaskAgent(instance.id);
+     * ```
+     */
+    triggerTaskAgent(instanceId: string): Promise<{
+        success: boolean;
+        status: string;
+    }>;
+    /**
+     * Cancel a JIT Task Agent.
+     *
+     * Stops execution and marks the task as cancelled.
+     * Cannot cancel tasks that are already completed/failed.
+     *
+     * @param instanceId - The task agent instance ID
+     * @returns Cancel result
+     *
+     * @example
+     * ```typescript
+     * await wallet.cancelTaskAgent('cuid_abc123');
+     * console.log('Task cancelled');
+     * ```
+     */
+    cancelTaskAgent(instanceId: string): Promise<{
+        success: boolean;
+        status: string;
+    }>;
+    /**
+     * List JIT Task Agents for the authenticated user.
+     *
+     * Returns deployed task agents with optional filtering by status,
+     * plan, or task. Includes pagination and summary statistics.
+     *
+     * @param options - Optional filter and pagination parameters
+     * @returns List of task agents with pagination and stats
+     *
+     * @example List all task agents
+     * ```typescript
+     * const { taskAgents, pagination, stats } = await wallet.listTaskAgents();
+     * console.log(`${pagination.total} total agents, ${stats.active} active`);
+     * ```
+     *
+     * @example Filter by status
+     * ```typescript
+     * const { taskAgents } = await wallet.listTaskAgents({ status: 'running' });
+     * for (const agent of taskAgents) {
+     *   console.log(`${agent.name}: $${agent.budget.spentUsd}/$${agent.budget.totalUsd}`);
+     * }
+     * ```
+     *
+     * @example Filter by plan
+     * ```typescript
+     * const { taskAgents } = await wallet.listTaskAgents({ planId: 'plan_abc' });
+     * ```
+     */
+    listTaskAgents(options?: ListTaskAgentsOptions): Promise<ListTaskAgentsResult>;
+    /**
+     * Wait for a JIT Task Agent to complete.
+     *
+     * Polls the status until the task reaches a terminal state
+     * (completed, failed, cancelled, budget_exceeded, expired).
+     *
+     * @param instanceId - The task agent instance ID
+     * @param options - Wait options
+     * @returns Final task result
+     *
+     * @example
+     * ```typescript
+     * const result = await wallet.waitForTaskAgent('cuid_abc123', {
+     *   pollIntervalMs: 2000,
+     *   timeoutMs: 300000, // 5 minutes
+     * });
+     *
+     * if (result.status === 'completed') {
+     *   console.log('Result:', result.result);
+     * } else {
+     *   console.log('Failed:', result.error);
+     * }
+     * ```
+     */
+    waitForTaskAgent(instanceId: string, options?: WaitForTaskAgentOptions): Promise<TaskAgentResult>;
+    /**
+     * Parse task agent instance from API response.
+     */
+    private parseTaskAgentInstance;
+    /**
+     * Parse task agent status from API response.
+     */
+    private parseTaskAgentStatus;
     /**
      * Simple LLM completion - single-turn, no tools.
      *
@@ -2541,6 +2706,262 @@ interface AgentRunStatusResult {
     /** When the run completed */
     completedAt?: Date;
 }
+/**
+ * Options for deploying a JIT Task Agent
+ */
+interface DeployTaskAgentOptions {
+    /** Display name for the task agent */
+    name: string;
+    /** The task prompt - what the agent should accomplish */
+    prompt: string;
+    /** Custom system prompt (optional) */
+    systemPrompt?: string;
+    /** LLM model to use (default: claude-sonnet-4-5) */
+    model?: string;
+    /** MCP tools to enable (e.g., ['platform/exa-search']) */
+    tools?: string[];
+    /** Budget cap in USD (min: $0.01, max: $1000) */
+    budgetUsd: number;
+    /** Time-to-live in hours (default: 24, max: 48) */
+    ttlHours?: number;
+    /** Maximum iterations (default: 10, max: 50) */
+    maxIterations?: number;
+    /** Optional plan ID for Mission Control integration */
+    planId?: string;
+    /** Optional task ID for Mission Control integration */
+    taskId?: string;
+    /** Idempotency key to prevent duplicate deploys */
+    idempotencyKey?: string;
+    /** Start execution immediately (default: false) */
+    autoRun?: boolean;
+}
+/**
+ * Result from deploying a JIT Task Agent
+ */
+interface DeployTaskAgentResult {
+    /** The deployed task agent instance */
+    instance: TaskAgentInstance;
+    /** Whether this was an idempotent return */
+    idempotent: boolean;
+    /** Request ID for debugging */
+    requestId: string;
+}
+/**
+ * A deployed JIT Task Agent instance
+ */
+interface TaskAgentInstance {
+    /** Unique instance ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Base endpoint URL */
+    endpointUrl: string;
+    /** Status check URL */
+    statusUrl: string;
+    /** Trigger execution URL */
+    triggerUrl: string;
+    /** Cancel URL */
+    cancelUrl: string;
+    /** Result URL */
+    resultUrl: string;
+    /** Current status */
+    status: string;
+    /** Budget in USD */
+    budgetUsd: number;
+    /** When the instance expires */
+    expiresAt: Date;
+    /** Spawn depth (for nested agents) */
+    depth: number;
+    /** Maximum iterations allowed */
+    maxIterations: number;
+}
+/**
+ * Full status of a JIT Task Agent
+ */
+interface TaskAgentStatus {
+    /** Unique instance ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** The task prompt */
+    prompt: string;
+    /** LLM model */
+    model: string;
+    /** Enabled tools */
+    tools: string[];
+    /** Current status */
+    status: string;
+    /** Budget tracking */
+    budget: {
+        totalUsd: number;
+        spentUsd: number;
+        remainingUsd: number;
+    };
+    /** Iteration tracking */
+    iterations: {
+        current: number;
+        max: number;
+    };
+    /** Usage statistics */
+    usage: {
+        toolCalls: number;
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** Final result (if completed) */
+    result?: string;
+    /** Error message (if failed) */
+    error?: string;
+    /** Spawn depth */
+    depth: number;
+    /** Plan ID (if linked) */
+    planId?: string;
+    /** Task ID (if linked) */
+    taskId?: string;
+    /** Endpoint URLs */
+    endpoints: {
+        statusUrl: string;
+        triggerUrl: string;
+        cancelUrl: string;
+        resultUrl: string;
+    };
+    /** TTL in hours */
+    ttlHours: number;
+    /** When the instance expires */
+    expiresAt: Date;
+    /** When the instance was created */
+    createdAt: Date;
+    /** When execution started */
+    startedAt?: Date;
+    /** When execution completed */
+    completedAt?: Date;
+}
+/**
+ * Options for waiting for a task agent to complete
+ */
+interface WaitForTaskAgentOptions {
+    /** Poll interval in milliseconds (default: 2000) */
+    pollIntervalMs?: number;
+    /** Timeout in milliseconds (default: 300000 = 5 minutes) */
+    timeoutMs?: number;
+}
+/**
+ * Final result from a completed JIT Task Agent
+ */
+interface TaskAgentResult {
+    /** Instance ID */
+    id: string;
+    /** Final status */
+    status: 'completed' | 'failed' | 'cancelled' | 'budget_exceeded' | 'expired';
+    /** Result text (if completed) */
+    result?: string;
+    /** Error message (if failed) */
+    error?: string;
+    /** Total USD spent */
+    spentUsd: number;
+    /** Number of iterations executed */
+    iterations: number;
+    /** Number of tool calls made */
+    toolCalls: number;
+    /** When execution completed */
+    completedAt?: Date;
+}
+/**
+ * Options for listing JIT Task Agents
+ */
+interface ListTaskAgentsOptions {
+    /** Filter by status (e.g., 'running', 'completed', 'failed') */
+    status?: string;
+    /** Filter by plan ID */
+    planId?: string;
+    /** Filter by task ID */
+    taskId?: string;
+    /** Maximum results to return (default: 50, max: 100) */
+    limit?: number;
+    /** Pagination offset (default: 0) */
+    offset?: number;
+}
+/**
+ * Result from listing JIT Task Agents
+ */
+interface ListTaskAgentsResult {
+    /** Array of task agents */
+    taskAgents: TaskAgentListItem[];
+    /** Pagination info */
+    pagination: {
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    };
+    /** Summary statistics */
+    stats: {
+        active: number;
+        completed: number;
+        failed: number;
+        totalSpentUsd: number;
+    };
+}
+/**
+ * A task agent summary in a list response
+ */
+interface TaskAgentListItem {
+    /** Unique instance ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Task prompt (truncated to 200 chars) */
+    prompt: string;
+    /** LLM model */
+    model: string;
+    /** Enabled tools */
+    tools: string[];
+    /** Current status */
+    status: string;
+    /** Budget tracking */
+    budget: {
+        totalUsd: number;
+        spentUsd: number;
+        remainingUsd: number;
+    };
+    /** Iteration tracking */
+    iterations: {
+        current: number;
+        max: number;
+    };
+    /** Usage statistics */
+    usage: {
+        toolCalls: number;
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** Final result (truncated to 500 chars, if completed) */
+    result?: string;
+    /** Error message (if failed) */
+    error?: string;
+    /** Spawn depth */
+    depth: number;
+    /** Linked plan (if any) */
+    plan: {
+        id: string;
+        title: string;
+    } | null;
+    /** Linked task (if any) */
+    task: {
+        id: string;
+        title: string;
+    } | null;
+    /** TTL in hours */
+    ttlHours: number;
+    /** When the instance expires */
+    expiresAt: Date;
+    /** When the instance was created */
+    createdAt: Date;
+    /** When execution started */
+    startedAt?: Date;
+    /** When execution completed */
+    completedAt?: Date;
+}
 
 /**
  * MixrPay Agent SDK - Custom Errors