attocode 0.1.0

package/dist/src/providers/resilient-fetch.js

@@ -0,0 +1,208 @@
+/**
+ * Resilient Fetch Utility
+ *
+ * Provides network resilience for LLM provider requests:
+ * - Configurable timeout to prevent infinite hangs
+ * - Retry with exponential backoff for transient failures
+ * - Rate limit handling with Retry-After header parsing
+ * - Cancellation token support for user interrupts
+ */
+/**
+ * Error thrown when fetch fails after all retries.
+ */
+export class ResilientFetchError extends Error {
+    providerName;
+    attempts;
+    lastError;
+    isTimeout;
+    isCancelled;
+    constructor(message, providerName, attempts, lastError, isTimeout = false, isCancelled = false) {
+        super(message);
+        this.providerName = providerName;
+        this.attempts = attempts;
+        this.lastError = lastError;
+        this.isTimeout = isTimeout;
+        this.isCancelled = isCancelled;
+        this.name = 'ResilientFetchError';
+    }
+}
+// =============================================================================
+// DEFAULT CONFIG
+// =============================================================================
+const DEFAULT_CONFIG = {
+    timeout: 30000,
+    maxRetries: 3,
+    baseRetryDelay: 1000,
+    maxRetryDelay: 30000,
+    retryableStatusCodes: [429, 500, 502, 503, 504],
+};
+// =============================================================================
+// RESILIENT FETCH
+// =============================================================================
+/**
+ * Perform a fetch with timeout, retry, and cancellation support.
+ *
+ * @example
+ * ```typescript
+ * const { response, attempts, duration } = await resilientFetch({
+ *   url: 'https://api.anthropic.com/v1/messages',
+ *   init: { method: 'POST', headers: {...}, body: JSON.stringify(body) },
+ *   providerName: 'anthropic',
+ *   networkConfig: { timeout: 60000, maxRetries: 3 },
+ * });
+ * ```
+ */
+export async function resilientFetch(options) {
+    const { url, init, providerName, networkConfig = {}, cancellationToken, onRetry, } = options;
+    const config = { ...DEFAULT_CONFIG, ...networkConfig };
+    const startTime = Date.now();
+    let lastError;
+    let attempts = 0;
+    while (attempts < config.maxRetries) {
+        attempts++;
+        // Check for cancellation before each attempt
+        if (cancellationToken?.isCancelled) {
+            throw new ResilientFetchError(`Request cancelled by user`, providerName, attempts, lastError, false, true);
+        }
+        // Create AbortController for timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), config.timeout);
+        // Link external cancellation token
+        let cancelCleanup;
+        if (cancellationToken?.onCancel) {
+            cancellationToken.onCancel(() => controller.abort());
+            // Note: In a real implementation, you'd want proper cleanup here
+        }
+        try {
+            const response = await fetch(url, {
+                ...init,
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (cancelCleanup)
+                cancelCleanup();
+            // Check if response is retryable
+            if (config.retryableStatusCodes.includes(response.status)) {
+                // Parse Retry-After header for rate limits
+                const retryAfter = parseRetryAfter(response.headers.get('Retry-After'));
+                const delay = retryAfter ?? calculateBackoff(attempts, config);
+                lastError = new Error(`HTTP ${response.status}: ${response.statusText}`);
+                // Don't retry if this is the last attempt
+                if (attempts >= config.maxRetries) {
+                    throw new ResilientFetchError(`${providerName} request failed after ${attempts} attempts: HTTP ${response.status}`, providerName, attempts, lastError);
+                }
+                // Notify about retry
+                if (onRetry) {
+                    onRetry(attempts, delay, lastError);
+                }
+                await sleep(delay);
+                continue;
+            }
+            // Success (or non-retryable error - let caller handle)
+            return {
+                response,
+                attempts,
+                duration: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (cancelCleanup)
+                cancelCleanup();
+            // Handle abort (timeout or cancellation)
+            if (error instanceof Error && error.name === 'AbortError') {
+                if (cancellationToken?.isCancelled) {
+                    throw new ResilientFetchError(`Request cancelled by user`, providerName, attempts, error, false, true);
+                }
+                // Timeout
+                lastError = new Error(`Request timeout after ${config.timeout}ms`);
+                if (attempts >= config.maxRetries) {
+                    throw new ResilientFetchError(`${providerName} request timed out after ${attempts} attempts`, providerName, attempts, lastError, true);
+                }
+                const delay = calculateBackoff(attempts, config);
+                if (onRetry) {
+                    onRetry(attempts, delay, lastError);
+                }
+                await sleep(delay);
+                continue;
+            }
+            // Network error (ECONNREFUSED, DNS failure, etc.)
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (attempts >= config.maxRetries) {
+                throw new ResilientFetchError(`${providerName} network error after ${attempts} attempts: ${lastError.message}`, providerName, attempts, lastError);
+            }
+            const delay = calculateBackoff(attempts, config);
+            if (onRetry) {
+                onRetry(attempts, delay, lastError);
+            }
+            await sleep(delay);
+        }
+    }
+    // Should not reach here, but just in case
+    throw new ResilientFetchError(`${providerName} request failed after ${attempts} attempts`, providerName, attempts, lastError);
+}
+// =============================================================================
+// HELPERS
+// =============================================================================
+/**
+ * Parse Retry-After header value.
+ * Can be either a number of seconds or an HTTP-date.
+ */
+function parseRetryAfter(header) {
+    if (!header)
+        return null;
+    // Try parsing as number of seconds
+    const seconds = parseInt(header, 10);
+    if (!isNaN(seconds)) {
+        return seconds * 1000; // Convert to milliseconds
+    }
+    // Try parsing as HTTP-date
+    try {
+        const date = new Date(header);
+        const delay = date.getTime() - Date.now();
+        return delay > 0 ? delay : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Calculate exponential backoff delay with jitter.
+ */
+function calculateBackoff(attempt, config) {
+    // Exponential backoff: baseDelay * 2^(attempt-1)
+    const exponentialDelay = config.baseRetryDelay * Math.pow(2, attempt - 1);
+    // Add jitter (±25%)
+    const jitter = exponentialDelay * 0.25 * (Math.random() * 2 - 1);
+    const delay = exponentialDelay + jitter;
+    // Clamp to max delay
+    return Math.min(delay, config.maxRetryDelay);
+}
+/**
+ * Sleep for a given number of milliseconds.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// =============================================================================
+// UTILITIES
+// =============================================================================
+/**
+ * Check if an error is a resilient fetch error.
+ */
+export function isResilientFetchError(error) {
+    return error instanceof ResilientFetchError;
+}
+/**
+ * Check if an error is a timeout error.
+ */
+export function isTimeoutError(error) {
+    return isResilientFetchError(error) && error.isTimeout;
+}
+/**
+ * Check if an error is a cancellation error.
+ */
+export function isCancellationError(error) {
+    return isResilientFetchError(error) && error.isCancelled;
+}
+//# sourceMappingURL=resilient-fetch.js.map

package/dist/src/providers/resilient-fetch.js.map

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

package/dist/src/providers/types.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Lesson 2: Provider Abstraction Types
+ *
+ * Extended types that support multiple LLM providers.
+ */
+export interface Message {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+/**
+ * Options for chat requests.
+ */
+export interface ChatOptions {
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Temperature for randomness (0-1) */
+    temperature?: number;
+    /** Stop sequences */
+    stopSequences?: string[];
+    /** Model override (uses provider default if not specified) */
+    model?: string;
+}
+/**
+ * Response from chat request.
+ */
+export interface ChatResponse {
+    /** The assistant's response text */
+    content: string;
+    /** Why the response stopped */
+    stopReason: 'end_turn' | 'max_tokens' | 'stop_sequence';
+    /** Token usage (if available) */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        /** Tokens read from cache (for providers that support caching) */
+        cachedTokens?: number;
+        /** Actual cost from provider (when available, e.g., OpenRouter) */
+        cost?: number;
+    };
+}
+/**
+ * The core LLM provider interface.
+ * All providers must implement this.
+ */
+export interface LLMProvider {
+    /** Provider name for logging/debugging */
+    readonly name: string;
+    /** Default model used by this provider */
+    readonly defaultModel: string;
+    /**
+     * Send a chat request to the LLM.
+     * @param messages - Conversation history
+     * @param options - Optional configuration
+     */
+    chat(messages: Message[], options?: ChatOptions): Promise<ChatResponse>;
+    /**
+     * Check if the provider is properly configured.
+     */
+    isConfigured(): boolean;
+}
+/**
+ * Configuration for Anthropic provider.
+ */
+export interface AnthropicConfig {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+}
+/**
+ * Configuration for OpenAI provider.
+ */
+export interface OpenAIConfig {
+    apiKey: string;
+    model?: string;
+    organization?: string;
+    baseUrl?: string;
+}
+/**
+ * Configuration for Azure OpenAI provider.
+ */
+export interface AzureOpenAIConfig {
+    apiKey: string;
+    endpoint: string;
+    deployment: string;
+    apiVersion?: string;
+}
+/**
+ * Configuration for OpenRouter provider.
+ * OpenRouter provides access to 100+ models via a single API.
+ */
+export interface OpenRouterConfig {
+    apiKey: string;
+    model?: string;
+    siteUrl?: string;
+    siteName?: string;
+}
+/**
+ * Union of all provider configs.
+ */
+export type ProviderConfig = {
+    type: 'anthropic';
+    config: AnthropicConfig;
+} | {
+    type: 'openai';
+    config: OpenAIConfig;
+} | {
+    type: 'azure';
+    config: AzureOpenAIConfig;
+} | {
+    type: 'openrouter';
+    config: OpenRouterConfig;
+} | {
+    type: 'mock';
+    config?: undefined;
+};
+/**
+ * Base error for provider issues.
+ */
+export declare class ProviderError extends Error {
+    readonly provider: string;
+    readonly code: ProviderErrorCode;
+    readonly cause?: Error | undefined;
+    constructor(message: string, provider: string, code: ProviderErrorCode, cause?: Error | undefined);
+}
+export type ProviderErrorCode = 'NOT_CONFIGURED' | 'AUTHENTICATION_FAILED' | 'RATE_LIMITED' | 'CONTEXT_LENGTH_EXCEEDED' | 'INVALID_REQUEST' | 'SERVER_ERROR' | 'NETWORK_ERROR' | 'UNKNOWN';
+/**
+ * OpenAI-compatible tool definition schema.
+ * This is the format expected by OpenRouter for native tool calling.
+ *
+ * Why this format?
+ * - OpenRouter uses OpenAI's API format
+ * - Native tool use is more reliable than JSON parsing from text
+ * - Type safety: the LLM's tool calls are structured, not string parsing
+ */
+export interface ToolDefinitionSchema {
+    type: 'function';
+    function: {
+        /** Tool name - must match what the LLM should call */
+        name: string;
+        /** Description shown to LLM - critical for correct tool selection */
+        description: string;
+        /** JSON Schema for parameters */
+        parameters: Record<string, unknown>;
+        /** Enable strict schema validation (OpenAI feature) */
+        strict?: boolean;
+    };
+}
+/**
+ * Extended chat options that include tool definitions.
+ */
+export interface ChatOptionsWithTools extends ChatOptions {
+    /** Tool definitions in OpenAI format */
+    tools?: ToolDefinitionSchema[];
+    /**
+     * How the LLM should choose tools:
+     * - 'auto': LLM decides whether to use tools (default)
+     * - 'required': LLM must use at least one tool
+     * - 'none': Disable tool use for this request
+     * - { type: 'function', function: { name: 'X' } }: Force specific tool
+     */
+    tool_choice?: 'auto' | 'required' | 'none' | {
+        type: 'function';
+        function: {
+            name: string;
+        };
+    };
+}
+/**
+ * A tool call returned by the LLM.
+ * This is the native response format - no JSON parsing needed!
+ */
+export interface ToolCallResponse {
+    /** Unique ID for this tool call (used to match results) */
+    id: string;
+    type: 'function';
+    function: {
+        /** Which tool the LLM wants to call */
+        name: string;
+        /** Arguments as JSON string (needs JSON.parse) */
+        arguments: string;
+    };
+}
+/**
+ * Extended chat response that may include tool calls.
+ */
+export interface ChatResponseWithTools extends ChatResponse {
+    /** Tool calls requested by the LLM (if any) */
+    toolCalls?: ToolCallResponse[];
+}
+/**
+ * Message content that supports caching.
+ * Used for OpenRouter's cache_control feature on Anthropic models.
+ */
+export interface CacheableContent {
+    type: 'text';
+    text: string;
+    /** Mark this content for caching */
+    cache_control?: {
+        type: 'ephemeral';
+    };
+}
+/**
+ * Extended message that supports both string and structured content.
+ * Structured content allows for cache control markers.
+ */
+export interface MessageWithContent {
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string | CacheableContent[];
+    /** For tool result messages - matches the tool call ID */
+    tool_call_id?: string;
+    /** For tool result messages - the name of the tool (required for Gemini) */
+    name?: string;
+    /** For assistant messages - tool calls made */
+    tool_calls?: ToolCallResponse[];
+}
+/**
+ * Provider interface extended with native tool use.
+ * Providers that support tools implement this alongside LLMProvider.
+ */
+export interface LLMProviderWithTools extends LLMProvider {
+    /**
+     * Send a chat request with tool definitions.
+     * Returns structured tool calls instead of text that needs parsing.
+     */
+    chatWithTools(messages: (Message | MessageWithContent)[], options?: ChatOptionsWithTools): Promise<ChatResponseWithTools>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/providers/types.d.ts.map

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

package/dist/src/providers/types.js

@@ -0,0 +1,24 @@
+/**
+ * Lesson 2: Provider Abstraction Types
+ *
+ * Extended types that support multiple LLM providers.
+ */
+// =============================================================================
+// PROVIDER ERRORS
+// =============================================================================
+/**
+ * Base error for provider issues.
+ */
+export class ProviderError extends Error {
+    provider;
+    code;
+    cause;
+    constructor(message, provider, code, cause) {
+        super(message);
+        this.provider = provider;
+        this.code = code;
+        this.cause = cause;
+        this.name = 'ProviderError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/src/providers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmIH,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAGpB;IACA;IACA;IAJlB,YACE,OAAe,EACC,QAAgB,EAChB,IAAuB,EACvB,KAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,aAAQ,GAAR,QAAQ,CAAQ;QAChB,SAAI,GAAJ,IAAI,CAAmB;QACvB,UAAK,GAAL,KAAK,CAAQ;QAG7B,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF"}

package/dist/src/session-picker.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Session Resume Picker
+ *
+ * Displays recent sessions and allows user to select one to resume.
+ * Works with both SQLite and JSONL session stores.
+ */
+import type { SessionMetadata } from './integrations/session-store.js';
+export interface SessionPickerOptions {
+    maxSessions?: number;
+    showCost?: boolean;
+}
+export interface SessionPickerResult {
+    action: 'resume' | 'new' | 'cancel';
+    sessionId?: string;
+}
+/**
+ * Display sessions and let user pick one.
+ */
+export declare function showSessionPicker(sessions: SessionMetadata[], options?: SessionPickerOptions): Promise<SessionPickerResult>;
+/**
+ * Simple inline session picker (single line prompt).
+ */
+export declare function showQuickPicker(sessions: SessionMetadata[]): Promise<SessionPickerResult>;
+/**
+ * Format sessions for display (used by /sessions command).
+ */
+export declare function formatSessionsTable(sessions: SessionMetadata[], maxRows?: number): string;
+//# sourceMappingURL=session-picker.d.ts.map

package/dist/src/session-picker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-picker.d.ts","sourceRoot":"","sources":["../../src/session-picker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAmLvE,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,eAAe,EAAE,EAC3B,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAmD9B;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,eAAe,EAAE,GAC1B,OAAO,CAAC,mBAAmB,CAAC,CA0B9B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,eAAe,EAAE,EAC3B,OAAO,GAAE,MAAW,GACnB,MAAM,CA4BR"}