@usesigil/kit 0.1.0 → 0.2.1

package/dist/agent-errors.js

@@ -5,7 +5,7 @@
  * Every error includes a category, retryability flag, and
  * recovery actions that tell the agent exactly what to do next.
  *
- * Maps all 71 on-chain error codes (6000-6070) plus 34 SDK
+ * Maps all 76 on-chain error codes (6000-6075) plus 34 SDK
  * error codes (7000-7033) to AgentError with machine-readable metadata.
  *
  * Zero dependency on @solana/web3.js or @coral-xyz/anchor.
@@ -393,20 +393,6 @@ export const ON_CHAIN_ERROR_MAP = {
         ],
     },
     6027: {
-        name: "TimelockActive",
-        message: "Vault has timelock active — use queue_policy_update instead of direct update",
-        category: "POLICY_VIOLATION",
-        retryable: false,
-        recovery_actions: [
-            {
-                action: "queue_update",
-                description: "Queue the policy update through the timelock mechanism",
-                tool: "sigil_update_policy",
-                parameters: { use_timelock: true },
-            },
-        ],
-    },
-    6028: {
         name: "NoTimelockConfigured",
         message: "No timelock configured on this vault",
         category: "INPUT_VALIDATION",
@@ -418,7 +404,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6029: {
+    6028: {
         name: "DestinationNotAllowed",
         message: "Destination address not in vault's allowed destinations list",
         category: "POLICY_VIOLATION",
@@ -435,7 +421,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6030: {
+    6029: {
         name: "TooManyDestinations",
         message: "Too many destinations in allowlist (max 10)",
         category: "INPUT_VALIDATION",
@@ -447,7 +433,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6031: {
+    6030: {
         name: "InvalidProtocolMode",
         message: "Invalid protocol mode (must be 0=all, 1=allowlist, or 2=denylist)",
         category: "INPUT_VALIDATION",
@@ -460,7 +446,7 @@ export const ON_CHAIN_ERROR_MAP = {
         ],
     },
     // --- Flash Trade expansion errors ---
-    6032: {
+    6031: {
         name: "InvalidNonSpendingAmount",
         message: "Non-spending action must have amount = 0",
         category: "INPUT_VALIDATION",
@@ -472,7 +458,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6033: {
+    6032: {
         name: "NoPositionsToClose",
         message: "No open positions to close or cancel",
         category: "RESOURCE_NOT_FOUND",
@@ -485,7 +471,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6034: {
+    6033: {
         name: "CpiCallNotAllowed",
         message: "Instruction must be top-level (CPI calls not allowed for validate/finalize)",
         category: "FATAL",
@@ -497,7 +483,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6035: {
+    6034: {
         name: "MissingFinalizeInstruction",
         message: "Transaction must include finalize_session after validate_and_authorize",
         category: "INPUT_VALIDATION",
@@ -510,7 +496,7 @@ export const ON_CHAIN_ERROR_MAP = {
         ],
     },
     // --- Stablecoin-only enforcement errors ---
-    6036: {
+    6035: {
         name: "NonTrackedSwapMustReturnStablecoin",
         message: "Non-stablecoin swap must return stablecoin (vault stablecoin balance did not increase)",
         category: "INPUT_VALIDATION",
@@ -522,7 +508,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6037: {
+    6036: {
         name: "SwapSlippageExceeded",
         message: "Swap slippage exceeds policy max_slippage_bps or quoted output is zero",
         category: "POLICY_VIOLATION",
@@ -539,7 +525,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6038: {
+    6037: {
         name: "InvalidJupiterInstruction",
         message: "Cannot parse Jupiter swap instruction data",
         category: "INPUT_VALIDATION",
@@ -551,7 +537,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6039: {
+    6038: {
         name: "UnauthorizedTokenTransfer",
         message: "Top-level SPL Token transfer not allowed between validate and finalize",
         category: "POLICY_VIOLATION",
@@ -563,7 +549,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6040: {
+    6039: {
         name: "SlippageBpsTooHigh",
         message: "Slippage BPS exceeds maximum allowed (5000 = 50%)",
         category: "INPUT_VALIDATION",
@@ -575,7 +561,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6041: {
+    6040: {
         name: "ProtocolMismatch",
         message: "DeFi instruction program does not match the declared target_protocol",
         category: "INPUT_VALIDATION",
@@ -587,7 +573,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6042: {
+    6041: {
         name: "TooManyDeFiInstructions",
         message: "Non-stablecoin swap allows exactly one DeFi instruction",
         category: "INPUT_VALIDATION",
@@ -600,7 +586,7 @@ export const ON_CHAIN_ERROR_MAP = {
         ],
     },
     // --- Multi-Agent errors ---
-    6043: {
+    6042: {
         name: "MaxAgentsReached",
         message: "Maximum agents per vault reached (limit: 10)",
         category: "INPUT_VALIDATION",
@@ -613,7 +599,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6044: {
+    6043: {
         name: "InsufficientPermissions",
         message: "Agent lacks permission for this action type",
         category: "PERMISSION",
@@ -630,7 +616,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6045: {
+    6044: {
         name: "InvalidPermissions",
         message: "Permission bitmask contains invalid bits (only 21 bits valid)",
         category: "INPUT_VALIDATION",
@@ -643,7 +629,7 @@ export const ON_CHAIN_ERROR_MAP = {
         ],
     },
     // --- Escrow errors ---
-    6046: {
+    6045: {
         name: "EscrowNotActive",
         message: "Escrow is not in Active status",
         category: "RESOURCE_NOT_FOUND",
@@ -655,7 +641,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6047: {
+    6046: {
         name: "EscrowExpired",
         message: "Escrow has expired — can only be refunded now",
         category: "RESOURCE_NOT_FOUND",
@@ -668,7 +654,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6048: {
+    6047: {
         name: "EscrowNotExpired",
         message: "Escrow has not expired yet — cannot refund before expiry",
         category: "INPUT_VALIDATION",
@@ -685,7 +671,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6049: {
+    6048: {
         name: "InvalidEscrowVault",
         message: "Invalid escrow vault — source or destination vault mismatch",
         category: "INPUT_VALIDATION",
@@ -697,7 +683,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6050: {
+    6049: {
         name: "EscrowConditionsNotMet",
         message: "Escrow settlement conditions not met (SHA-256 proof invalid)",
         category: "INPUT_VALIDATION",
@@ -709,7 +695,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6051: {
+    6050: {
         name: "EscrowDurationExceeded",
         message: "Escrow duration exceeds maximum (30 days)",
         category: "INPUT_VALIDATION",
@@ -722,7 +708,7 @@ export const ON_CHAIN_ERROR_MAP = {
         ],
     },
     // --- Instruction constraints errors ---
-    6052: {
+    6051: {
         name: "InvalidConstraintConfig",
         message: "Invalid constraint configuration: bounds exceeded",
         category: "INPUT_VALIDATION",
@@ -734,7 +720,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6053: {
+    6052: {
         name: "ConstraintViolated",
         message: "Instruction violated a configured constraint",
         category: "POLICY_VIOLATION",
@@ -751,7 +737,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6054: {
+    6053: {
         name: "InvalidConstraintsPda",
         message: "Invalid constraints PDA: wrong owner or vault",
         category: "INPUT_VALIDATION",
@@ -763,7 +749,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6055: {
+    6054: {
         name: "InvalidPendingConstraintsPda",
         message: "Invalid pending constraints PDA: wrong owner or vault",
         category: "INPUT_VALIDATION",
@@ -776,7 +762,7 @@ export const ON_CHAIN_ERROR_MAP = {
         ],
     },
     // --- Per-agent spend limit errors ---
-    6056: {
+    6055: {
         name: "AgentSpendLimitExceeded",
         message: "Agent's rolling 24h spend exceeds their individual spending limit",
         category: "SPENDING_CAP",
@@ -798,7 +784,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6057: {
+    6056: {
         name: "OverlaySlotExhausted",
         message: "Per-agent overlay is full — cannot register agent with spending limit",
         category: "INPUT_VALIDATION",
@@ -811,7 +797,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6058: {
+    6057: {
         name: "AgentSlotNotFound",
         message: "Agent has per-agent spending limit but no overlay tracking slot",
         category: "RESOURCE_NOT_FOUND",
@@ -823,7 +809,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6059: {
+    6058: {
         name: "UnauthorizedTokenApproval",
         message: "Unauthorized SPL Token Approve detected between validate and finalize",
         category: "POLICY_VIOLATION",
@@ -835,7 +821,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6060: {
+    6059: {
         name: "InvalidSessionExpiry",
         message: "Session expiry slots out of range (10-450)",
         category: "INPUT_VALIDATION",
@@ -847,7 +833,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6061: {
+    6060: {
         name: "UnconstrainedProgramBlocked",
         message: "Program has no constraint entry and strict mode is enabled",
         category: "POLICY_VIOLATION",
@@ -865,7 +851,7 @@ export const ON_CHAIN_ERROR_MAP = {
         ],
     },
     // --- Per-protocol spend cap errors ---
-    6062: {
+    6061: {
         name: "ProtocolCapExceeded",
         message: "Per-protocol rolling 24h spending cap would be exceeded",
         category: "SPENDING_CAP",
@@ -886,7 +872,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6063: {
+    6062: {
         name: "ProtocolCapsMismatch",
         message: "protocol_caps length must match protocols length when has_protocol_caps is true",
         category: "INPUT_VALIDATION",
@@ -899,7 +885,7 @@ export const ON_CHAIN_ERROR_MAP = {
         ],
     },
     // --- Vault closure guard errors ---
-    6064: {
+    6063: {
         name: "ActiveEscrowsExist",
         message: "Active escrow deposits exist — close them before closing vault",
         category: "RESOURCE_NOT_FOUND",
@@ -911,7 +897,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6065: {
+    6064: {
         name: "ConstraintsNotClosed",
         message: "Instruction constraints PDA still exists — close it before closing vault",
         category: "RESOURCE_NOT_FOUND",
@@ -923,7 +909,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6066: {
+    6065: {
         name: "PendingPolicyExists",
         message: "A pending policy update exists — apply or cancel it before closing vault",
         category: "RESOURCE_NOT_FOUND",
@@ -936,7 +922,7 @@ export const ON_CHAIN_ERROR_MAP = {
         ],
     },
     // --- Agent pause errors ---
-    6067: {
+    6066: {
         name: "AgentPaused",
         message: "Agent is paused — unpause before executing actions",
         category: "PERMISSION",
@@ -948,7 +934,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6068: {
+    6067: {
         name: "AgentAlreadyPaused",
         message: "Agent is already paused",
         category: "INPUT_VALIDATION",
@@ -960,7 +946,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6069: {
+    6068: {
         name: "AgentNotPaused",
         message: "Agent is not paused — cannot unpause",
         category: "INPUT_VALIDATION",
@@ -972,7 +958,7 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
-    6070: {
+    6069: {
         name: "UnauthorizedPostFinalizeInstruction",
         message: "Instructions after finalize_session must be ComputeBudget or SystemProgram only",
         category: "POLICY_VIOLATION",
@@ -984,6 +970,88 @@ export const ON_CHAIN_ERROR_MAP = {
             },
         ],
     },
+    6070: {
+        name: "UnexpectedBalanceDecrease",
+        message: "Vault stablecoin balance decreased more than the session authorized amount. " +
+            "This indicates a compromised DeFi program attempted to drain vault tokens via CPI.",
+        category: "FATAL",
+        retryable: false,
+        recovery_actions: [
+            {
+                action: "investigate_defi_program",
+                description: "The whitelisted DeFi program may be compromised. The actual vault balance decrease " +
+                    "exceeded the authorized delegation amount (fees + DeFi spend). Freeze the vault, " +
+                    "investigate the DeFi program, and consider removing it from the protocol allowlist.",
+            },
+            {
+                action: "freeze_vault",
+                description: "Immediately freeze the vault to prevent further transactions until the cause is identified.",
+            },
+        ],
+    },
+    // --- TOCTOU + timelock hardening errors ---
+    6071: {
+        name: "TimelockTooShort",
+        message: "Timelock duration is below the minimum (1800 seconds / 30 minutes).",
+        category: "INPUT_VALIDATION",
+        retryable: false,
+        recovery_actions: [
+            {
+                action: "increase_timelock",
+                description: "Set timelock_duration to at least 1800 seconds (30 minutes).",
+            },
+        ],
+    },
+    6072: {
+        name: "PolicyVersionMismatch",
+        message: "Policy version changed since agent's last RPC read. Re-resolve vault state and retry.",
+        category: "TRANSIENT",
+        retryable: true,
+        retry_after_ms: 1000,
+        recovery_actions: [
+            {
+                action: "re_resolve_state",
+                description: "Re-fetch vault state via resolveVaultState() to get current policy version, then retry.",
+            },
+        ],
+    },
+    6073: {
+        name: "PendingAgentPermsExists",
+        message: "A pending agent permissions update already exists for this agent.",
+        category: "RESOURCE_NOT_FOUND",
+        retryable: false,
+        recovery_actions: [
+            {
+                action: "apply_or_cancel_pending",
+                description: "Apply or cancel the existing pending update before queuing a new one.",
+            },
+        ],
+    },
+    6074: {
+        name: "PendingCloseConstraintsExists",
+        message: "A pending close constraints operation already exists for this vault.",
+        category: "RESOURCE_NOT_FOUND",
+        retryable: false,
+        recovery_actions: [
+            {
+                action: "apply_or_cancel_pending",
+                description: "Apply or cancel the existing pending close constraints before queuing a new one.",
+            },
+        ],
+    },
+    6075: {
+        name: "ActiveSessionsExist",
+        message: "Cannot close vault with active sessions. Finalize all pending sessions first.",
+        category: "POLICY_VIOLATION",
+        retryable: true,
+        retry_after_ms: 10000,
+        recovery_actions: [
+            {
+                action: "finalize_sessions",
+                description: "Wait for active sessions to finalize or expire, then retry close_vault.",
+            },
+        ],
+    },
 };
 // ---------------------------------------------------------------------------
 // SDK error codes (7000-7033) — numeric to match agent error code pattern
@@ -1481,7 +1549,7 @@ const SDK_ERRORS = {
  * Convert any error into a structured AgentError.
  *
  * Handles:
- * - On-chain Anchor errors (code 6000-6069)
+ * - On-chain Anchor errors (code 6000-6075)
  * - SDK errors (code 7000-7033)
  * - Network/RPC errors (from message patterns)
  * - Unknown errors (wrapped as FATAL)
@@ -1783,7 +1851,7 @@ function extractErrorCode(error) {
         return null;
     const e = error;
     // Direct code property
-    if (typeof e.code === "number" && e.code >= 6000 && e.code <= 6069)
+    if (typeof e.code === "number" && e.code >= 6000 && e.code <= 6075)
         return e.code;
     // Anchor error structure
     if (e.error && typeof e.error === "object") {
@@ -1799,7 +1867,7 @@ function extractErrorCode(error) {
         const match = e.message.match(/custom program error: 0x([0-9a-fA-F]+)/);
         if (match) {
             const code = parseInt(match[1], 16);
-            if (code >= 6000 && code <= 6069)
+            if (code >= 6000 && code <= 6075)
                 return code;
         }
     }
@@ -1849,8 +1917,15 @@ const SDK_ERROR_PATTERNS = [
         category: "RESOURCE_NOT_FOUND",
         retryable: false,
         recovery_actions: [
-            { action: "check_vault_status", description: "Verify vault status. It may be frozen or closed." },
-            { action: "reactivate_vault", description: "If frozen, ask the vault owner to reactivate.", tool: "reactivateVault" },
+            {
+                action: "check_vault_status",
+                description: "Verify vault status. It may be frozen or closed.",
+            },
+            {
+                action: "reactivate_vault",
+                description: "If frozen, ask the vault owner to reactivate.",
+                tool: "reactivateVault",
+            },
         ],
     },
     {
@@ -1858,7 +1933,11 @@ const SDK_ERROR_PATTERNS = [
         category: "PERMISSION",
         retryable: false,
         recovery_actions: [
-            { action: "register_agent", description: "Register this agent in the vault.", tool: "registerAgent" },
+            {
+                action: "register_agent",
+                description: "Register this agent in the vault.",
+                tool: "registerAgent",
+            },
         ],
     },
     {
@@ -1866,7 +1945,11 @@ const SDK_ERROR_PATTERNS = [
         category: "PERMISSION",
         retryable: false,
         recovery_actions: [
-            { action: "unpause_agent", description: "Ask the vault owner to unpause this agent.", tool: "unpauseAgent" },
+            {
+                action: "unpause_agent",
+                description: "Ask the vault owner to unpause this agent.",
+                tool: "unpauseAgent",
+            },
         ],
     },
     {
@@ -1874,7 +1957,10 @@ const SDK_ERROR_PATTERNS = [
         category: "PERMISSION",
         retryable: false,
         recovery_actions: [
-            { action: "update_permissions", description: "Request permission for this action type from the vault owner." },
+            {
+                action: "update_permissions",
+                description: "Request permission for this action type from the vault owner.",
+            },
         ],
     },
     {
@@ -1882,7 +1968,10 @@ const SDK_ERROR_PATTERNS = [
         category: "PROTOCOL_NOT_SUPPORTED",
         retryable: false,
         recovery_actions: [
-            { action: "add_protocol", description: "Add this protocol to the vault's allowlist." },
+            {
+                action: "add_protocol",
+                description: "Add this protocol to the vault's allowlist.",
+            },
         ],
     },
     {
@@ -1890,8 +1979,14 @@ const SDK_ERROR_PATTERNS = [
         category: "INPUT_VALIDATION",
         retryable: false,
         recovery_actions: [
-            { action: "add_alts", description: "Pass protocolAltAddresses from your DeFi API response." },
-            { action: "reduce_instructions", description: "Reduce instruction count or split across multiple transactions." },
+            {
+                action: "add_alts",
+                description: "Pass protocolAltAddresses from your DeFi API response.",
+            },
+            {
+                action: "reduce_instructions",
+                description: "Reduce instruction count or split across multiple transactions.",
+            },
         ],
     },
     {
@@ -1899,7 +1994,10 @@ const SDK_ERROR_PATTERNS = [
         category: "POLICY_VIOLATION",
         retryable: true,
         recovery_actions: [
-            { action: "close_position", description: "Close an existing position before opening a new one." },
+            {
+                action: "close_position",
+                description: "Close an existing position before opening a new one.",
+            },
         ],
     },
     {
@@ -1907,7 +2005,10 @@ const SDK_ERROR_PATTERNS = [
         category: "INPUT_VALIDATION",
         retryable: false,
         recovery_actions: [
-            { action: "fix_amount", description: "Set amount to the transaction value in token base units." },
+            {
+                action: "fix_amount",
+                description: "Set amount to the transaction value in token base units.",
+            },
         ],
     },
     {
@@ -1915,7 +2016,10 @@ const SDK_ERROR_PATTERNS = [
         category: "INPUT_VALIDATION",
         retryable: false,
         recovery_actions: [
-            { action: "set_zero_amount", description: "Non-spending actions (close, withdraw, etc.) require amount = 0n." },
+            {
+                action: "set_zero_amount",
+                description: "Non-spending actions (close, withdraw, etc.) require amount = 0n.",
+            },
         ],
     },
     {
@@ -1923,7 +2027,10 @@ const SDK_ERROR_PATTERNS = [
         category: "INPUT_VALIDATION",
         retryable: false,
         recovery_actions: [
-            { action: "add_instructions", description: "Include DeFi instructions in the wrap call, or set targetProtocol explicitly." },
+            {
+                action: "add_instructions",
+                description: "Include DeFi instructions in the wrap call, or set targetProtocol explicitly.",
+            },
         ],
     },
     {
@@ -1931,7 +2038,10 @@ const SDK_ERROR_PATTERNS = [
         category: "INPUT_VALIDATION",
         retryable: false,
         recovery_actions: [
-            { action: "use_escrow_api", description: "Use createEscrow/settleEscrow/refundEscrow instead of wrap()." },
+            {
+                action: "use_escrow_api",
+                description: "Use createEscrow/settleEscrow/refundEscrow instead of wrap().",
+            },
         ],
     },
 ];
@@ -1965,7 +2075,7 @@ export class SigilSdkError extends Error {
  * Returns a SigilSdkError (extends Error) so instanceof Error checks still work.
  *
  * Processing order:
- * 1. Try on-chain error extraction via toAgentError() (numeric codes 6000-6070)
+ * 1. Try on-chain error extraction via toAgentError() (numeric codes 6000-6075)
  * 2. Pattern-match SDK error messages (11 patterns from seal.ts throw sites)
  * 3. Fallback to UNKNOWN/FATAL
  */