@mixrpay/agent-sdk 0.8.6 → 0.8.9

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: {
@@ -1453,6 +1459,143 @@ declare class AgentWallet {
      * ```
      */
     getJitInstance(instanceId: string): Promise<JitInstance>;
+    /**
+     * Use a configured skill by deploying a JIT MCP server with your saved API keys.
+     *
+     * Skills are configured on the MixrPay dashboard with your API keys stored securely.
+     * When you call useSkill(), MixrPay deploys an ephemeral MCP server with your keys
+     * injected server-side - your keys are never exposed to the agent.
+     *
+     * @param skillId - The skill ID (e.g., 'github', 'notion', 'spotify')
+     * @param options - Optional configuration
+     * @returns Skill endpoint and available tools
+     *
+     * @example
+     * ```typescript
+     * // Use the GitHub skill
+     * const github = await wallet.useSkill('github');
+     *
+     * console.log('Endpoint:', github.endpoint);
+     * console.log('Tools:', github.tools);
+     * console.log('Expires:', github.expiresAt);
+     *
+     * // Connect to the MCP endpoint and call tools
+     * // The exact method depends on your MCP client
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Use Notion with custom TTL
+     * const notion = await wallet.useSkill('notion', { ttlHours: 48 });
+     * ```
+     *
+     * @throws {MixrPayError} If skill is not configured or deployment fails
+     */
+    useSkill(skillId: string, options?: UseSkillOptions): Promise<UseSkillResult>;
+    /**
+     * List all available skills and their configuration status.
+     *
+     * @returns Array of skills with status
+     *
+     * @example
+     * ```typescript
+     * const skills = await wallet.listSkills();
+     *
+     * // Find configured skills
+     * const configured = skills.filter(s => s.status === 'configured');
+     * console.log(`${configured.length} skills ready to use`);
+     *
+     * // Find skills that need configuration
+     * const needsConfig = skills.filter(s => s.status === 'not_configured' && s.envVars.length > 0);
+     * for (const skill of needsConfig) {
+     *   console.log(`${skill.name} needs: ${skill.envVars.map(v => v.label).join(', ')}`);
+     * }
+     * ```
+     */
+    listSkills(): Promise<SkillInfo[]>;
+    /**
+     * Get apps connected via Composio (Gmail, Slack, GitHub, etc.).
+     *
+     * Use this to discover which apps the owner has connected before
+     * attempting to use them via `wallet.useSkill('composio')`.
+     *
+     * @returns Object with connected app names and connection details
+     *
+     * @example
+     * ```typescript
+     * const apps = await wallet.getConnectedApps();
+     *
+     * if (apps.connected.length === 0) {
+     *   console.log('No apps connected. Ask your owner to connect apps at the dashboard.');
+     * } else {
+     *   console.log('Connected apps:', apps.connected.join(', '));
+     *
+     *   if (apps.connected.includes('gmail')) {
+     *     // Safe to use Composio for Gmail
+     *     const { endpoint, tools } = await wallet.useSkill('composio');
+     *     // tools will include 'gmail_read_emails', 'gmail_send_email', etc.
+     *   }
+     * }
+     * ```
+     */
+    getConnectedApps(): Promise<ConnectedAppsResult>;
+    /**
+     * Get configuration status for a specific skill.
+     *
+     * @param skillId - The skill ID
+     * @returns Skill configuration status
+     *
+     * @example
+     * ```typescript
+     * const status = await wallet.getSkillStatus('github');
+     *
+     * if (status.status === 'configured') {
+     *   console.log('GitHub is ready!');
+     *   console.log('Configured vars:', status.configuredVars);
+     * } else {
+     *   console.log('Please configure GitHub at the MixrPay dashboard');
+     * }
+     * ```
+     */
+    getSkillStatus(skillId: string): Promise<SkillStatus>;
+    /**
+     * Configure a skill with API keys.
+     *
+     * This allows agents to save API keys received via chat to the MixrPay platform.
+     * Keys are encrypted at rest and will be available for use on subsequent deploy/redeploy.
+     *
+     * @param skillId - The skill ID (e.g., 'web-search', 'github', 'notion') or custom skill with 'custom-' prefix
+     * @param envVars - Environment variables with API keys (e.g., { BRAVE_API_KEY: 'xxx' })
+     * @returns Configuration result with list of configured variables
+     *
+     * @example Predefined skill
+     * ```typescript
+     * // User provides API key in chat, agent saves it
+     * const result = await wallet.configureSkill('web-search', {
+     *   BRAVE_API_KEY: 'BSA_abc123xyz',
+     * });
+     *
+     * console.log('Configured:', result.configuredVars);
+     * // After next redeploy, the skill will be enabled with this key
+     * ```
+     *
+     * @example Custom API key
+     * ```typescript
+     * // For APIs not in predefined skills, use custom- prefix
+     * // User: "Here's my Polymarket API key: pk_abc123"
+     * const result = await wallet.configureSkill('custom-polymarket', {
+     *   POLYMARKET_API_KEY: 'pk_abc123',
+     * });
+     *
+     * // The key is now available in the agent's environment
+     * // Access via: process.env.POLYMARKET_API_KEY
+     * ```
+     */
+    configureSkill(skillId: string, envVars: Record<string, string>): Promise<{
+        success: boolean;
+        skillId: string;
+        configuredVars: string[];
+    }>;
     /**
      * Search the Glama MCP server directory.
      *
@@ -1507,6 +1650,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.
      *
@@ -2303,6 +2605,115 @@ interface JitInstance {
     /** Creation time */
     createdAt: Date;
 }
+/**
+ * Options for using a skill
+ */
+interface UseSkillOptions {
+    /** Time-to-live in hours for the MCP server (default: 24, max: 48) */
+    ttlHours?: number;
+}
+/**
+ * Result from using a skill
+ */
+interface UseSkillResult {
+    /** Skill ID */
+    skillId: string;
+    /** MCP server endpoint URL */
+    endpoint: string;
+    /** Available tool names */
+    tools: string[];
+    /** When the MCP server expires */
+    expiresAt: Date;
+    /** JIT instance ID for reference */
+    instanceId: string;
+}
+/**
+ * Skill information from the skills list
+ */
+interface SkillInfo {
+    /** Skill ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Short description */
+    description: string;
+    /** Category */
+    category: string;
+    /** Category display name */
+    categoryName: string;
+    /** Icon name */
+    icon: string;
+    /** Whether this is a built-in skill */
+    builtIn: boolean;
+    /** Whether this skill requires MCP deployment */
+    requiresMcp: boolean;
+    /** Whether this skill is available */
+    available: boolean;
+    /** Configuration status */
+    status: 'not_configured' | 'configured' | 'error';
+    /** Last used timestamp */
+    lastUsedAt?: string;
+    /** Error message if status is 'error' */
+    errorMessage?: string;
+    /** Environment variables required */
+    envVars: Array<{
+        name: string;
+        label: string;
+        description: string;
+        required: boolean;
+        isSecret: boolean;
+        configured: boolean;
+    }>;
+}
+/**
+ * Skill configuration status
+ */
+interface SkillStatus {
+    /** Skill ID */
+    skillId: string;
+    /** Configuration status */
+    status: 'not_configured' | 'configured' | 'error';
+    /** Names of configured environment variables */
+    configuredVars: string[];
+    /** Last used timestamp */
+    lastUsedAt?: Date;
+    /** Error message if status is 'error' */
+    errorMessage?: string;
+}
+/**
+ * Connected apps information from Composio
+ */
+interface ConnectedAppsResult {
+    /** Array of connected app IDs (e.g., ['gmail', 'slack', 'github']) */
+    connected: string[];
+    /** Full connection details */
+    connections: Array<{
+        id: string;
+        app: string;
+        app_name: string;
+        type: 'oauth' | 'api_key';
+        status: string;
+        account_name: string | null;
+        connected_at: string;
+    }>;
+    /** OAuth connections only */
+    oauthConnections: Array<{
+        id: string;
+        app: string;
+        app_name: string;
+        status: string;
+        account_name: string | null;
+        connected_at: string;
+    }>;
+    /** API key connections only */
+    apiKeyConnections: Array<{
+        id: string;
+        app: string;
+        app_name: string;
+        status: string;
+        connected_at: string;
+    }>;
+}
 /**
  * MCP server from the Glama directory
  */
@@ -2541,6 +2952,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
@@ -2982,4 +3649,4 @@ declare function isMixrPayError(error: unknown): error is MixrPayError;
  */
 declare function getErrorMessage(error: unknown): string;
 
-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 CompleteOptions, type CompleteResult, type DeployJitMcpOptions, type DeployJitMcpResult, type DiagnosticsResult, type GlamaImportData, type GlamaSearchResult, type GlamaServer, InsufficientBalanceError, InvalidSessionKeyError, type JitInstance, 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 };
+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 CompleteOptions, type CompleteResult, type DeployJitMcpOptions, type DeployJitMcpResult, type DiagnosticsResult, type GlamaImportData, type GlamaSearchResult, type GlamaServer, InsufficientBalanceError, InvalidSessionKeyError, type JitInstance, MerchantNotAllowedError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, type SkillInfo, type SkillStatus, type SpawnChildOptions, type SpawnChildResult, SpendingLimitExceededError, type SpendingStats, type UseSkillOptions, type UseSkillResult, X402ProtocolError, getErrorMessage, isMixrPayError };