@usesigil/kit 0.1.0

package/dist/agent-errors.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Kit-native Agent Error System
+ *
+ * Structured errors optimized for AI agent consumption.
+ * 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
+ * error codes (7000-7033) to AgentError with machine-readable metadata.
+ *
+ * Zero dependency on @solana/web3.js or @coral-xyz/anchor.
+ * Uses bigint instead of BN for context values.
+ */
+export type ErrorCategory = "INPUT_VALIDATION" | "TRANSIENT" | "RATE_LIMIT" | "PERMISSION" | "RESOURCE_NOT_FOUND" | "SPENDING_CAP" | "POLICY_VIOLATION" | "PROTOCOL_NOT_SUPPORTED" | "ESCALATION_REQUIRED" | "FATAL";
+export interface RecoveryAction {
+    /** Machine-readable action identifier */
+    action: string;
+    /** Human-readable description of what to do */
+    description: string;
+    /** Which tool to call for recovery (if applicable) */
+    tool?: string;
+    /** Suggested parameter values for the recovery tool */
+    parameters?: Record<string, unknown>;
+}
+export interface AgentError {
+    /** Error code — on-chain numeric (e.g. "6010") or SDK string (e.g. "NETWORK_ERROR") */
+    code: string;
+    /** One-sentence description */
+    message: string;
+    /** Error classification for agent decision-making */
+    category: ErrorCategory;
+    /** Whether the same request may succeed if retried */
+    retryable: boolean;
+    /** Suggested delay before retry (ms), only meaningful when retryable=true */
+    retry_after_ms?: number;
+    /** Ordered list of recovery actions the agent should attempt */
+    recovery_actions: RecoveryAction[];
+    /** Additional context about the error (amounts, addresses, etc.) */
+    context: Record<string, unknown>;
+}
+interface ErrorMapping {
+    name: string;
+    message: string;
+    category: ErrorCategory;
+    retryable: boolean;
+    retry_after_ms?: number;
+    recovery_actions: RecoveryAction[];
+}
+export declare const ON_CHAIN_ERROR_MAP: Record<number, ErrorMapping>;
+/**
+ * Convert any error into a structured AgentError.
+ *
+ * Handles:
+ * - On-chain Anchor errors (code 6000-6069)
+ * - SDK errors (code 7000-7033)
+ * - Network/RPC errors (from message patterns)
+ * - Unknown errors (wrapped as FATAL)
+ *
+ * Uses bigint for context values instead of BN.
+ */
+export declare function toAgentError(error: unknown, extraContext?: Record<string, unknown>): AgentError;
+/**
+ * Create an AgentError for protocol escalation.
+ *
+ * The anti-redirect behavior is embedded in the error structure:
+ * 1. Primary recovery = escalate_to_human (ALWAYS first)
+ * 2. Secondary = what vault owner must change
+ * 3. Tertiary = alternatives ONLY IF user agrees (ALWAYS last)
+ */
+export declare function protocolEscalationError(escalation: {
+    message: string;
+    requiredActions: string[];
+    alternatives?: unknown[];
+}): AgentError;
+/**
+ * Parse an on-chain error code (numeric or hex string) into an AgentError.
+ *
+ * @param codeOrHex - Numeric code (e.g. 6000) or hex string (e.g. "0x1770")
+ * @returns AgentError if the code maps to a known error, null otherwise
+ */
+export declare function parseOnChainErrorCode(codeOrHex: number | string): AgentError | null;
+/**
+ * Type guard for AgentError.
+ */
+export declare function isAgentError(value: unknown): value is AgentError;
+/**
+ * Get all mapped on-chain error codes (for testing/documentation).
+ */
+export declare function getAllOnChainErrorCodes(): number[];
+/**
+ * Discriminated union for TypeScript switch exhaustiveness with typed context.
+ *
+ * Complements `ErrorCategory` (string literal union for agent decision-making).
+ * Use `SigilErrorCategory` when you need typed access to error-specific fields
+ * like `remaining` for spending errors or `protocol` for protocol errors.
+ */
+export type SigilErrorCategory = {
+    type: "spending";
+    code: number;
+    remaining: bigint;
+    cap: bigint;
+} | {
+    type: "permission";
+    code: number;
+    required: string;
+} | {
+    type: "protocol";
+    code: number;
+    protocol: string;
+} | {
+    type: "vault";
+    code: number;
+    status: string;
+} | {
+    type: "network";
+    code: number;
+    retryable: boolean;
+};
+export declare function categorizeError(err: AgentError): SigilErrorCategory;
+/**
+ * Get all SDK error codes (for testing/documentation).
+ */
+export declare function getAllSdkErrorCodes(): Array<{
+    code: number;
+    name: string;
+}>;
+/**
+ * Error class that is BOTH an Error instance AND an AgentError.
+ * Critical: extends Error so `instanceof Error` checks work in consumer code.
+ */
+export declare class SigilSdkError extends Error implements AgentError {
+    readonly code: string;
+    readonly category: ErrorCategory;
+    readonly retryable: boolean;
+    readonly recovery_actions: RecoveryAction[];
+    readonly context: Record<string, unknown>;
+    readonly retry_after_ms?: number;
+    constructor(agentError: AgentError);
+}
+/**
+ * Convert any error thrown by seal() or SigilClient methods into a structured AgentError.
+ * 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)
+ * 2. Pattern-match SDK error messages (11 patterns from seal.ts throw sites)
+ * 3. Fallback to UNKNOWN/FATAL
+ */
+export declare function toSigilAgentError(err: unknown): SigilSdkError;
+export {};
+//# sourceMappingURL=agent-errors.d.ts.map

package/dist/agent-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-errors.d.ts","sourceRoot":"","sources":["../src/agent-errors.ts"],"names":[],"mappings":"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"}