@bradygaster/squad-sdk 0.7.0 → 0.8.0

package/dist/adapter/errors.d.ts

@@ -0,0 +1,260 @@
+/**
+ * SDK Error Hierarchy and Telemetry (M0-6, Issue #78)
+ *
+ * Wraps Copilot SDK errors with Squad-specific context and diagnostic information.
+ * Provides a comprehensive error hierarchy for SDK-specific exceptions.
+ * Includes basic telemetry hooks for latency tracking and error rate monitoring.
+ *
+ * @module adapter/errors
+ */
+/**
+ * Error severity levels for classification and routing.
+ */
+export declare enum ErrorSeverity {
+    /** Informational — no action needed, logged for awareness */
+    INFO = "info",
+    /** Warning — degraded functionality but operation can continue */
+    WARNING = "warning",
+    /** Error — operation failed but system remains stable */
+    ERROR = "error",
+    /** Critical — system stability at risk, requires immediate attention */
+    CRITICAL = "critical"
+}
+/**
+ * Error categories for diagnostic routing.
+ */
+export declare enum ErrorCategory {
+    /** SDK connection or communication errors */
+    SDK_CONNECTION = "sdk_connection",
+    /** Session lifecycle errors (create, resume, close) */
+    SESSION_LIFECYCLE = "session_lifecycle",
+    /** Tool execution failures */
+    TOOL_EXECUTION = "tool_execution",
+    /** Model API call failures */
+    MODEL_API = "model_api",
+    /** Configuration errors */
+    CONFIGURATION = "configuration",
+    /** Authentication and authorization failures */
+    AUTH = "auth",
+    /** Rate limiting and quota errors */
+    RATE_LIMIT = "rate_limit",
+    /** Internal Squad runtime errors */
+    RUNTIME = "runtime",
+    /** Validation errors (invalid input) */
+    VALIDATION = "validation",
+    /** Unknown or uncategorized errors */
+    UNKNOWN = "unknown"
+}
+/**
+ * Diagnostic context for error reporting.
+ * Includes metadata to help identify and resolve issues.
+ */
+export interface ErrorContext {
+    /** Session ID where error occurred (if applicable) */
+    sessionId?: string;
+    /** Agent name (if applicable) */
+    agentName?: string;
+    /** Tool name (if tool execution error) */
+    toolName?: string;
+    /** Model being used (if model API error) */
+    model?: string;
+    /** Operation being performed when error occurred */
+    operation?: string;
+    /** Additional diagnostic data */
+    metadata?: Record<string, unknown>;
+    /** Stack trace from original error */
+    originalStack?: string;
+    /** Timestamp when error occurred */
+    timestamp: Date;
+}
+/**
+ * Base error class for all Squad SDK errors.
+ * Wraps SDK exceptions with Squad context and diagnostic information.
+ */
+export declare class SquadError extends Error {
+    readonly severity: ErrorSeverity;
+    readonly category: ErrorCategory;
+    readonly context: ErrorContext;
+    readonly recoverable: boolean;
+    readonly originalError?: Error;
+    /**
+     * Create a new Squad error.
+     *
+     * @param message - User-friendly error message
+     * @param severity - Error severity level
+     * @param category - Error category for routing
+     * @param context - Diagnostic context
+     * @param recoverable - Whether the operation can be retried
+     * @param originalError - Original SDK error (if wrapping)
+     */
+    constructor(message: string, severity: ErrorSeverity, category: ErrorCategory, context: ErrorContext, recoverable?: boolean, originalError?: Error);
+    /**
+     * Convert error to JSON for logging/telemetry.
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Get user-friendly error message with context.
+     */
+    getUserMessage(): string;
+}
+/**
+ * SDK connection error — failed to connect to Copilot SDK.
+ */
+export declare class SDKConnectionError extends SquadError {
+    constructor(message: string, context: ErrorContext, originalError?: Error);
+}
+/**
+ * Session lifecycle error — failed to create, resume, or close a session.
+ */
+export declare class SessionLifecycleError extends SquadError {
+    constructor(message: string, context: ErrorContext, recoverable?: boolean, originalError?: Error);
+}
+/**
+ * Tool execution error — custom tool failed during execution.
+ */
+export declare class ToolExecutionError extends SquadError {
+    constructor(message: string, context: ErrorContext, originalError?: Error);
+}
+/**
+ * Model API error — LLM API call failed.
+ */
+export declare class ModelAPIError extends SquadError {
+    constructor(message: string, context: ErrorContext, recoverable?: boolean, originalError?: Error);
+}
+/**
+ * Configuration error — invalid or missing configuration.
+ */
+export declare class ConfigurationError extends SquadError {
+    constructor(message: string, context: ErrorContext, originalError?: Error);
+}
+/**
+ * Authentication error — auth failure (token, permissions).
+ */
+export declare class AuthenticationError extends SquadError {
+    constructor(message: string, context: ErrorContext, originalError?: Error);
+}
+/**
+ * Rate limit error — API rate limit exceeded.
+ */
+export declare class RateLimitError extends SquadError {
+    readonly retryAfter?: number;
+    constructor(message: string, context: ErrorContext, retryAfter?: number, originalError?: Error);
+    getUserMessage(): string;
+}
+/**
+ * Runtime error — internal Squad runtime failure.
+ */
+export declare class RuntimeError extends SquadError {
+    constructor(message: string, context: ErrorContext, originalError?: Error);
+}
+/**
+ * Validation error — invalid input or parameters.
+ */
+export declare class ValidationError extends SquadError {
+    constructor(message: string, context: ErrorContext, originalError?: Error);
+}
+/**
+ * Factory for creating Squad errors from SDK errors.
+ * Maps SDK error patterns to appropriate Squad error types.
+ */
+export declare class ErrorFactory {
+    /**
+     * Wrap an SDK error with Squad context.
+     * Automatically detects error type and maps to appropriate Squad error class.
+     *
+     * @param error - Original SDK error
+     * @param context - Squad diagnostic context
+     * @returns Squad error with full context
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await session.sendMessage({ prompt: 'Hello' });
+     * } catch (err) {
+     *   throw ErrorFactory.wrap(err, {
+     *     sessionId: 'abc-123',
+     *     operation: 'sendMessage',
+     *     timestamp: new Date()
+     *   });
+     * }
+     * ```
+     */
+    static wrap(error: unknown, context: Partial<ErrorContext>): SquadError;
+}
+/**
+ * Telemetry data point for tracking operations.
+ */
+export interface TelemetryPoint {
+    /** Operation name */
+    operation: string;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Success or failure */
+    success: boolean;
+    /** Error category (if failed) */
+    errorCategory?: ErrorCategory;
+    /** Session ID */
+    sessionId?: string;
+    /** Agent name */
+    agentName?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Timestamp */
+    timestamp: Date;
+}
+/**
+ * Telemetry handler function.
+ */
+export type TelemetryHandler = (point: TelemetryPoint) => void | Promise<void>;
+/**
+ * Telemetry collector for tracking latency and error rates.
+ *
+ * Usage:
+ * ```typescript
+ * const telemetry = new TelemetryCollector();
+ *
+ * // Register handler
+ * telemetry.onData((point) => {
+ *   console.log(`${point.operation}: ${point.duration}ms`);
+ * });
+ *
+ * // Track operation
+ * const stopwatch = telemetry.start('session.create', { sessionId: 'abc-123' });
+ * try {
+ *   await createSession();
+ *   stopwatch.success();
+ * } catch (err) {
+ *   stopwatch.failure(err);
+ * }
+ * ```
+ */
+export declare class TelemetryCollector {
+    private handlers;
+    /**
+     * Register a telemetry data handler.
+     *
+     * @param handler - Handler function to receive telemetry points
+     * @returns Unsubscribe function
+     */
+    onData(handler: TelemetryHandler): () => void;
+    /**
+     * Start tracking an operation.
+     *
+     * @param operation - Operation name
+     * @param context - Additional context
+     * @returns Stopwatch object with success/failure methods
+     */
+    start(operation: string, context?: {
+        sessionId?: string;
+        agentName?: string;
+        metadata?: Record<string, unknown>;
+    }): {
+        success: () => void;
+        failure: (error: unknown) => void;
+    };
+    /**
+     * Clear all handlers.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/adapter/errors.d.ts.map

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

package/dist/adapter/errors.js

@@ -0,0 +1,362 @@
+/**
+ * SDK Error Hierarchy and Telemetry (M0-6, Issue #78)
+ *
+ * Wraps Copilot SDK errors with Squad-specific context and diagnostic information.
+ * Provides a comprehensive error hierarchy for SDK-specific exceptions.
+ * Includes basic telemetry hooks for latency tracking and error rate monitoring.
+ *
+ * @module adapter/errors
+ */
+// ============================================================================
+// Base Error Types
+// ============================================================================
+/**
+ * Error severity levels for classification and routing.
+ */
+export var ErrorSeverity;
+(function (ErrorSeverity) {
+    /** Informational — no action needed, logged for awareness */
+    ErrorSeverity["INFO"] = "info";
+    /** Warning — degraded functionality but operation can continue */
+    ErrorSeverity["WARNING"] = "warning";
+    /** Error — operation failed but system remains stable */
+    ErrorSeverity["ERROR"] = "error";
+    /** Critical — system stability at risk, requires immediate attention */
+    ErrorSeverity["CRITICAL"] = "critical";
+})(ErrorSeverity || (ErrorSeverity = {}));
+/**
+ * Error categories for diagnostic routing.
+ */
+export var ErrorCategory;
+(function (ErrorCategory) {
+    /** SDK connection or communication errors */
+    ErrorCategory["SDK_CONNECTION"] = "sdk_connection";
+    /** Session lifecycle errors (create, resume, close) */
+    ErrorCategory["SESSION_LIFECYCLE"] = "session_lifecycle";
+    /** Tool execution failures */
+    ErrorCategory["TOOL_EXECUTION"] = "tool_execution";
+    /** Model API call failures */
+    ErrorCategory["MODEL_API"] = "model_api";
+    /** Configuration errors */
+    ErrorCategory["CONFIGURATION"] = "configuration";
+    /** Authentication and authorization failures */
+    ErrorCategory["AUTH"] = "auth";
+    /** Rate limiting and quota errors */
+    ErrorCategory["RATE_LIMIT"] = "rate_limit";
+    /** Internal Squad runtime errors */
+    ErrorCategory["RUNTIME"] = "runtime";
+    /** Validation errors (invalid input) */
+    ErrorCategory["VALIDATION"] = "validation";
+    /** Unknown or uncategorized errors */
+    ErrorCategory["UNKNOWN"] = "unknown";
+})(ErrorCategory || (ErrorCategory = {}));
+/**
+ * Base error class for all Squad SDK errors.
+ * Wraps SDK exceptions with Squad context and diagnostic information.
+ */
+export class SquadError extends Error {
+    severity;
+    category;
+    context;
+    recoverable;
+    originalError;
+    /**
+     * Create a new Squad error.
+     *
+     * @param message - User-friendly error message
+     * @param severity - Error severity level
+     * @param category - Error category for routing
+     * @param context - Diagnostic context
+     * @param recoverable - Whether the operation can be retried
+     * @param originalError - Original SDK error (if wrapping)
+     */
+    constructor(message, severity, category, context, recoverable = false, originalError) {
+        super(message);
+        this.name = 'SquadError';
+        this.severity = severity;
+        this.category = category;
+        this.context = context;
+        this.recoverable = recoverable;
+        this.originalError = originalError;
+        // Maintain proper stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+        // Preserve original stack if available
+        if (originalError?.stack) {
+            this.context.originalStack = originalError.stack;
+        }
+    }
+    /**
+     * Convert error to JSON for logging/telemetry.
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            severity: this.severity,
+            category: this.category,
+            recoverable: this.recoverable,
+            context: this.context,
+            stack: this.stack,
+            originalError: this.originalError?.message
+        };
+    }
+    /**
+     * Get user-friendly error message with context.
+     */
+    getUserMessage() {
+        const parts = [this.message];
+        if (this.context.sessionId) {
+            parts.push(`(Session: ${this.context.sessionId})`);
+        }
+        if (this.context.agentName) {
+            parts.push(`(Agent: ${this.context.agentName})`);
+        }
+        if (this.recoverable) {
+            parts.push('— This error is recoverable. You may retry the operation.');
+        }
+        return parts.join(' ');
+    }
+}
+// ============================================================================
+// Specific Error Types
+// ============================================================================
+/**
+ * SDK connection error — failed to connect to Copilot SDK.
+ */
+export class SDKConnectionError extends SquadError {
+    constructor(message, context, originalError) {
+        super(message, ErrorSeverity.ERROR, ErrorCategory.SDK_CONNECTION, context, true, originalError);
+        this.name = 'SDKConnectionError';
+    }
+}
+/**
+ * Session lifecycle error — failed to create, resume, or close a session.
+ */
+export class SessionLifecycleError extends SquadError {
+    constructor(message, context, recoverable = false, originalError) {
+        super(message, ErrorSeverity.ERROR, ErrorCategory.SESSION_LIFECYCLE, context, recoverable, originalError);
+        this.name = 'SessionLifecycleError';
+    }
+}
+/**
+ * Tool execution error — custom tool failed during execution.
+ */
+export class ToolExecutionError extends SquadError {
+    constructor(message, context, originalError) {
+        super(message, ErrorSeverity.ERROR, ErrorCategory.TOOL_EXECUTION, context, false, originalError);
+        this.name = 'ToolExecutionError';
+    }
+}
+/**
+ * Model API error — LLM API call failed.
+ */
+export class ModelAPIError extends SquadError {
+    constructor(message, context, recoverable = true, originalError) {
+        super(message, ErrorSeverity.ERROR, ErrorCategory.MODEL_API, context, recoverable, originalError);
+        this.name = 'ModelAPIError';
+    }
+}
+/**
+ * Configuration error — invalid or missing configuration.
+ */
+export class ConfigurationError extends SquadError {
+    constructor(message, context, originalError) {
+        super(message, ErrorSeverity.ERROR, ErrorCategory.CONFIGURATION, context, false, originalError);
+        this.name = 'ConfigurationError';
+    }
+}
+/**
+ * Authentication error — auth failure (token, permissions).
+ */
+export class AuthenticationError extends SquadError {
+    constructor(message, context, originalError) {
+        super(message, ErrorSeverity.CRITICAL, ErrorCategory.AUTH, context, false, originalError);
+        this.name = 'AuthenticationError';
+    }
+}
+/**
+ * Rate limit error — API rate limit exceeded.
+ */
+export class RateLimitError extends SquadError {
+    retryAfter;
+    constructor(message, context, retryAfter, originalError) {
+        super(message, ErrorSeverity.WARNING, ErrorCategory.RATE_LIMIT, context, true, originalError);
+        this.name = 'RateLimitError';
+        this.retryAfter = retryAfter;
+    }
+    getUserMessage() {
+        const baseMessage = super.getUserMessage();
+        if (this.retryAfter) {
+            return `${baseMessage} Retry after ${this.retryAfter} seconds.`;
+        }
+        return baseMessage;
+    }
+}
+/**
+ * Runtime error — internal Squad runtime failure.
+ */
+export class RuntimeError extends SquadError {
+    constructor(message, context, originalError) {
+        super(message, ErrorSeverity.CRITICAL, ErrorCategory.RUNTIME, context, false, originalError);
+        this.name = 'RuntimeError';
+    }
+}
+/**
+ * Validation error — invalid input or parameters.
+ */
+export class ValidationError extends SquadError {
+    constructor(message, context, originalError) {
+        super(message, ErrorSeverity.ERROR, ErrorCategory.VALIDATION, context, false, originalError);
+        this.name = 'ValidationError';
+    }
+}
+// ============================================================================
+// Error Factory
+// ============================================================================
+/**
+ * Factory for creating Squad errors from SDK errors.
+ * Maps SDK error patterns to appropriate Squad error types.
+ */
+export class ErrorFactory {
+    /**
+     * Wrap an SDK error with Squad context.
+     * Automatically detects error type and maps to appropriate Squad error class.
+     *
+     * @param error - Original SDK error
+     * @param context - Squad diagnostic context
+     * @returns Squad error with full context
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await session.sendMessage({ prompt: 'Hello' });
+     * } catch (err) {
+     *   throw ErrorFactory.wrap(err, {
+     *     sessionId: 'abc-123',
+     *     operation: 'sendMessage',
+     *     timestamp: new Date()
+     *   });
+     * }
+     * ```
+     */
+    static wrap(error, context) {
+        const fullContext = {
+            timestamp: new Date(),
+            ...context
+        };
+        const originalError = error instanceof Error ? error : undefined;
+        const message = originalError?.message ?? String(error);
+        // Pattern matching on error message to categorize
+        if (message.includes('connection') || message.includes('ECONNREFUSED') || message.includes('ETIMEDOUT')) {
+            return new SDKConnectionError(`Failed to connect to Copilot SDK: ${message}`, fullContext, originalError);
+        }
+        if (message.includes('session') && (message.includes('create') || message.includes('resume'))) {
+            return new SessionLifecycleError(`Session lifecycle error: ${message}`, fullContext, true, originalError);
+        }
+        if (message.includes('auth') || message.includes('token') || message.includes('unauthorized')) {
+            return new AuthenticationError(`Authentication failed: ${message}`, fullContext, originalError);
+        }
+        if (message.includes('rate limit') || message.includes('429') || message.includes('quota')) {
+            const retryMatch = message.match(/retry after (\d+)/i);
+            const retryAfter = retryMatch ? parseInt(retryMatch[1], 10) : undefined;
+            return new RateLimitError(`Rate limit exceeded: ${message}`, fullContext, retryAfter, originalError);
+        }
+        if (message.includes('model') || message.includes('API') || message.includes('provider')) {
+            return new ModelAPIError(`Model API error: ${message}`, fullContext, true, originalError);
+        }
+        if (message.includes('config') || message.includes('invalid') || message.includes('missing')) {
+            return new ConfigurationError(`Configuration error: ${message}`, fullContext, originalError);
+        }
+        if (context.toolName) {
+            return new ToolExecutionError(`Tool execution failed: ${message}`, fullContext, originalError);
+        }
+        // Default to generic Squad error
+        return new SquadError(message, ErrorSeverity.ERROR, ErrorCategory.UNKNOWN, fullContext, false, originalError);
+    }
+}
+/**
+ * Telemetry collector for tracking latency and error rates.
+ *
+ * Usage:
+ * ```typescript
+ * const telemetry = new TelemetryCollector();
+ *
+ * // Register handler
+ * telemetry.onData((point) => {
+ *   console.log(`${point.operation}: ${point.duration}ms`);
+ * });
+ *
+ * // Track operation
+ * const stopwatch = telemetry.start('session.create', { sessionId: 'abc-123' });
+ * try {
+ *   await createSession();
+ *   stopwatch.success();
+ * } catch (err) {
+ *   stopwatch.failure(err);
+ * }
+ * ```
+ */
+export class TelemetryCollector {
+    handlers = new Set();
+    /**
+     * Register a telemetry data handler.
+     *
+     * @param handler - Handler function to receive telemetry points
+     * @returns Unsubscribe function
+     */
+    onData(handler) {
+        this.handlers.add(handler);
+        return () => this.handlers.delete(handler);
+    }
+    /**
+     * Start tracking an operation.
+     *
+     * @param operation - Operation name
+     * @param context - Additional context
+     * @returns Stopwatch object with success/failure methods
+     */
+    start(operation, context) {
+        const startTime = Date.now();
+        const timestamp = new Date();
+        const record = (success, errorCategory) => {
+            const duration = Date.now() - startTime;
+            const point = {
+                operation,
+                duration,
+                success,
+                errorCategory,
+                sessionId: context?.sessionId,
+                agentName: context?.agentName,
+                metadata: context?.metadata,
+                timestamp
+            };
+            for (const handler of this.handlers) {
+                try {
+                    const result = handler(point);
+                    if (result instanceof Promise) {
+                        result.catch((err) => console.error('Telemetry handler error:', err));
+                    }
+                }
+                catch (err) {
+                    console.error('Telemetry handler error:', err);
+                }
+            }
+        };
+        return {
+            success: () => record(true),
+            failure: (error) => {
+                const category = error instanceof SquadError ? error.category : ErrorCategory.UNKNOWN;
+                record(false, category);
+            }
+        };
+    }
+    /**
+     * Clear all handlers.
+     */
+    clear() {
+        this.handlers.clear();
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/adapter/errors.js.map

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