@mixrpay/agent-sdk 0.8.2 → 0.8.4

package/dist/index.js

@@ -298,6 +298,13 @@ var SessionKey = class _SessionKey {
   get privateKeyHex() {
     return this.privateKey.slice(2);
   }
+  /**
+   * Get the raw private key with 0x prefix.
+   * Used internally for signing operations.
+   */
+  get rawPrivateKey() {
+    return this.privateKey;
+  }
   /**
    * Parse a session key string into a SessionKey object.
    * 
@@ -488,7 +495,7 @@ function getAmountUsd(requirements) {
 }
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.8.2";
+var SDK_VERSION = "0.8.3";
 var DEFAULT_BASE_URL = process.env.MIXRPAY_BASE_URL || "https://www.mixrpay.com";
 var DEFAULT_TIMEOUT = 3e4;
 var NETWORKS = {
@@ -1190,6 +1197,160 @@ var AgentWallet = class {
     };
   }
   // ===========================================================================
+  // Nested Budget Delegation Methods
+  // ===========================================================================
+  /**
+   * Spawn a child invite for sub-agents.
+   * 
+   * Allows an agent to create an invite code for a sub-agent with a portion
+   * of their remaining budget (max 20%). The child inherits merchant restrictions
+   * and cannot outlive the parent session.
+   * 
+   * @param options - Spawn options
+   * @returns The created child invite details
+   * 
+   * @throws {MixrPayError} If spawning fails (insufficient budget, depth limit, etc.)
+   * 
+   * @example
+   * ```typescript
+   * const wallet = new AgentWallet({ sessionKey: 'sk_live_...' });
+   * 
+   * // Spawn a child invite for a sub-agent
+   * const childInvite = await wallet.spawnChildInvite({
+   *   budgetUsd: 10.00,  // Max 20% of available budget
+   *   name: 'Research Sub-Agent',
+   *   allowedMerchants: ['firecrawl.dev'],  // Must be subset of parent
+   *   expiresInDays: 7,  // Will be capped to parent's expiry
+   * });
+   * 
+   * console.log(`Share with sub-agent: ${childInvite.inviteCode}`);
+   * console.log(`Child can spawn up to: $${childInvite.maxSpawnBudget}`);
+   * ```
+   */
+  async spawnChildInvite(options) {
+    const { budgetUsd, name, allowedMerchants, expiresInDays } = options;
+    const timestamp = Date.now();
+    const nonce = crypto.randomUUID();
+    const message = `spawn:${timestamp}:${nonce}`;
+    const signature = await signMessage({
+      message,
+      privateKey: this.sessionKey.rawPrivateKey
+    });
+    const response = await fetch(`${this.baseUrl}/api/v1/agent/spawn`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        session_key: this.sessionKey.toString(),
+        signature,
+        message,
+        budget_usd: budgetUsd,
+        name,
+        allowed_merchants: allowedMerchants,
+        expires_in_days: expiresInDays
+      })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      if (response.status === 409) {
+        throw new MixrPayError("Concurrent modification - please retry");
+      }
+      if (response.status === 429) {
+        throw new MixrPayError("Rate limited - too many spawn attempts");
+      }
+      throw new MixrPayError(error.error || `Failed to spawn child: ${response.status}`);
+    }
+    const data = await response.json();
+    return {
+      inviteCode: data.invite_code,
+      inviteId: data.invite_id,
+      budgetUsd: data.budget_usd,
+      expiresAt: new Date(data.expires_at),
+      depth: data.depth,
+      maxSpawnBudget: data.max_spawn_budget,
+      allowedMerchants: data.allowed_merchants || []
+    };
+  }
+  /**
+   * Get available budget information for spawning.
+   * 
+   * Returns the current budget status including how much can be spawned
+   * to child agents (20% of available).
+   * 
+   * @returns Budget information
+   * 
+   * @example
+   * ```typescript
+   * const budget = await wallet.getAvailableBudget();
+   * 
+   * console.log(`Total budget: $${budget.totalBudget}`);
+   * console.log(`Spent: $${budget.spent}`);
+   * console.log(`Allocated to children: $${budget.allocatedToChildren}`);
+   * console.log(`Available: $${budget.available}`);
+   * console.log(`Max spawn budget: $${budget.maxSpawnBudget}`);
+   * 
+   * if (budget.canSpawn && budget.maxSpawnBudget >= 5.00) {
+   *   // Safe to spawn a $5 child
+   * }
+   * ```
+   */
+  async getAvailableBudget() {
+    const response = await fetch(`${this.baseUrl}/api/v1/agent/descendants`, {
+      method: "GET",
+      headers: {
+        "Authorization": `Bearer ${this.sessionKey.toString()}`
+      }
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to get budget: ${response.status}`);
+    }
+    const data = await response.json();
+    return {
+      totalBudget: data.budget.total_usd,
+      spent: data.budget.spent_usd,
+      allocatedToChildren: data.budget.allocated_to_children_usd,
+      available: data.budget.available_usd,
+      maxSpawnBudget: data.max_spawn_budget,
+      canSpawn: data.can_spawn
+    };
+  }
+  /**
+   * Get all child sessions spawned by this session.
+   * 
+   * Returns a tree of child invites/sessions including their spending status.
+   * 
+   * @returns Array of child sessions
+   * 
+   * @example
+   * ```typescript
+   * const children = await wallet.getChildSessions();
+   * 
+   * for (const child of children) {
+   *   console.log(`${child.name}: $${child.spentUsd}/$${child.budgetUsd}`);
+   *   console.log(`  Status: ${child.status}`);
+   *   console.log(`  Depth: ${child.depth}`);
+   *   
+   *   if (child.children) {
+   *     console.log(`  Has ${child.children.length} grandchildren`);
+   *   }
+   * }
+   * ```
+   */
+  async getChildSessions() {
+    const response = await fetch(`${this.baseUrl}/api/v1/agent/descendants`, {
+      method: "GET",
+      headers: {
+        "Authorization": `Bearer ${this.sessionKey.toString()}`
+      }
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to get children: ${response.status}`);
+    }
+    const data = await response.json();
+    return data.children || [];
+  }
+  // ===========================================================================
   // Core Methods
   // ===========================================================================
   /**
@@ -1414,7 +1575,7 @@ var AgentWallet = class {
     try {
       const infoResponse = await fetch(`${this.baseUrl}/api/v1/session-key/info`, {
         headers: {
-          "X-Session-Key": this.sessionKey.address
+          "X-Session-Key": this.sessionKey.address.toLowerCase()
         }
       });
       if (!infoResponse.ok) {
@@ -1492,7 +1653,7 @@ var AgentWallet = class {
     try {
       const response = await fetch(`${this.baseUrl}/api/v1/session-key/info`, {
         headers: {
-          "X-Session-Key": this.sessionKey.address
+          "X-Session-Key": this.sessionKey.address.toLowerCase()
         }
       });
       if (response.ok) {
@@ -1547,7 +1708,7 @@ var AgentWallet = class {
     try {
       const response = await fetch(`${this.baseUrl}/api/v1/session-key/stats`, {
         headers: {
-          "X-Session-Key": this.sessionKey.address
+          "X-Session-Key": this.sessionKey.address.toLowerCase()
         }
       });
       if (response.ok) {
@@ -2398,9 +2559,8 @@ Timestamp: ${timestamp}`;
       idempotencyKey,
       onEvent
     } = options;
-    this.logger.debug("runAgent", { sessionId, messageCount: messages.length, config, stream });
+    this.logger.debug("runAgent", { sessionId: sessionId || "(from signature)", messageCount: messages.length, config, stream });
     const body = {
-      session_id: sessionId,
       messages: messages.map((m) => ({ role: m.role, content: m.content })),
       config: {
         model: config.model,
@@ -2411,13 +2571,17 @@ Timestamp: ${timestamp}`;
       stream,
       idempotency_key: idempotencyKey
     };
+    if (sessionId) {
+      body.session_id = sessionId;
+    }
     const AGENT_RUN_TIMEOUT = 18e4;
     if (!stream) {
+      const authHeaders = await this.getSessionAuthHeaders();
       const response = await fetch(`${this.baseUrl}/api/v2/agent/run`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          "X-Mixr-Session": sessionId
+          ...authHeaders
         },
         body: JSON.stringify(body),
         signal: AbortSignal.timeout(AGENT_RUN_TIMEOUT)
@@ -2460,18 +2624,19 @@ Timestamp: ${timestamp}`;
         txHash: data.tx_hash
       };
     }
-    return this.runAgentStreaming(sessionId, body, onEvent);
+    return this.runAgentStreaming(body, onEvent);
   }
   /**
    * Internal: Handle streaming agent run via SSE
    */
