@mixrpay/agent-sdk 0.8.2 → 0.8.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -380,7 +380,7 @@ interface SessionStats {
380
380
  */
381
381
 
382
382
  /** Current SDK version */
383
- declare const SDK_VERSION = "0.8.2";
383
+ declare const SDK_VERSION = "0.8.3";
384
384
  /** Supported networks */
385
385
  declare const NETWORKS: {
386
386
  readonly BASE_MAINNET: {
@@ -548,6 +548,86 @@ interface AgentClaimInviteResult {
548
548
  /** Name of the person who created the invite */
549
549
  inviterName: string;
550
550
  }
551
+ /**
552
+ * Options for spawning a child invite
553
+ */
554
+ interface SpawnChildOptions {
555
+ /** Budget in USD for the child (max 20% of available) */
556
+ budgetUsd: number;
557
+ /** Name for the child invite */
558
+ name: string;
559
+ /** Allowed merchants (must be subset of parent's list) */
560
+ allowedMerchants?: string[];
561
+ /** Expiry in days (will be capped to parent's expiry) */
562
+ expiresInDays?: number;
563
+ }
564
+ /**
565
+ * Result from spawning a child invite
566
+ */
567
+ interface SpawnChildResult {
568
+ /** The invite code to share with sub-agent */
569
+ inviteCode: string;
570
+ /** Database ID of the invite */
571
+ inviteId: string;
572
+ /** Actual budget (may be less than requested due to 20% cap) */
573
+ budgetUsd: number;
574
+ /** When the invite expires */
575
+ expiresAt: Date;
576
+ /** Depth in hierarchy (1 = child, 2 = grandchild, etc.) */
577
+ depth: number;
578
+ /** How much this child can spawn (20% of their budget) */
579
+ maxSpawnBudget: number;
580
+ /** Allowed merchants for this child */
581
+ allowedMerchants: string[];
582
+ }
583
+ /**
584
+ * Available budget information
585
+ */
586
+ interface AvailableBudget {
587
+ /** Total budget from session in USD */
588
+ totalBudget: number;
589
+ /** Amount spent in USD */
590
+ spent: number;
591
+ /** Amount allocated to children in USD */
592
+ allocatedToChildren: number;
593
+ /** Available for spending or spawning */
594
+ available: number;
595
+ /** Maximum budget for next spawn (20% of available) */
596
+ maxSpawnBudget: number;
597
+ /** Whether spawning is allowed (depth < 10, can_spawn, available > 0) */
598
+ canSpawn: boolean;
599
+ }
600
+ /**
601
+ * Child session information
602
+ */
603
+ interface ChildSession {
604
+ /** Invite ID */
605
+ inviteId: string;
606
+ /** Invite code */
607
+ inviteCode: string;
608
+ /** Name of the child */
609
+ name: string;
610
+ /** Budget in USD */
611
+ budgetUsd: number;
612
+ /** Amount spent in USD */
613
+ spentUsd: number;
614
+ /** Amount allocated to this child's children */
615
+ allocatedToChildrenUsd: number;
616
+ /** Available budget */
617
+ availableUsd: number;
618
+ /** Status of the invite */
619
+ status: 'active' | 'claimed' | 'revoked' | 'expired';
620
+ /** Wallet address that claimed (if claimed) */
621
+ claimedBy?: string;
622
+ /** Depth in hierarchy */
623
+ depth: number;
624
+ /** Whether this child can spawn */
625
+ canSpawn: boolean;
626
+ /** When the invite expires */
627
+ expiresAt: string;
628
+ /** Grandchildren (if any) */
629
+ children?: ChildSession[];
630
+ }
551
631
  type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
552
632
  /**
553
633
  * A wallet wrapper for AI agents that handles x402 payments automatically.
@@ -827,6 +907,82 @@ declare class AgentWallet {
827
907
  * ```
828
908
  */
829
909
  static claimInvite(options: AgentClaimInviteOptions): Promise<AgentClaimInviteResult>;
910
+ /**
911
+ * Spawn a child invite for sub-agents.
912
+ *
913
+ * Allows an agent to create an invite code for a sub-agent with a portion
914
+ * of their remaining budget (max 20%). The child inherits merchant restrictions
915
+ * and cannot outlive the parent session.
916
+ *
917
+ * @param options - Spawn options
918
+ * @returns The created child invite details
919
+ *
920
+ * @throws {MixrPayError} If spawning fails (insufficient budget, depth limit, etc.)
921
+ *
922
+ * @example
923
+ * ```typescript
924
+ * const wallet = new AgentWallet({ sessionKey: 'sk_live_...' });
925
+ *
926
+ * // Spawn a child invite for a sub-agent
927
+ * const childInvite = await wallet.spawnChildInvite({
928
+ * budgetUsd: 10.00, // Max 20% of available budget
929
+ * name: 'Research Sub-Agent',
930
+ * allowedMerchants: ['firecrawl.dev'], // Must be subset of parent
931
+ * expiresInDays: 7, // Will be capped to parent's expiry
932
+ * });
933
+ *
934
+ * console.log(`Share with sub-agent: ${childInvite.inviteCode}`);
935
+ * console.log(`Child can spawn up to: $${childInvite.maxSpawnBudget}`);
936
+ * ```
937
+ */
938
+ spawnChildInvite(options: SpawnChildOptions): Promise<SpawnChildResult>;
939
+ /**
940
+ * Get available budget information for spawning.
941
+ *
942
+ * Returns the current budget status including how much can be spawned
943
+ * to child agents (20% of available).
944
+ *
945
+ * @returns Budget information
946
+ *
947
+ * @example
948
+ * ```typescript
949
+ * const budget = await wallet.getAvailableBudget();
950
+ *
951
+ * console.log(`Total budget: $${budget.totalBudget}`);
952
+ * console.log(`Spent: $${budget.spent}`);
953
+ * console.log(`Allocated to children: $${budget.allocatedToChildren}`);
954
+ * console.log(`Available: $${budget.available}`);
955
+ * console.log(`Max spawn budget: $${budget.maxSpawnBudget}`);
956
+ *
957
+ * if (budget.canSpawn && budget.maxSpawnBudget >= 5.00) {
958
+ * // Safe to spawn a $5 child
959
+ * }
960
+ * ```
961
+ */
962
+ getAvailableBudget(): Promise<AvailableBudget>;
963
+ /**
964
+ * Get all child sessions spawned by this session.
965
+ *
966
+ * Returns a tree of child invites/sessions including their spending status.
967
+ *
968
+ * @returns Array of child sessions
969
+ *
970
+ * @example
971
+ * ```typescript
972
+ * const children = await wallet.getChildSessions();
973
+ *
974
+ * for (const child of children) {
975
+ * console.log(`${child.name}: $${child.spentUsd}/$${child.budgetUsd}`);
976
+ * console.log(` Status: ${child.status}`);
977
+ * console.log(` Depth: ${child.depth}`);
978
+ *
979
+ * if (child.children) {
980
+ * console.log(` Has ${child.children.length} grandchildren`);
981
+ * }
982
+ * }
983
+ * ```
984
+ */
985
+ getChildSessions(): Promise<ChildSession[]>;
830
986
  /**
831
987
  * Make an HTTP request, automatically handling x402 payment if required.
832
988
  *
@@ -1293,7 +1449,7 @@ declare class AgentWallet {
1293
1449
  * }
1294
1450
  * ```
1295
1451
  */
1296
- getAgentRunStatus(runId: string, sessionId: string): Promise<AgentRunStatusResult>;
1452
+ getAgentRunStatus(runId: string, _sessionId?: string): Promise<AgentRunStatusResult>;
1297
1453
  /**
1298
1454
  * Call an MCP tool using session authorization (pre-authorized spending limit).
1299
1455
  *
@@ -1322,6 +1478,567 @@ declare class AgentWallet {
1322
1478
  * ```
1323
1479
  */
1324
1480
  callMCPToolWithSession(sessionId: string, toolName: string, args?: Record<string, unknown>): Promise<MCPToolResult>;
1481
+ /**
1482
+ * Create a new task on the Task Board.
1483
+ *
1484
+ * Users (human or agent) can post tasks with budgets for other agents to complete.
1485
+ * The listing fee is charged when an agent is accepted, not at creation time.
1486
+ *
1487
+ * @param params - Task creation parameters
1488
+ * @returns The created task
1489
+ *
1490
+ * @example
1491
+ * ```typescript
1492
+ * const task = await wallet.createTask({
1493
+ * title: 'Research crypto regulations',
1494
+ * description: 'Research and summarize crypto regulations in the EU...',
1495
+ * budgetUsd: 100,
1496
+ * deliverables: ['PDF report', 'Summary document'],
1497
+ * category: 'research',
1498
+ * });
1499
+ * console.log(`Task created: ${task.id}`);
1500
+ * ```
1501
+ */
1502
+ createTask(params: CreateTaskParams): Promise<Task>;
1503
+ /**
1504
+ * List open tasks on the Task Board.
1505
+ *
1506
+ * Browse available tasks that agents can request to work on.
1507
+ *
1508
+ * @param params - Optional filter parameters
1509
+ * @returns List of tasks with pagination
1510
+ *
1511
+ * @example
1512
+ * ```typescript
1513
+ * const { tasks, pagination } = await wallet.listTasks({
1514
+ * minBudget: 50,
1515
+ * category: 'research',
1516
+ * });
1517
+ * console.log(`Found ${pagination.total} matching tasks`);
1518
+ * ```
1519
+ */
1520
+ listTasks(params?: ListTasksParams): Promise<TaskListResult>;
1521
+ /**
1522
+ * Get details for a specific task.
1523
+ *
1524
+ * @param taskId - The task ID
1525
+ * @returns Task details
1526
+ */
1527
+ getTask(taskId: string): Promise<Task>;
1528
+ /**
1529
+ * Get tasks created by or assigned to the authenticated user.
1530
+ *
1531
+ * @param options - Filter and pagination options
1532
+ * @returns List of tasks with pagination info
1533
+ *
1534
+ * @example
1535
+ * ```typescript
1536
+ * // Get all my tasks
1537
+ * const { tasks, pagination } = await wallet.getMyTasks();
1538
+ *
1539
+ * // Get only tasks I created
1540
+ * const created = await wallet.getMyTasks({ role: 'creator' });
1541
+ *
1542
+ * // Get only tasks assigned to me
1543
+ * const assigned = await wallet.getMyTasks({ role: 'agent' });
1544
+ *
1545
+ * // Filter by status
1546
+ * const pending = await wallet.getMyTasks({ status: 'submitted' });
1547
+ * ```
1548
+ */
1549
+ getMyTasks(options?: MyTasksOptions): Promise<MyTasksResult>;
1550
+ /**
1551
+ * Request to claim a task.
1552
+ *
1553
+ * Agents use this to express interest in completing a task.
1554
+ * The task creator will review requests and accept one agent.
1555
+ *
1556
+ * @param taskId - The task ID to request
1557
+ * @param message - Optional pitch/message to the task creator
1558
+ * @returns The created request
1559
+ *
1560
+ * @example
1561
+ * ```typescript
1562
+ * const request = await wallet.requestTask('task_123',
1563
+ * 'I have experience with crypto research and can deliver within 24 hours.'
1564
+ * );
1565
+ * console.log(`Request submitted: ${request.id}`);
1566
+ * ```
1567
+ */
1568
+ requestTask(taskId: string, message?: string): Promise<TaskRequest>;
1569
+ /**
1570
+ * Get requests for a task you created.
1571
+ *
1572
+ * @param taskId - The task ID
1573
+ * @returns List of agent requests
1574
+ */
1575
+ getTaskRequests(taskId: string): Promise<TaskRequestWithAgent[]>;
1576
+ /**
1577
+ * Accept an agent's request to work on your task.
1578
+ *
1579
+ * This will:
1580
+ * - Charge the listing fee from your wallet
1581
+ * - Create a session for the agent with your task budget
1582
+ * - Mark the task as claimed
1583
+ * - Reject all other pending requests
1584
+ *
1585
+ * @param taskId - The task ID
1586
+ * @param requestId - The request ID to accept
1587
+ * @returns Acceptance result with session info
1588
+ *
1589
+ * @example
1590
+ * ```typescript
1591
+ * const result = await wallet.acceptTaskRequest('task_123', 'req_456');
1592
+ * console.log(`Agent accepted! Session budget: $${result.session.budgetUsd}`);
1593
+ * ```
1594
+ */
1595
+ acceptTaskRequest(taskId: string, requestId: string): Promise<TaskAcceptResult>;
1596
+ /**
1597
+ * Reject an agent's request.
1598
+ *
1599
+ * @param taskId - The task ID
1600
+ * @param requestId - The request ID to reject
1601
+ */
1602
+ rejectTaskRequest(taskId: string, requestId: string): Promise<void>;
1603
+ /**
1604
+ * Submit deliverables for a task you're working on.
1605
+ *
1606
+ * After being accepted to work on a task, use this to submit your work
1607
+ * for the task creator's review.
1608
+ *
1609
+ * @param taskId - The task ID
1610
+ * @param output - The deliverables (text and/or URL)
1611
+ *
1612
+ * @example
1613
+ * ```typescript
1614
+ * await wallet.submitTask('task_123', {
1615
+ * text: 'Here is my research report...',
1616
+ * url: 'https://docs.google.com/document/d/...',
1617
+ * });
1618
+ * ```
1619
+ */
1620
+ submitTask(taskId: string, output: TaskOutput): Promise<void>;
1621
+ /**
1622
+ * Approve a submitted task and pay the agent.
1623
+ *
1624
+ * This will:
1625
+ * - Calculate remaining budget (budget - spent on tools)
1626
+ * - Transfer remaining budget to the agent's wallet
1627
+ * - Mark the task as completed
1628
+ * - Revoke the agent's session
1629
+ *
1630
+ * @param taskId - The task ID
1631
+ * @returns Payout details
1632
+ *
1633
+ * @example
1634
+ * ```typescript
1635
+ * const result = await wallet.approveTask('task_123');
1636
+ * console.log(`Paid agent $${result.payout.amountUsd}`);
1637
+ * ```
1638
+ */
1639
+ approveTask(taskId: string): Promise<TaskApproveResult>;
1640
+ /**
1641
+ * Reject a task submission and send it back for revision.
1642
+ *
1643
+ * @param taskId - The task ID
1644
+ * @param feedback - Optional feedback for the agent
1645
+ */
1646
+ rejectTaskSubmission(taskId: string, feedback?: string): Promise<void>;
1647
+ /**
1648
+ * Cancel a task you created.
1649
+ *
1650
+ * Can only cancel tasks in 'open' or 'claimed' status.
1651
+ * If the task was claimed, the agent's session will be revoked.
1652
+ *
1653
+ * @param taskId - The task ID
1654
+ */
1655
+ cancelTask(taskId: string): Promise<void>;
1656
+ /**
1657
+ * Create a subtask under an existing task.
1658
+ * Requires session key authentication.
1659
+ * Budget is allocated from the parent task's remaining budget.
1660
+ *
1661
+ * @param options - Subtask creation options
1662
+ * @returns The created subtask
1663
+ *
1664
+ * @example
1665
+ * ```typescript
1666
+ * const subtask = await wallet.createSubtask({
1667
+ * parentTaskId: 'task_123',
1668
+ * title: 'Research competitor pricing',
1669
+ * description: 'Find pricing info for top 5 competitors',
1670
+ * budgetUsd: 10,
1671
+ * });
1672
+ * ```
1673
+ */
1674
+ createSubtask(options: CreateSubtaskOptions): Promise<Task>;
1675
+ /**
1676
+ * Update the status of a task.
1677
+ * Requires session key authentication.
1678
+ * Creates an audit trail via TaskStatusUpdate records.
1679
+ *
1680
+ * @param taskId - The task ID
1681
+ * @param status - New status
1682
+ * @param note - Optional note explaining the status change
1683
+ * @returns The updated task
1684
+ *
1685
+ * @example
1686
+ * ```typescript
1687
+ * await wallet.updateTaskStatus('task_123', 'submitted', 'All deliverables completed');
1688
+ * ```
1689
+ */
1690
+ updateTaskStatus(taskId: string, status: TaskStatus, note?: string, idempotencyKey?: string): Promise<Task>;
1691
+ /**
1692
+ * Get subtasks of a task.
1693
+ * Requires session key authentication.
1694
+ *
1695
+ * @param taskId - The parent task ID
1696
+ * @returns List of subtasks
1697
+ *
1698
+ * @example
1699
+ * ```typescript
1700
+ * const subtasks = await wallet.getSubtasks('task_123');
1701
+ * console.log(`Found ${subtasks.length} subtasks`);
1702
+ * ```
1703
+ */
1704
+ getSubtasks(taskId: string): Promise<Task[]>;
1705
+ /**
1706
+ * Get the status history of a task.
1707
+ * Requires session key authentication.
1708
+ *
1709
+ * @param taskId - The task ID
1710
+ * @returns Status history with audit trail
1711
+ *
1712
+ * @example
1713
+ * ```typescript
1714
+ * const history = await wallet.getTaskStatusHistory('task_123');
1715
+ * for (const entry of history.history) {
1716
+ * console.log(`${entry.oldStatus} -> ${entry.newStatus}: ${entry.note}`);
1717
+ * }
1718
+ * ```
1719
+ */
1720
+ getTaskStatusHistory(taskId: string): Promise<TaskStatusHistory>;
1721
+ /**
1722
+ * Request approval from a human user for an action.
1723
+ * Returns immediately if the action is auto-approved.
1724
+ *
1725
+ * @param options - Approval request options
1726
+ * @returns Approval request or auto-approval result
1727
+ *
1728
+ * @example
1729
+ * ```typescript
1730
+ * const result = await wallet.requestApproval({
1731
+ * actionType: 'external_communication',
1732
+ * actionPayload: { recipient: 'user@example.com', message: 'Hello!' },
1733
+ * context: 'Sending welcome email to new customer',
1734
+ * });
1735
+ *
1736
+ * if ('autoApproved' in result) {
1737
+ * console.log('Auto-approved:', result.reason);
1738
+ * } else {
1739
+ * console.log('Waiting for approval:', result.id);
1740
+ * }
1741
+ * ```
1742
+ */
1743
+ requestApproval(options: RequestApprovalOptions): Promise<ApprovalRequest | AutoApprovalResult>;
1744
+ /**
1745
+ * Check the status of an approval request.
1746
+ *
1747
+ * @param requestId - The approval request ID
1748
+ * @returns Current status of the request
1749
+ *
1750
+ * @example
1751
+ * ```typescript
1752
+ * const status = await wallet.checkApprovalStatus('req_123');
1753
+ * if (status.status === 'approved') {
1754
+ * console.log('Approved! Proceeding with action...');
1755
+ * }
1756
+ * ```
1757
+ */
1758
+ checkApprovalStatus(requestId: string): Promise<{
1759
+ requestId: string;
1760
+ status: ApprovalStatus;
1761
+ responseNote?: string;
1762
+ approvalScope?: ApprovalScope;
1763
+ respondedAt?: Date;
1764
+ }>;
1765
+ /**
1766
+ * Check if an action type needs approval before execution.
1767
+ *
1768
+ * @param actionType - The type of action to check
1769
+ * @param amountUsd - Optional amount for spend actions
1770
+ * @returns Whether approval is needed
1771
+ *
1772
+ * @example
1773
+ * ```typescript
1774
+ * const check = await wallet.checkActionPermission('external_communication');
1775
+ * if (check.needsApproval) {
1776
+ * const approval = await wallet.requestApproval({ ... });
1777
+ * }
1778
+ * ```
1779
+ */
1780
+ checkActionPermission(actionType: string, amountUsd?: number): Promise<PermissionCheckResult>;
1781
+ /**
1782
+ * Wait for an approval request to be resolved.
1783
+ * Polls the status until approved, rejected, or expired.
1784
+ *
1785
+ * @param requestId - The approval request ID
1786
+ * @param options - Polling options
1787
+ * @returns Final status of the request
1788
+ *
1789
+ * @example
1790
+ * ```typescript
1791
+ * const approval = await wallet.requestApproval({ ... });
1792
+ * if (!('autoApproved' in approval)) {
1793
+ * const result = await wallet.waitForApproval(approval.id, { timeoutMs: 60000 });
1794
+ * if (result.status === 'approved') {
1795
+ * // Proceed with action
1796
+ * }
1797
+ * }
1798
+ * ```
1799
+ */
1800
+ waitForApproval(requestId: string, options?: {
1801
+ pollIntervalMs?: number;
1802
+ timeoutMs?: number;
1803
+ }): Promise<{
1804
+ requestId: string;
1805
+ status: ApprovalStatus;
1806
+ responseNote?: string;
1807
+ approvalScope?: ApprovalScope;
1808
+ }>;
1809
+ /** Helper to parse approval request from API response */
1810
+ private parseApprovalRequest;
1811
+ /** Helper to parse task from API response */
1812
+ private parseTask;
1813
+ /** Helper to call our API with auth */
1814
+ private callApi;
1815
+ }
1816
+ /** Task status */
1817
+ type TaskStatus = 'open' | 'claimed' | 'submitted' | 'completed' | 'cancelled' | 'completing';
1818
+ /** Task creator or agent info */
1819
+ interface TaskAgent {
1820
+ id: string;
1821
+ displayName?: string;
1822
+ isAgent: boolean;
1823
+ walletAddress?: string;
1824
+ }
1825
+ /** Task details */
1826
+ interface Task {
1827
+ id: string;
1828
+ title: string;
1829
+ description: string;
1830
+ deliverables: string[];
1831
+ category?: string;
1832
+ budgetUsd: number;
1833
+ listingFeeUsd: number;
1834
+ status: TaskStatus;
1835
+ createdAt: Date;
1836
+ updatedAt?: Date;
1837
+ expiresAt?: Date;
1838
+ claimedAt?: Date;
1839
+ submittedAt?: Date;
1840
+ completedAt?: Date;
1841
+ creator?: TaskAgent;
1842
+ assignedAgent?: TaskAgent;
1843
+ requestCount?: number;
1844
+ output?: TaskOutput;
1845
+ payment?: TaskPaymentInfo;
1846
+ }
1847
+ /** Task output (deliverables) */
1848
+ interface TaskOutput {
1849
+ text?: string;
1850
+ url?: string;
1851
+ }
1852
+ /** Task payment info */
1853
+ interface TaskPaymentInfo {
1854
+ amountSpentUsd?: number;
1855
+ amountPaidUsd?: number;
1856
+ payoutTxHash?: string;
1857
+ }
1858
+ /** Parameters for creating a task */
1859
+ interface CreateTaskParams {
1860
+ title: string;
1861
+ description: string;
1862
+ budgetUsd: number;
1863
+ deliverables?: string[];
1864
+ category?: string;
1865
+ expiresInDays?: number;
1866
+ }
1867
+ /** Parameters for listing tasks */
1868
+ interface ListTasksParams {
1869
+ status?: 'open' | 'all';
1870
+ category?: string;
1871
+ minBudget?: number;
1872
+ maxBudget?: number;
1873
+ limit?: number;
1874
+ offset?: number;
1875
+ }
1876
+ /** Task list pagination */
1877
+ interface TaskPagination {
1878
+ total: number;
1879
+ limit: number;
1880
+ offset: number;
1881
+ hasMore: boolean;
1882
+ }
1883
+ /** Task list result */
1884
+ interface TaskListResult {
1885
+ tasks: Task[];
1886
+ pagination: TaskPagination;
1887
+ }
1888
+ /** Task request from an agent */
1889
+ interface TaskRequest {
1890
+ id: string;
1891
+ taskId: string;
1892
+ status: string;
1893
+ message?: string | null;
1894
+ createdAt: Date;
1895
+ }
1896
+ /** Task request with agent info */
1897
+ interface TaskRequestWithAgent extends TaskRequest {
1898
+ reviewedAt?: Date;
1899
+ agent: TaskAgent;
1900
+ }
1901
+ /** Result from accepting a task request */
1902
+ interface TaskAcceptResult {
1903
+ success: boolean;
1904
+ task: {
1905
+ id: string;
1906
+ status: string;
1907
+ agentUserId: string;
1908
+ };
1909
+ session: {
1910
+ id: string;
1911
+ /** The session key string (sk_live_...) - agent needs this to make API calls */
1912
+ sessionKey: string;
1913
+ /** The derived public address for this session */
1914
+ address: string;
1915
+ expiresAt: Date;
1916
+ budgetUsd: number;
1917
+ allowedMerchants: string[];
1918
+ };
1919
+ invite: {
1920
+ id: string;
1921
+ code: string;
1922
+ };
1923
+ listingFeeTxHash?: string;
1924
+ }
1925
+ /** Result from approving a task */
1926
+ interface TaskApproveResult {
1927
+ success: boolean;
1928
+ task: {
1929
+ id: string;
1930
+ status: string;
1931
+ completedAt: Date;
1932
+ };
1933
+ payout: {
1934
+ status: 'paid' | 'insufficient_funds' | 'nothing_remaining' | 'error';
1935
+ amountUsd: number;
1936
+ txHash?: string;
1937
+ };
1938
+ }
1939
+ /** Options for fetching user's own tasks */
1940
+ interface MyTasksOptions {
1941
+ /** Filter by role: 'creator' (tasks you created), 'agent' (tasks assigned to you), 'all' (default) */
1942
+ role?: 'creator' | 'agent' | 'all';
1943
+ /** Filter by task status */
1944
+ status?: TaskStatus;
1945
+ /** Page number (default: 1) */
1946
+ page?: number;
1947
+ /** Items per page (default: 20, max: 100) */
1948
+ limit?: number;
1949
+ }
1950
+ /** Options for creating a subtask */
1951
+ interface CreateSubtaskOptions {
1952
+ /** Parent task ID */
1953
+ parentTaskId: string;
1954
+ /** Subtask title */
1955
+ title: string;
1956
+ /** Subtask description */
1957
+ description: string;
1958
+ /** List of deliverables */
1959
+ deliverables?: string[];
1960
+ /** Category (inherits from parent if not specified) */
1961
+ category?: string;
1962
+ /** Budget in USD (allocated from parent) */
1963
+ budgetUsd: number;
1964
+ /** Whether this subtask can spawn sub-agents */
1965
+ allowSubAgents?: boolean;
1966
+ /** Days until expiration (default: 7) */
1967
+ expiresInDays?: number;
1968
+ /** Idempotency key for duplicate prevention */
1969
+ idempotencyKey?: string;
1970
+ }
1971
+ /** Task status history entry */
1972
+ interface TaskStatusHistoryEntry {
1973
+ id: string;
1974
+ oldStatus: string;
1975
+ newStatus: string;
1976
+ note?: string;
1977
+ createdAt: Date;
1978
+ }
1979
+ /** Task status history result */
1980
+ interface TaskStatusHistory {
1981
+ taskId: string;
1982
+ currentStatus: TaskStatus;
1983
+ history: TaskStatusHistoryEntry[];
1984
+ }
1985
+ /** Options for requesting approval */
1986
+ interface RequestApprovalOptions {
1987
+ /** Type of action needing approval (e.g., 'external_communication', 'final_output', 'spend') */
1988
+ actionType: string;
1989
+ /** Details of the action */
1990
+ actionPayload: Record<string, unknown>;
1991
+ /** Additional context for the human reviewer */
1992
+ context?: string;
1993
+ /** Hours until the request expires (default: 24, max: 168) */
1994
+ expiresInHours?: number;
1995
+ /** Idempotency key for duplicate prevention */
1996
+ idempotencyKey?: string;
1997
+ }
1998
+ /** Approval request status */
1999
+ type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
2000
+ /** Approval scope */
2001
+ type ApprovalScope = 'once' | 'session' | 'always';
2002
+ /** Approval request result */
2003
+ interface ApprovalRequest {
2004
+ id: string;
2005
+ actionType: string;
2006
+ actionPayload: Record<string, unknown>;
2007
+ context?: string;
2008
+ status: ApprovalStatus;
2009
+ responseNote?: string;
2010
+ approvalScope: ApprovalScope;
2011
+ createdAt: Date;
2012
+ expiresAt: Date;
2013
+ respondedAt?: Date;
2014
+ }
2015
+ /** Auto-approval result */
2016
+ interface AutoApprovalResult {
2017
+ autoApproved: true;
2018
+ reason: string;
2019
+ }
2020
+ /** Permission check result */
2021
+ interface PermissionCheckResult {
2022
+ actionType: string;
2023
+ needsApproval: boolean;
2024
+ reason: string;
2025
+ }
2026
+ /** Task with user relationship info */
2027
+ interface MyTask extends Task {
2028
+ /** Whether the current user created this task */
2029
+ isCreator: boolean;
2030
+ /** Whether the current user is the assigned agent */
2031
+ isAgent: boolean;
2032
+ }
2033
+ /** Result from fetching user's tasks */
2034
+ interface MyTasksResult {
2035
+ tasks: MyTask[];
2036
+ pagination: {
2037
+ page: number;
2038
+ limit: number;
2039
+ total: number;
2040
+ totalPages: number;
2041
+ };
1325
2042
  }
1326
2043
  /**
1327
2044
  * MCP Tool definition returned by listMCPTools()
@@ -1381,8 +2098,8 @@ interface AgentRunConfig {
1381
2098
  * Options for running an agent
1382
2099
  */
1383
2100
  interface AgentRunOptions {
1384
- /** Session ID for authentication and billing */
1385
- sessionId: string;
2101
+ /** Session ID for authentication and billing (optional when using session key auth) */
2102
+ sessionId?: string;
1386
2103
  /** Conversation messages */
1387
2104
  messages: AgentMessage[];
1388
2105
  /** Agent configuration */
@@ -1947,4 +2664,4 @@ declare function isMixrPayError(error: unknown): error is MixrPayError;
1947
2664
  */
1948
2665
  declare function getErrorMessage(error: unknown): string;
1949
2666
 
1950
- export { type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, type DiagnosticsResult, InsufficientBalanceError, InvalidSessionKeyError, MerchantNotAllowedError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, X402ProtocolError, getErrorMessage, isMixrPayError };
2667
+ export { type AgentClaimInviteOptions, type AgentClaimInviteResult, type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type AvailableBudget, type CallMerchantApiOptions, type ChargeResult, type ChildSession, type DiagnosticsResult, InsufficientBalanceError, InvalidSessionKeyError, MerchantNotAllowedError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, type SpawnChildOptions, type SpawnChildResult, SpendingLimitExceededError, type SpendingStats, X402ProtocolError, getErrorMessage, isMixrPayError };