@mixrpay/agent-sdk 0.8.6 → 0.8.8

package/README.md

@@ -2,15 +2,71 @@
 
 Enable AI agents to make payments to MixrPay-powered APIs.
 
+## Getting Started: Claim an Access Code
+
+Agents get spending authorization by claiming an **Access Code** from a human wallet owner.
+
+### Step 1: Human Creates Access Code
+
+The human logs in at [mixrpay.com/manage/invites](https://www.mixrpay.com/manage/invites), deposits funds, and creates an Access Code (e.g., `mixr-abc123`) with a budget.
+
+### Step 2: Agent Claims the Access Code
+
+```typescript
+import { AgentWallet } from '@mixrpay/agent-sdk';
+
+// Claim the Access Code to get your session key
+const result = await AgentWallet.claimInvite({
+  inviteCode: 'mixr-abc123',              // From the human
+  privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+});
+
+// IMPORTANT: Save this immediately — shown ONCE, cannot be recovered!
+console.log('Session Key:', result.sessionKey);  // sk_live_xxx
+console.log('Budget:', result.limits.budgetUsd);
+console.log('Invited by:', result.inviterName);
+```
+
+### Step 3: Use the Session Key
+
+```typescript
+const wallet = new AgentWallet({
+  sessionKey: result.sessionKey,  // or process.env.MIXRPAY_SESSION_KEY
+});
+
+// All spending is authorized from the human's wallet
+const response = await wallet.fetch('https://api.example.com/paid-endpoint');
+```
+
+## Understanding Wallet Addresses
+
+When you claim an Access Code, two addresses are involved:
+
+| Address | What it is | Purpose |
+|---------|-----------|---------|
+| `info.address` | Session key's derived address | Used for signing requests |
+| `info.walletAddress` | Human's funded wallet | Where funds are charged FROM |
+
+**Verify which wallet you're spending from:**
+
+```typescript
+const info = await wallet.getSessionKeyInfo();
+console.log('Session key:', info.address);        // Your signing key
+console.log('Spending from:', info.walletAddress); // Human's wallet (funding source)
+console.log('Budget remaining:', info.limits.totalUsd);
+```
+
+This is important: your session key authorizes spending from the **human's wallet**, not your own external wallet. The human controls the budget and can revoke access at any time.
+
 ## Important: Session Key Security
 
 Your session key (`sk_live_...`) is a **private key**. Treat it like a password:
 
-- **Save it immediately** when you receive it (from `claimInvite()` or dashboard)
+- **Save it immediately** when you receive it (from `claimInvite()`)
 - **Store it securely** (environment variable, secrets manager)
 - **Never commit it** to version control
 - **Never log it** to console or files
-- **It cannot be recovered** if lost - you will need a new invite
+- **It cannot be recovered** if lost - you will need a new Access Code
 
 The session key is shown **only once** when claimed. MixrPay does not store it.
 
@@ -39,8 +95,6 @@ const response = await wallet.callMerchantApi({
 const data = await response.json();
 ```
 
-Get session keys at [mixrpay.com/wallet/sessions](https://www.mixrpay.com/wallet/sessions).
-
 ## Core Methods
 
 ```typescript

package/dist/index.cjs

@@ -532,7 +532,7 @@ function getAmountUsd(requirements) {
 }
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.8.5";
+var SDK_VERSION = "0.8.7";
 var DEFAULT_BASE_URL = process.env.MIXRPAY_BASE_URL || "https://www.mixrpay.com";
 var DEFAULT_TIMEOUT = 3e4;
 var NETWORKS = {
@@ -1707,6 +1707,7 @@ var AgentWallet = class {
         const data = await response.json();
         this.sessionKeyInfo = {
           address: this.sessionKey.address,
+          walletAddress: data.wallet_address ?? data.walletAddress ?? null,
           isValid: data.is_valid ?? data.isValid ?? true,
           limits: {
             perTxUsd: data.per_tx_limit_usd ?? data.perTxLimitUsd ?? null,
@@ -1731,6 +1732,7 @@ var AgentWallet = class {
     }
     return {
       address: this.sessionKey.address,
+      walletAddress: null,
       isValid: true,
       limits: { perTxUsd: null, dailyUsd: null, totalUsd: null },
       usage: { todayUsd: this.totalSpentUsd, totalUsd: this.totalSpentUsd, txCount: this.payments.length },
@@ -2829,6 +2831,399 @@ Timestamp: ${timestamp}`;
     };
   }
   // ===========================================================================
+  // JIT Task Agent Methods
+  // ===========================================================================
+  /**
+   * 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);
+   * ```
+   */
+  async deployTaskAgent(options) {
+    this.logger.debug("deployTaskAgent", { name: options.name, budgetUsd: options.budgetUsd });
+    const authHeaders = await this.getSessionAuthHeaders();
+    const response = await fetch(`${this.baseUrl}/api/v2/jit-task/deploy`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...authHeaders
+      },
+      body: JSON.stringify({
+        name: options.name,
+        prompt: options.prompt,
+        system_prompt: options.systemPrompt,
+        model: options.model || "claude-sonnet-4-5",
+        tools: options.tools || [],
+        budget_usd: options.budgetUsd,
+        ttl_hours: options.ttlHours || 24,
+        max_iterations: options.maxIterations || 10,
+        plan_id: options.planId,
+        task_id: options.taskId,
+        idempotency_key: options.idempotencyKey,
+        auto_run: options.autoRun || false
+      })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Task agent deploy failed: ${response.status}`);
+    }
+    const data = await response.json();
+    return {
+      instance: this.parseTaskAgentInstance(data.instance),
+      idempotent: data.idempotent || false,
+      requestId: data.request_id
+    };
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getTaskAgentStatus(instanceId) {
+    this.logger.debug("getTaskAgentStatus", { instanceId });
+    const authHeaders = await this.getSessionAuthHeaders();
+    const response = await fetch(`${this.baseUrl}/api/v2/jit-task/${instanceId}`, {
+      method: "GET",
+      headers: authHeaders
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to get task status: ${response.status}`);
+    }
+    const data = await response.json();
+    return this.parseTaskAgentStatus(data);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async triggerTaskAgent(instanceId) {
+    this.logger.debug("triggerTaskAgent", { instanceId });
+    const authHeaders = await this.getSessionAuthHeaders();
+    const response = await fetch(`${this.baseUrl}/api/v2/jit-task/${instanceId}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...authHeaders
+      }
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to trigger task: ${response.status}`);
+    }
+    const data = await response.json();
+    return {
+      success: data.success,
+      status: data.status
+    };
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async cancelTaskAgent(instanceId) {
+    this.logger.debug("cancelTaskAgent", { instanceId });
+    const authHeaders = await this.getSessionAuthHeaders();
+    const response = await fetch(`${this.baseUrl}/api/v2/jit-task/${instanceId}`, {
+      method: "DELETE",
+      headers: authHeaders
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to cancel task: ${response.status}`);
+    }
+    const data = await response.json();
+    return {
+      success: data.success,
+      status: data.status
+    };
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async listTaskAgents(options) {
+    this.logger.debug("listTaskAgents", { options });
+    const authHeaders = await this.getSessionAuthHeaders();
+    const searchParams = new URLSearchParams();
+    if (options?.status) searchParams.set("status", options.status);
+    if (options?.planId) searchParams.set("plan_id", options.planId);
+    if (options?.taskId) searchParams.set("task_id", options.taskId);
+    if (options?.limit !== void 0) searchParams.set("limit", String(options.limit));
+    if (options?.offset !== void 0) searchParams.set("offset", String(options.offset));
+    const qs = searchParams.toString();
+    const url = `${this.baseUrl}/api/v2/jit-task${qs ? `?${qs}` : ""}`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: authHeaders
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to list task agents: ${response.status}`);
+    }
+    const data = await response.json();
+    return {
+      taskAgents: (data.task_agents || []).map((agent) => {
+        const budget = agent.budget;
+        const iterations = agent.iterations;
+        const usage = agent.usage;
+        const plan = agent.plan;
+        const task = agent.task;
+        return {
+          id: agent.id,
+          name: agent.name,
+          prompt: agent.prompt,
+          model: agent.model,
+          tools: agent.tools,
+          status: agent.status,
+          budget: {
+            totalUsd: budget.total_usd,
+            spentUsd: budget.spent_usd,
+            remainingUsd: budget.remaining_usd
+          },
+          iterations: {
+            current: iterations.current,
+            max: iterations.max
+          },
+          usage: {
+            toolCalls: usage.tool_calls,
+            inputTokens: usage.input_tokens,
+            outputTokens: usage.output_tokens
+          },
+          result: agent.result,
+          error: agent.error,
+          depth: agent.depth,
+          plan: plan ? { id: plan.id, title: plan.title } : null,
+          task: task ? { id: task.id, title: task.title } : null,
+          ttlHours: agent.ttl_hours,
+          expiresAt: new Date(agent.expires_at),
+          createdAt: new Date(agent.created_at),
+          startedAt: agent.started_at ? new Date(agent.started_at) : void 0,
+          completedAt: agent.completed_at ? new Date(agent.completed_at) : void 0
+        };
+      }),
+      pagination: {
+        total: data.pagination.total,
+        limit: data.pagination.limit,
+        offset: data.pagination.offset,
+        hasMore: data.pagination.has_more
+      },
+      stats: {
+        active: data.stats.active ?? 0,
+        completed: data.stats.completed ?? 0,
+        failed: data.stats.failed ?? 0,
+        totalSpentUsd: data.stats.total_spent_usd ?? 0
+      }
+    };
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async waitForTaskAgent(instanceId, options) {
+    const pollIntervalMs = options?.pollIntervalMs || 2e3;
+    const timeoutMs = options?.timeoutMs || 3e5;
+    const startTime = Date.now();
+    this.logger.debug("waitForTaskAgent", { instanceId, pollIntervalMs, timeoutMs });
+    while (true) {
+      const status = await this.getTaskAgentStatus(instanceId);
+      if (["completed", "failed", "cancelled", "budget_exceeded", "expired"].includes(status.status)) {
+        return {
+          id: status.id,
+          status: status.status,
+          result: status.result,
+          error: status.error,
+          spentUsd: status.budget.spentUsd,
+          iterations: status.iterations.current,
+          toolCalls: status.usage.toolCalls,
+          completedAt: status.completedAt
+        };
+      }
+      if (Date.now() - startTime > timeoutMs) {
+        throw new MixrPayError(`Task agent wait timeout after ${timeoutMs}ms`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+  }
+  /**
+   * Parse task agent instance from API response.
+   */
+  parseTaskAgentInstance(data) {
+    return {
+      id: data.id,
+      name: data.name,
+      endpointUrl: data.endpoint_url,
+      statusUrl: data.status_url,
+      triggerUrl: data.trigger_url,
+      cancelUrl: data.cancel_url,
+      resultUrl: data.result_url,
+      status: data.status,
+      budgetUsd: data.budget_usd,
+      expiresAt: new Date(data.expires_at),
+      depth: data.depth,
+      maxIterations: data.max_iterations
+    };
+  }
+  /**
+   * Parse task agent status from API response.
+   */
+  parseTaskAgentStatus(data) {
+    const budget = data.budget;
+    const iterations = data.iterations;
+    const usage = data.usage;
+    const endpoints = data.endpoints;
+    return {
+      id: data.id,
+      name: data.name,
+      prompt: data.prompt,
+      model: data.model,
+      tools: data.tools,
+      status: data.status,
+      budget: {
+        totalUsd: budget?.total_usd ?? 0,
+        spentUsd: budget?.spent_usd ?? 0,
+        remainingUsd: budget?.remaining_usd ?? 0
+      },
+      iterations: {
+        current: iterations?.current ?? 0,
+        max: iterations?.max ?? 0
+      },
+      usage: {
+        toolCalls: usage?.tool_calls ?? 0,
+        inputTokens: usage?.input_tokens ?? 0,
+        outputTokens: usage?.output_tokens ?? 0
+      },
+      result: data.result,
+      error: data.error,
+      depth: data.depth,
+      planId: data.plan_id,
+      taskId: data.task_id,
+      endpoints: {
+        statusUrl: endpoints?.status_url ?? "",
+        triggerUrl: endpoints?.trigger_url ?? "",
+        cancelUrl: endpoints?.cancel_url ?? "",
+        resultUrl: endpoints?.result_url ?? ""
+      },
+      ttlHours: data.ttl_hours,
+      expiresAt: new Date(data.expires_at),
+      createdAt: new Date(data.created_at),
+      startedAt: data.started_at ? new Date(data.started_at) : void 0,
+      completedAt: data.completed_at ? new Date(data.completed_at) : void 0
+    };
+  }
+  // ===========================================================================
   // LLM Completion Methods
   // ===========================================================================
   /**