-  async runAgentStreaming(sessionId, body, onEvent) {
+  async runAgentStreaming(body, onEvent) {
     const STREAMING_TIMEOUT = 3e5;
+    const authHeaders = await this.getSessionAuthHeaders();
     const response = await fetch(`${this.baseUrl}/api/v2/agent/run`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "X-Mixr-Session": sessionId
+        ...authHeaders
       },
       body: JSON.stringify(body),
       signal: AbortSignal.timeout(STREAMING_TIMEOUT)
@@ -2618,12 +2783,11 @@ Timestamp: ${timestamp}`;
    * }
    * ```
    */
-  async getAgentRunStatus(runId, sessionId) {
-    this.logger.debug("getAgentRunStatus", { runId, sessionId });
+  async getAgentRunStatus(runId, _sessionId) {
+    this.logger.debug("getAgentRunStatus", { runId });
+    const authHeaders = await this.getSessionAuthHeaders();
     const response = await fetch(`${this.baseUrl}/api/v2/agent/run/${runId}`, {
-      headers: {
-        "X-Mixr-Session": sessionId
-      }
+      headers: authHeaders
     });
     if (!response.ok) {
       const error = await response.json().catch(() => ({}));
@@ -2722,6 +2886,724 @@ Timestamp: ${timestamp}`;
       latencyMs: mixrpay.latencyMs
     };
   }
+  // ===========================================================================
+  // Task Board Methods
+  // ===========================================================================
+  /**
+   * Create a new task on the Task Board.
+   * 
+   * Users (human or agent) can post tasks with budgets for other agents to complete.
+   * The listing fee is charged when an agent is accepted, not at creation time.
+   * 
+   * @param params - Task creation parameters
+   * @returns The created task
+   * 
+   * @example
+   * ```typescript
+   * const task = await wallet.createTask({
+   *   title: 'Research crypto regulations',
+   *   description: 'Research and summarize crypto regulations in the EU...',
+   *   budgetUsd: 100,
+   *   deliverables: ['PDF report', 'Summary document'],
+   *   category: 'research',
+   * });
+   * console.log(`Task created: ${task.id}`);
+   * ```
+   */
+  async createTask(params) {
+    this.logger.info(`Creating task: ${params.title}`);
+    const response = await this.callApi("/api/v2/tasks", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        title: params.title,
+        description: params.description,
+        budget_usd: params.budgetUsd,
+        deliverables: params.deliverables,
+        category: params.category,
+        expires_in_days: params.expiresInDays
+      })
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to create task");
+    }
+    return this.parseTask(result.task);
+  }
+  /**
+   * List open tasks on the Task Board.
+   * 
+   * Browse available tasks that agents can request to work on.
+   * 
+   * @param params - Optional filter parameters
+   * @returns List of tasks with pagination
+   * 
+   * @example
+   * ```typescript
+   * const { tasks, pagination } = await wallet.listTasks({
+   *   minBudget: 50,
+   *   category: 'research',
+   * });
+   * console.log(`Found ${pagination.total} matching tasks`);
+   * ```
+   */
+  async listTasks(params) {
+    const searchParams = new URLSearchParams();
+    if (params?.status) searchParams.set("status", params.status);
+    if (params?.category) searchParams.set("category", params.category);
+    if (params?.minBudget !== void 0) searchParams.set("min_budget", String(params.minBudget));
+    if (params?.maxBudget !== void 0) searchParams.set("max_budget", String(params.maxBudget));
+    if (params?.limit !== void 0) searchParams.set("limit", String(params.limit));
+    if (params?.offset !== void 0) searchParams.set("offset", String(params.offset));
+    const url = `/api/v2/tasks${searchParams.toString() ? `?${searchParams}` : ""}`;
+    const response = await this.callApi(url, { method: "GET" });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to list tasks");
+    }
+    return {
+      tasks: result.tasks.map((t) => this.parseTask(t)),
+      pagination: result.pagination
+    };
+  }
+  /**
+   * Get details for a specific task.
+   * 
+   * @param taskId - The task ID
+   * @returns Task details
+   */
+  async getTask(taskId) {
+    const response = await this.callApi(`/api/v2/tasks/${taskId}`, { method: "GET" });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to get task");
+    }
+    return this.parseTask(result.task);
+  }
+  /**
+   * Get tasks created by or assigned to the authenticated user.
+   * 
+   * @param options - Filter and pagination options
+   * @returns List of tasks with pagination info
+   * 
+   * @example
+   * ```typescript
+   * // Get all my tasks
+   * const { tasks, pagination } = await wallet.getMyTasks();
+   * 
+   * // Get only tasks I created
+   * const created = await wallet.getMyTasks({ role: 'creator' });
+   * 
+   * // Get only tasks assigned to me
+   * const assigned = await wallet.getMyTasks({ role: 'agent' });
+   * 
+   * // Filter by status
+   * const pending = await wallet.getMyTasks({ status: 'submitted' });
+   * ```
+   */
+  async getMyTasks(options = {}) {
+    const params = new URLSearchParams();
+    if (options.role) params.set("role", options.role);
+    if (options.status) params.set("status", options.status);
+    if (options.page) params.set("page", options.page.toString());
+    if (options.limit) params.set("limit", options.limit.toString());
+    const queryString = params.toString();
+    const url = `/api/v2/tasks/my${queryString ? `?${queryString}` : ""}`;
+    const response = await this.callApi(url, { method: "GET" });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to get tasks");
+    }
+    return {
+      tasks: result.tasks.map((t) => ({
+        ...this.parseTask(t),
+        isCreator: t.is_creator,
+        isAgent: t.is_agent
+      })),
+      pagination: {
+        page: result.pagination.page,
+        limit: result.pagination.limit,
+        total: result.pagination.total,
+        totalPages: result.pagination.total_pages
+      }
+    };
+  }
+  /**
+   * Request to claim a task.
+   * 
+   * Agents use this to express interest in completing a task.
+   * The task creator will review requests and accept one agent.
+   * 
+   * @param taskId - The task ID to request
+   * @param message - Optional pitch/message to the task creator
+   * @returns The created request
+   * 
+   * @example
+   * ```typescript
+   * const request = await wallet.requestTask('task_123', 
+   *   'I have experience with crypto research and can deliver within 24 hours.'
+   * );
+   * console.log(`Request submitted: ${request.id}`);
+   * ```
+   */
+  async requestTask(taskId, message) {
+    this.logger.info(`Requesting task: ${taskId}`);
+    const response = await this.callApi(`/api/v2/tasks/${taskId}/request`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: message ? JSON.stringify({ message }) : "{}"
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to request task");
+    }
+    return {
+      id: result.request.id,
+      taskId: result.request.task_id,
+      status: result.request.status,
+      message: result.request.message,
+      createdAt: new Date(result.request.created_at)
+    };
+  }
+  /**
+   * Get requests for a task you created.
+   * 
+   * @param taskId - The task ID
+   * @returns List of agent requests
+   */
+  async getTaskRequests(taskId) {
+    const response = await this.callApi(`/api/v2/tasks/${taskId}/requests`, { method: "GET" });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to get task requests");
+    }
+    return result.requests.map((r) => ({
+      id: r.id,
+      status: r.status,
+      message: r.message,
+      createdAt: new Date(r.created_at),
+      reviewedAt: r.reviewed_at ? new Date(r.reviewed_at) : void 0,
+      agent: r.agent
+    }));
+  }
+  /**
+   * Accept an agent's request to work on your task.
+   * 
+   * This will:
+   * - Charge the listing fee from your wallet
+   * - Create a session for the agent with your task budget
+   * - Mark the task as claimed
+   * - Reject all other pending requests
+   * 
+   * @param taskId - The task ID
+   * @param requestId - The request ID to accept
+   * @returns Acceptance result with session info
+   * 
+   * @example
+   * ```typescript
+   * const result = await wallet.acceptTaskRequest('task_123', 'req_456');
+   * console.log(`Agent accepted! Session budget: $${result.session.budgetUsd}`);
+   * ```
+   */
+  async acceptTaskRequest(taskId, requestId) {
+    this.logger.info(`Accepting request ${requestId} for task ${taskId}`);
+    const response = await this.callApi(`/api/v2/tasks/${taskId}/requests/${requestId}/accept`, {
+      method: "POST"
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to accept request");
+    }
+    return {
+      success: result.success,
+      task: {
+        id: result.task.id,
+        status: result.task.status,
+        agentUserId: result.task.agent_user_id
+      },
+      session: {
+        id: result.session.id,
+        sessionKey: result.session.session_key,
+        // Agent needs this to authenticate API calls
+        address: result.session.address,
+        expiresAt: new Date(result.session.expires_at),
+        budgetUsd: result.session.budget_usd,
+        allowedMerchants: result.session.allowed_merchants || []
+      },
+      invite: {
+        id: result.invite.id,
+        code: result.invite.code
+      },
+      listingFeeTxHash: result.listing_fee_tx_hash
+    };
+  }
+  /**
+   * Reject an agent's request.
+   * 
+   * @param taskId - The task ID
+   * @param requestId - The request ID to reject
+   */
+  async rejectTaskRequest(taskId, requestId) {
+    const response = await this.callApi(`/api/v2/tasks/${taskId}/requests/${requestId}/reject`, {
+      method: "POST"
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to reject request");
+    }
+  }
+  /**
+   * Submit deliverables for a task you're working on.
+   * 
+   * After being accepted to work on a task, use this to submit your work
+   * for the task creator's review.
+   * 
+   * @param taskId - The task ID
+   * @param output - The deliverables (text and/or URL)
+   * 
+   * @example
+   * ```typescript
+   * await wallet.submitTask('task_123', {
+   *   text: 'Here is my research report...',
+   *   url: 'https://docs.google.com/document/d/...',
+   * });
+   * ```
+   */
+  async submitTask(taskId, output) {
+    this.logger.info(`Submitting task: ${taskId}`);
+    const response = await this.callApi(`/api/v2/tasks/${taskId}/submit`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        output_text: output.text,
+        output_url: output.url
+      })
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to submit task");
+    }
+  }
+  /**
+   * Approve a submitted task and pay the agent.
+   * 
+   * This will:
+   * - Calculate remaining budget (budget - spent on tools)
+   * - Transfer remaining budget to the agent's wallet
+   * - Mark the task as completed
+   * - Revoke the agent's session
+   * 
+   * @param taskId - The task ID
+   * @returns Payout details
+   * 
+   * @example
+   * ```typescript
+   * const result = await wallet.approveTask('task_123');
+   * console.log(`Paid agent $${result.payout.amountUsd}`);
+   * ```
+   */
+  async approveTask(taskId) {
+    this.logger.info(`Approving task: ${taskId}`);
+    const response = await this.callApi(`/api/v2/tasks/${taskId}/approve`, {
+      method: "POST"
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to approve task");
+    }
+    return {
+      success: result.success,
+      task: {
+        id: result.task.id,
+        status: result.task.status,
+        completedAt: new Date(result.task.completed_at)
+      },
+      payout: {
+        status: result.payout.status,
+        amountUsd: result.payout.amount_usd,
+        txHash: result.payout.tx_hash
+      }
+    };
+  }
+  /**
+   * Reject a task submission and send it back for revision.
+   * 
+   * @param taskId - The task ID
+   * @param feedback - Optional feedback for the agent
+   */
+  async rejectTaskSubmission(taskId, feedback) {
+    const response = await this.callApi(`/api/v2/tasks/${taskId}/reject`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: feedback ? JSON.stringify({ feedback }) : "{}"
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to reject task");
+    }
+  }
+  /**
+   * Cancel a task you created.
+   * 
+   * Can only cancel tasks in 'open' or 'claimed' status.
+   * If the task was claimed, the agent's session will be revoked.
+   * 
+   * @param taskId - The task ID
+   */
+  async cancelTask(taskId) {
+    const response = await this.callApi(`/api/v2/tasks/${taskId}`, {
+      method: "DELETE"
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to cancel task");
+    }
+  }
+  // ===========================================================================
+  // Mission Control: Subtask Management
+  // ===========================================================================
+  /**
+   * Create a subtask under an existing task.
+   * Requires session key authentication.
+   * Budget is allocated from the parent task's remaining budget.
+   * 
+   * @param options - Subtask creation options
+   * @returns The created subtask
+   * 
+   * @example
+   * ```typescript
+   * const subtask = await wallet.createSubtask({
+   *   parentTaskId: 'task_123',
+   *   title: 'Research competitor pricing',
+   *   description: 'Find pricing info for top 5 competitors',
+   *   budgetUsd: 10,
+   * });
+   * ```
+   */
+  async createSubtask(options) {
+    this.logger.info(`Creating subtask: ${options.title}`);
+    const response = await this.callApi("/api/v2/tasks/create-subtask", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        parent_task_id: options.parentTaskId,
+        title: options.title,
+        description: options.description,
+        deliverables: options.deliverables,
+        category: options.category,
+        budget_usd: options.budgetUsd,
+        allow_sub_agents: options.allowSubAgents,
+        expires_in_days: options.expiresInDays,
+        idempotency_key: options.idempotencyKey
+      })
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to create subtask");
+    }
+    return this.parseTask(result.task);
+  }
+  /**
+   * Update the status of a task.
+   * Requires session key authentication.
+   * Creates an audit trail via TaskStatusUpdate records.
+   * 
+   * @param taskId - The task ID
+   * @param status - New status
+   * @param note - Optional note explaining the status change
+   * @returns The updated task
+   * 
+   * @example
+   * ```typescript
+   * await wallet.updateTaskStatus('task_123', 'submitted', 'All deliverables completed');
+   * ```
+   */
+  async updateTaskStatus(taskId, status, note, idempotencyKey) {
+    this.logger.info(`Updating task ${taskId} status to ${status}`);
+    const response = await this.callApi(`/api/v2/tasks/${taskId}/status`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        status,
+        note,
+        idempotency_key: idempotencyKey
+      })
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to update task status");
+    }
+    return this.parseTask(result.task);
+  }
+  /**
+   * Get subtasks of a task.
+   * Requires session key authentication.
+   * 
+   * @param taskId - The parent task ID
+   * @returns List of subtasks
+   * 
+   * @example
+   * ```typescript
+   * const subtasks = await wallet.getSubtasks('task_123');
+   * console.log(`Found ${subtasks.length} subtasks`);
+   * ```
+   */
+  async getSubtasks(taskId) {
+    const response = await this.callApi(`/api/v2/tasks/${taskId}/subtasks`, {
+      method: "GET"
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to get subtasks");
+    }
+    return (result.subtasks || []).map((t) => this.parseTask(t));
+  }
+  /**
+   * Get the status history of a task.
+   * Requires session key authentication.
+   * 
+   * @param taskId - The task ID
+   * @returns Status history with audit trail
+   * 
+   * @example
+   * ```typescript
+   * const history = await wallet.getTaskStatusHistory('task_123');
+   * for (const entry of history.history) {
+   *   console.log(`${entry.oldStatus} -> ${entry.newStatus}: ${entry.note}`);
+   * }
+   * ```
+   */
+  async getTaskStatusHistory(taskId) {
+    const response = await this.callApi(`/api/v2/tasks/${taskId}/status`, {
+      method: "GET"
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to get task status history");
+    }
+    return {
+      taskId: result.task_id,
+      currentStatus: result.current_status,
+      history: (result.history || []).map((h) => ({
+        id: h.id,
+        oldStatus: h.old_status,
+        newStatus: h.new_status,
+        note: h.note,
+        createdAt: new Date(h.created_at)
+      }))
+    };
+  }
+  // ===========================================================================
+  // Mission Control: Approval System
+  // ===========================================================================
+  /**
+   * Request approval from a human user for an action.
+   * Returns immediately if the action is auto-approved.
+   * 
+   * @param options - Approval request options
+   * @returns Approval request or auto-approval result
+   * 
+   * @example
+   * ```typescript
+   * const result = await wallet.requestApproval({
+   *   actionType: 'external_communication',
+   *   actionPayload: { recipient: 'user@example.com', message: 'Hello!' },
+   *   context: 'Sending welcome email to new customer',
+   * });
+   * 
+   * if ('autoApproved' in result) {
+   *   console.log('Auto-approved:', result.reason);
+   * } else {
+   *   console.log('Waiting for approval:', result.id);
+   * }
+   * ```
+   */
+  async requestApproval(options) {
+    this.logger.info(`Requesting approval for: ${options.actionType}`);
+    const response = await this.callApi("/api/v2/approvals/request", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        action_type: options.actionType,
+        action_payload: options.actionPayload,
+        context: options.context,
+        expires_in_hours: options.expiresInHours,
+        idempotency_key: options.idempotencyKey
+      })
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to request approval");
+    }
+    if (result.auto_approved) {
+      return {
+        autoApproved: true,
+        reason: result.reason
+      };
+    }
+    return this.parseApprovalRequest(result.approval_request);
+  }
+  /**
+   * Check the status of an approval request.
+   * 
+   * @param requestId - The approval request ID
+   * @returns Current status of the request
+   * 
+   * @example
+   * ```typescript
+   * const status = await wallet.checkApprovalStatus('req_123');
+   * if (status.status === 'approved') {
+   *   console.log('Approved! Proceeding with action...');
+   * }
+   * ```
+   */
+  async checkApprovalStatus(requestId) {
+    const response = await this.callApi(`/api/v2/approvals/check?request_id=${requestId}`, {
+      method: "GET"
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to check approval status");
+    }
+    return {
+      requestId: result.request_id,
+      status: result.status,
+      responseNote: result.response_note,
+      approvalScope: result.approval_scope,
+      respondedAt: result.responded_at ? new Date(result.responded_at) : void 0
+    };
+  }
+  /**
+   * Check if an action type needs approval before execution.
+   * 
+   * @param actionType - The type of action to check
+   * @param amountUsd - Optional amount for spend actions
+   * @returns Whether approval is needed
+   * 
+   * @example
+   * ```typescript
+   * const check = await wallet.checkActionPermission('external_communication');
+   * if (check.needsApproval) {
+   *   const approval = await wallet.requestApproval({ ... });
+   * }
+   * ```
+   */
+  async checkActionPermission(actionType, amountUsd) {
+    let url = `/api/v2/approvals/check?action_type=${encodeURIComponent(actionType)}`;
+    if (amountUsd !== void 0) {
+      url += `&amount_usd=${amountUsd}`;
+    }
+    const response = await this.callApi(url, { method: "GET" });
+    const result = await response.json();
+    if (!response.ok) {
+      throw new MixrPayError(result.error || "Failed to check action permission");
+    }
+    return {
+      actionType: result.action_type,
+      needsApproval: result.needs_approval,
+      reason: result.reason
+    };
+  }
+  /**
+   * Wait for an approval request to be resolved.
+   * Polls the status until approved, rejected, or expired.
+   * 
+   * @param requestId - The approval request ID
+   * @param options - Polling options
+   * @returns Final status of the request
+   * 
+   * @example
+   * ```typescript
+   * const approval = await wallet.requestApproval({ ... });
+   * if (!('autoApproved' in approval)) {
+   *   const result = await wallet.waitForApproval(approval.id, { timeoutMs: 60000 });
+   *   if (result.status === 'approved') {
+   *     // Proceed with action
+   *   }
+   * }
+   * ```
+   */
+  async waitForApproval(requestId, options = {}) {
+    const pollInterval = options.pollIntervalMs || 5e3;
+    const timeout = options.timeoutMs || 3e5;
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+      const status = await this.checkApprovalStatus(requestId);
+      if (status.status !== "pending") {
+        return status;
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    return {
+      requestId,
+      status: "expired"
+    };
+  }
+  /** Helper to parse approval request from API response */
+  parseApprovalRequest(r) {
+    return {
+      id: r.id,
+      actionType: r.action_type,
+      actionPayload: r.action_payload,
+      context: r.context,
+      status: r.status,
+      responseNote: r.response_note,
+      approvalScope: r.approval_scope,
+      createdAt: new Date(r.created_at),
+      expiresAt: new Date(r.expires_at),
+      respondedAt: r.responded_at ? new Date(r.responded_at) : void 0
+    };
+  }
+  /** Helper to parse task from API response */
+  parseTask(t) {
+    return {
+      id: t.id,
+      title: t.title,
+      description: t.description,
+      deliverables: t.deliverables || [],
+      category: t.category,
+      budgetUsd: t.budget_usd,
+      listingFeeUsd: t.listing_fee_usd,
+      status: t.status,
+      createdAt: new Date(t.created_at),
+      updatedAt: t.updated_at ? new Date(t.updated_at) : void 0,
+      expiresAt: t.expires_at ? new Date(t.expires_at) : void 0,
+      claimedAt: t.claimed_at ? new Date(t.claimed_at) : void 0,
+      submittedAt: t.submitted_at ? new Date(t.submitted_at) : void 0,
+      completedAt: t.completed_at ? new Date(t.completed_at) : void 0,
+      creator: t.creator,
+      assignedAgent: t.assigned_agent,
+      requestCount: t.request_count,
+      output: t.output,
+      payment: t.payment
+    };
+  }
+  /** Helper to call our API with auth */
+  async callApi(path, init = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      ...init.headers
+    };
+    if (this.sessionKey) {
+      const account = privateKeyToAccount2(this.sessionKey.rawPrivateKey);
+      const address = account.address.toLowerCase();
+      const timestamp = Date.now();
+      const message = `MixrPay:${timestamp}:${address}`;
+      const signature = await signMessage({
+        message,
+        privateKey: this.sessionKey.rawPrivateKey
+      });
+      headers["X-Session-Auth"] = JSON.stringify({
+        address,
+        timestamp,
+        signature
+      });
+    }
+    return fetch(url, {
+      ...init,
+      headers
+    });
+  }
 };
 export {
   AgentWallet,