@aiagentflow/cli 0.6.1 → 0.7.0

package/dist/providers/provider-errors.js

@@ -0,0 +1,175 @@
+/**
+ * Shared error handling utilities for LLM providers.
+ *
+ * Provides actionable error messages, retry logic, and timeout
+ * handling so each provider doesn't duplicate this logic.
+ *
+ * Dependency direction: provider-errors.ts → core/errors.ts, utils/logger.ts
+ * Used by: anthropic.ts, openai.ts, gemini.ts, ollama.ts
+ */
+import { ProviderError } from '../core/errors.js';
+import { logger } from '../utils/logger.js';
+/** Default timeout for cloud provider requests (60 seconds). */
+export const PROVIDER_TIMEOUT_MS = 60_000;
+/** Ollama timeout — local models on CPU can be slow (5 minutes). */
+export const OLLAMA_TIMEOUT_MS = 300_000;
+/** Get an actionable hint for an HTTP error status code. */
+export function getHttpErrorHint(status, provider) {
+    if (status === 401 || status === 403) {
+        return `Check your ${provider} API key in .aiagentflow/config.json — run 'aiagentflow init' to reconfigure`;
+    }
+    if (status === 404) {
+        return 'Check the base URL in your configuration or verify the model name exists';
+    }
+    if (status === 429) {
+        return 'Rate limited — wait a moment and retry, or check your plan\'s rate limits';
+    }
+    if (status >= 500) {
+        return `${provider} is experiencing server issues — retry in a few seconds`;
+    }
+    return '';
+}
+/** Classify a network/connection error and return an actionable hint. */
+export function getConnectionErrorHint(err, provider, baseUrl) {
+    const code = getErrorCode(err);
+    const message = err instanceof Error ? err.message : String(err);
+    if (code === 'ECONNREFUSED' || message.includes('ECONNREFUSED')) {
+        if (provider === 'ollama') {
+            return `Cannot reach ${baseUrl} — is Ollama running? Start it with 'ollama serve'`;
+        }
+        return `Cannot reach ${baseUrl} — is the service running?`;
+    }
+    if (code === 'ENOTFOUND' || message.includes('ENOTFOUND') || message.includes('getaddrinfo')) {
+        return `DNS lookup failed for ${baseUrl} — check the URL in .aiagentflow/config.json`;
+    }
+    if (code === 'ETIMEDOUT' || code === 'UND_ERR_CONNECT_TIMEOUT' || message.includes('ETIMEDOUT')) {
+        return `Connection timed out to ${baseUrl} — check your network or try again`;
+    }
+    if (err instanceof Error && (err.name === 'AbortError' || err.name === 'TimeoutError')) {
+        return 'Request timed out — the server may be overloaded, try again';
+    }
+    return '';
+}
+/** Build a ProviderError with an actionable hint from an HTTP error. */
+export function buildHttpError(status, statusText, provider, errorBody) {
+    const hint = getHttpErrorHint(status, provider);
+    const label = getStatusLabel(status);
+    const message = hint
+        ? `${provider} API ${label} (${status}). ${hint}`
+        : `${provider} API error: ${status} ${statusText}`;
+    return new ProviderError(message, {
+        provider,
+        status,
+        body: errorBody,
+        ...(hint ? { hint } : {}),
+    });
+}
+/** Build a ProviderError with an actionable hint from a connection error. */
+export function buildConnectionError(err, provider, baseUrl) {
+    const hint = getConnectionErrorHint(err, provider, baseUrl);
+    const underlying = err instanceof Error ? err.message : String(err);
+    const message = hint
+        ? `Failed to connect to ${provider} API. ${hint}`
+        : `Failed to connect to ${provider} API: ${underlying}`;
+    return new ProviderError(message, {
+        provider,
+        baseUrl,
+        ...(hint ? { hint } : {}),
+    });
+}
+/** Check if an HTTP status code is retryable. */
+export function isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+/** Check if a network error is retryable. */
+function isRetryableNetworkError(err) {
+    const code = getErrorCode(err);
+    const retryableCodes = ['ECONNRESET', 'ECONNREFUSED', 'EPIPE', 'ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT'];
+    if (code && retryableCodes.includes(code))
+        return true;
+    if (err instanceof Error) {
+        if (err.name === 'AbortError' || err.name === 'TimeoutError')
+            return true;
+    }
+    return false;
+}
+/**
+ * Fetch with automatic retry, timeout, and actionable error messages.
+ *
+ * Retries on 429, 5xx, and transient network errors with exponential backoff.
+ * Throws ProviderError with actionable hints on final failure.
+ */
+export async function fetchWithRetry(url, init, options) {
+    const { provider, baseUrl, timeoutMs, maxRetries = 2 } = options;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            const response = await fetch(url, {
+                ...init,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (!response.ok) {
+                if (isRetryableStatus(response.status) && attempt < maxRetries) {
+                    const delay = getRetryDelay(response, attempt);
+                    logger.debug(`${provider} returned ${response.status}, retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries + 1})`);
+                    await sleep(delay);
+                    continue;
+                }
+                const errorBody = await response.text();
+                throw buildHttpError(response.status, response.statusText, provider, errorBody);
+            }
+            return response;
+        }
+        catch (err) {
+            // Re-throw our own errors
+            if (err instanceof ProviderError)
+                throw err;
+            if (isRetryableNetworkError(err) && attempt < maxRetries) {
+                const delay = 1000 * 2 ** attempt; // 1s, 2s, 4s
+                logger.debug(`${provider} connection failed, retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries + 1})`);
+                await sleep(delay);
+                continue;
+            }
+            throw buildConnectionError(err, provider, baseUrl);
+        }
+    }
+    // Unreachable, but satisfies TypeScript
+    throw new ProviderError(`${provider} request failed after ${maxRetries + 1} attempts`, { provider });
+}
+// ── Private helpers ──
+function getStatusLabel(status) {
+    if (status === 401)
+        return 'authentication failed';
+    if (status === 403)
+        return 'access denied';
+    if (status === 404)
+        return 'endpoint not found';
+    if (status === 429)
+        return 'rate limit exceeded';
+    if (status >= 500)
+        return 'server error';
+    return 'error';
+}
+function getErrorCode(err) {
+    if (err instanceof Error) {
+        // Node.js errors store code on the error itself or on cause
+        const nodeErr = err;
+        return nodeErr.code ?? nodeErr.cause?.code;
+    }
+    return undefined;
+}
+function getRetryDelay(response, attempt) {
+    // Respect Retry-After header if present
+    const retryAfter = response.headers.get('retry-after');
+    if (retryAfter) {
+        const seconds = Number(retryAfter);
+        if (!Number.isNaN(seconds) && seconds > 0 && seconds <= 60) {
+            return seconds * 1000;
+        }
+    }
+    // Exponential backoff: 1s, 2s, 4s
+    return 1000 * 2 ** attempt;
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=provider-errors.js.map

package/dist/providers/provider-errors.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiagentflow/cli",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "A local-first, CLI-driven multi-agent AI software engineering workflow orchestrator — feed specs, PRDs, and guidelines to auto-generate implementation plans and code",
   "type": "module",
   "bin": {