@evolinkai/mcp 0.0.0-stage → 1.4.0

package/dist/core/src/services/api-client.js

@@ -0,0 +1,179 @@
+import { gatewayAuthHeaders } from '../config.js';
+import { classifyGatewayError, formatGatewayError } from './error-handler.js';
+import { DEFAULT_READ_TIMEOUT_MS, DEFAULT_SUBMIT_TIMEOUT_MS, MAX_RETRY_DELAY_MS, PaidRequestOutcomeUnknownError, RequestTimeoutError, evoHeaders, fetchWithTimeout, newRunId, parseRetryAfter, readJsonBody, responseRequestId, timeoutFromEnv, } from './http-policy.js';
+// --- Error class for HTTP-level failures ---
+export class ApiHttpError extends Error {
+    status;
+    retryAfterMs;
+    requestId;
+    info;
+    constructor(status, message, retryAfterMs, requestId, info) {
+        super(message);
+        this.status = status;
+        this.retryAfterMs = retryAfterMs;
+        this.requestId = requestId;
+        this.info = info;
+        this.name = 'ApiHttpError';
+    }
+}
+// --- Retry logic ---
+const RETRYABLE_STATUS_CODES = new Set([429, 502, 503]);
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function isRetryable(error) {
+    // Key and balance rejections are always HTTP 402, so they are never retried here.
+    if (error instanceof ApiHttpError)
+        return RETRYABLE_STATUS_CODES.has(error.status);
+    if (error instanceof PaidRequestOutcomeUnknownError)
+        return true;
+    if (error instanceof RequestTimeoutError)
+        return true;
+    if (error instanceof TypeError)
+        return true; // network errors (DNS, reset, …)
+    return false;
+}
+export async function withRetry(fn, retries, baseDelayMs) {
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < retries && isRetryable(error)) {
+                const retryAfterMs = error instanceof ApiHttpError ? error.retryAfterMs : undefined;
+                await sleep(Math.min(retryAfterMs ?? baseDelayMs * (attempt + 1), MAX_RETRY_DELAY_MS));
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw lastError;
+}
+// --- Core request (no retry) ---
+async function rawRequest(config, options) {
+    const url = `${config.baseUrl}${options.path}`;
+    const headers = {
+        ...gatewayAuthHeaders(),
+        'Accept': 'application/json',
+        ...evoHeaders(options.tool ?? 'unknown'),
+    };
+    if (options.body)
+        headers['Content-Type'] = 'application/json';
+    if (options.idempotencyKey) {
+        headers['Idempotency-Key'] = options.idempotencyKey;
+        headers['X-Evo-Run-Id'] = options.idempotencyKey;
+    }
+    const isRead = options.method === 'GET' || !options.idempotencyKey;
+    let response;
+    try {
+        response = await fetchWithTimeout(url, {
+            method: options.method,
+            headers,
+            body: options.body ? JSON.stringify(options.body) : undefined,
+        }, options.timeoutMs ?? timeoutFromEnv(isRead ? 'EVOLINK_MCP_READ_TIMEOUT_MS' : 'EVOLINK_MCP_WRITE_TIMEOUT_MS', isRead ? DEFAULT_READ_TIMEOUT_MS : DEFAULT_SUBMIT_TIMEOUT_MS));
+    }
+    catch (error) {
+        if (!isRead)
+            throw new PaidRequestOutcomeUnknownError(error, options.idempotencyKey);
+        throw error;
+    }
+    const data = await readJsonBody(response);
+    const requestId = responseRequestId(response.headers);
+    if (!response.ok) {
+        const retryAfterMs = parseRetryAfter(response.headers.get('retry-after'));
+        const info = classifyGatewayError(response.status, data, retryAfterMs, requestId);
+        throw new ApiHttpError(response.status, formatGatewayError(info), retryAfterMs, info.request_id, info);
+    }
+    return { data: data, requestId, headers: response.headers };
+}
+/**
+ * Submit one paid intent. At most one transport retry, always with the same
+ * idempotency key, so the gateway ledger (Idempotency-Key) can return the
+ * original task instead of creating a second one.
+ */
+export async function submitTask(config, options) {
+    const idempotencyKey = options.idempotencyKey ?? newRunId();
+    const { data, requestId, headers } = await withRetry(() => rawRequest(config, {
+        method: 'POST',
+        path: options.path,
+        body: options.body,
+        tool: options.tool,
+        idempotencyKey,
+    }), 1, 500);
+    if (!data.request_id && requestId)
+        data.request_id = requestId;
+    if (headers.get('idempotency-replayed') === 'true')
+        data.idempotency_replayed = true;
+    return data;
+}
+/** @deprecated kept for callers outside the tools; use submitTask. */
+export async function apiRequest(config, options) {
+    if (options.method !== 'POST' || !options.body) {
+        throw new Error('apiRequest only accepts generation POST operations');
+    }
+    return submitTask(config, { path: options.path, body: options.body, tool: options.tool ?? 'unknown' });
+}
+/** One task (GET /v1/tasks/{id}). Unfinished tasks sync with the provider on every read, so callers pace themselves. */
+export async function queryTask(config, taskId, tool = 'get_task') {
+    const { data, requestId } = await withRetry(() => rawRequest(config, { method: 'GET', path: `/v1/tasks/${encodeURIComponent(taskId)}`, tool }), 2, 1500);
+    if (!data.request_id && requestId)
+        data.request_id = requestId;
+    return data;
+}
+/** Up to 50 tasks in one call (POST /v1/tasks/batch); unknown or foreign IDs are simply absent. */
+export async function queryTasks(config, taskIds, tool = 'list_tasks') {
+    const { data } = await withRetry(() => rawRequest(config, {
+        method: 'POST',
+        path: '/v1/tasks/batch',
+        body: { task_ids: taskIds },
+        tool,
+    }), 2, 1500);
+    return Array.isArray(data.data) ? data.data : [];
+}
+/** The account's recent tasks, newest first (GET /v1/tasks). Items carry no result links. */
+export async function listTasks(config, query, tool = 'list_tasks') {
+    const params = new URLSearchParams();
+    if (query.status)
+        params.set('status', query.status);
+    if (query.type)
+        params.set('type', query.type);
+    if (query.model)
+        params.set('model', query.model);
+    params.set('page', String(query.page ?? 1));
+    params.set('page_size', String(query.pageSize ?? 20));
+    const { data } = await withRetry(() => rawRequest(config, { method: 'GET', path: `/v1/tasks?${params}`, tool }), 2, 1500);
+    return {
+        data: Array.isArray(data.data) ? data.data : [],
+        total: typeof data.total === 'number' ? data.total : 0,
+        page: typeof data.page === 'number' ? data.page : query.page ?? 1,
+        page_size: typeof data.page_size === 'number' ? data.page_size : query.pageSize ?? 20,
+    };
+}
+/**
+ * A short-lived upload token for a signed-in hosted connection (POST
+ * /v1/files/upload-token). The connection has no API key of its own, so
+ * files-api takes this token instead. Free; the gateway allows 30 a minute per
+ * account.
+ */
+export async function requestUploadToken(config, tool) {
+    const { data, requestId } = await withRetry(() => rawRequest(config, { method: 'POST', path: '/v1/files/upload-token', tool }), 1, 500);
+    const token = typeof data.upload_token === 'string' ? data.upload_token : '';
+    const expiresAt = typeof data.expires_at === 'number' ? data.expires_at : 0;
+    if (!token.startsWith('evup_') || expiresAt <= 0) {
+        const info = classifyGatewayError(500, { error: { message: 'EvoLink returned no upload token.' } }, undefined, requestId);
+        throw new ApiHttpError(500, formatGatewayError(info), undefined, requestId, info);
+    }
+    return { token, expiresAt };
+}
+/** Account balance and this key's usage (GET /v1/credits). */
+export async function getCredits(config, tool = 'check_balance') {
+    const { data, requestId } = await withRetry(() => rawRequest(config, { method: 'GET', path: '/v1/credits', tool }), 2, 1000);
+    if (data.success === false || !data.data?.user || !data.data?.token) {
+        const info = classifyGatewayError(500, { error: { message: data.message || 'The balance could not be read.' } }, undefined, requestId);
+        throw new ApiHttpError(500, formatGatewayError(info), undefined, requestId, info);
+    }
+    return data.data;
+}
+//# sourceMappingURL=api-client.js.map

package/dist/core/src/services/api-client.js.map

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

package/dist/core/src/services/error-handler.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What the assistant should do about a rejection. The gateway already tells
+ * the three quota cases apart by error.code (all are HTTP 402 with the same
+ * error.type), so classification goes by code first and status second.
+ *
+ * A signed-in connection spends the account's internal MCP key, so its key
+ * limits are the user's "EvoLink MCP limit" (mcp_*), never an API key's.
+ */
+export type ErrorCategory = 'account_balance_insufficient' | 'mcp_limit_reached' | 'mcp_daily_limit_reached' | 'mcp_paused' | 'mcp_key_expired' | 'key_quota_exhausted' | 'key_daily_quota_exhausted' | 'key_disabled' | 'key_expired' | 'model_not_allowed' | 'unauthorized' | 'forbidden' | 'rate_limited' | 'invalid_request' | 'not_found' | 'content_policy' | 'model_unavailable' | 'idempotency_conflict' | 'outcome_unknown' | 'request_too_large' | 'server_error' | 'connection_ended' | 'session_check_unavailable' | 'connection_setup_failed' | 'service_misconfigured' | 'sign_in_token_rejected' | 'mcp_channel_disabled' | 'account_disabled';
+export interface GatewayErrorInfo {
+    status: number;
+    category: ErrorCategory;
+    /**
+     * First sentence for the user when a limit, the balance or the connection
+     * stopped the request. It names which one, so every client can tell an
+     * EvoLink MCP limit from an empty account.
+     */
+    headline?: string;
+    code?: string;
+    message: string;
+    next_step: string;
+    retryable: boolean;
+    retry_after_seconds?: number;
+    action_url?: string;
+    request_id?: string;
+    /** Key name, balance and limit figures the gateway attaches to quota rejections (credits). */
+    details?: Record<string, unknown>;
+}
+/** Gateway display rate: 1 USD = 6.8 CNY and 1 CNY = 10 credits. */
+export declare const CREDITS_PER_USD = 68;
+export declare function formatCredits(value: number): string;
+export declare function formatUsd(value: number): string;
+/** Classifies one non-2xx gateway or files-api response. */
+export declare function classifyGatewayError(status: number, body: unknown, retryAfterMs?: number, headerRequestId?: string): GatewayErrorInfo;
+/**
+ * With a headline the first line says which limit it is; the gateway's own
+ * sentence is left out because it speaks of "API key …" even for the MCP key.
+ */
+export declare function formatGatewayError(info: GatewayErrorInfo): string;
+export declare function formatApiError(status: number, body: unknown): string;
+export type TaskErrorCode = 'content_policy_violation' | 'invalid_parameters' | 'image_dimension_mismatch' | 'image_processing_error' | 'request_cancelled' | 'resource_not_found' | 'generation_timeout' | 'quota_exceeded' | 'resource_exhausted' | 'generation_failed_no_content' | 'service_error' | 'service_unavailable' | 'unknown_error';
+export interface TaskErrorInfo {
+    suggestion: string;
+    retryable: boolean;
+}
+export declare function getTaskErrorInfo(code: string): TaskErrorInfo;
+export declare function formatTaskError(error: {
+    code?: string;
+    message?: string;
+}): string;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/core/src/services/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../../../../core/src/services/error-handler.ts"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GACrB,8BAA8B,GAC9B,mBAAmB,GACnB,yBAAyB,GACzB,YAAY,GACZ,iBAAiB,GACjB,qBAAqB,GACrB,2BAA2B,GAC3B,cAAc,GACd,aAAa,GACb,mBAAmB,GACnB,cAAc,GACd,WAAW,GACX,cAAc,GACd,iBAAiB,GACjB,WAAW,GACX,gBAAgB,GAChB,mBAAmB,GACnB,sBAAsB,GACtB,iBAAiB,GACjB,mBAAmB,GACnB,cAAc,GACd,kBAAkB,GAClB,2BAA2B,GAC3B,yBAAyB,GACzB,uBAAuB,GACvB,wBAAwB,GACxB,sBAAsB,GACtB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,aAAa,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,oEAAoE;AACpE,eAAO,MAAM,eAAe,KAAK,CAAC;AAwHlC,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK/C;AA6JD,4DAA4D;AAC5D,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,YAAY,CAAC,EAAE,MAAM,EACrB,eAAe,CAAC,EAAE,MAAM,GACvB,gBAAgB,CAuClB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAOjE;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAEpE;AAID,MAAM,MAAM,aAAa,GACrB,0BAA0B,GAC1B,oBAAoB,GACpB,0BAA0B,GAC1B,wBAAwB,GACxB,mBAAmB,GACnB,oBAAoB,GACpB,oBAAoB,GACpB,gBAAgB,GAChB,oBAAoB,GACpB,8BAA8B,GAC9B,eAAe,GACf,qBAAqB,GACrB,eAAe,CAAC;AAEpB,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAyDD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAM5D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAUlF"}

package/dist/core/src/services/error-handler.js

@@ -0,0 +1,403 @@
+import { currentCredentialMode } from '../request-context.js';
+import { API_KEYS_URL, MCP_CONSOLE_URL, MCP_KEY_NAME, TOP_UP_URL, siteUrl } from './http-policy.js';
+import { trackedLink } from './utm.js';
+/** Gateway display rate: 1 USD = 6.8 CNY and 1 CNY = 10 credits. */
+export const CREDITS_PER_USD = 68;
+const ACCOUNT_CODES = new Set(['insufficient_quota', 'insufficient_user_quota', 'quota_not_enough', 'account_balance_insufficient']);
+const KEY_QUOTA_CODES = new Set(['insufficient_token_quota', 'key_quota_exhausted']);
+const KEY_DAILY_CODES = new Set(['token_daily_quota_exceeded', 'key_daily_quota_exhausted']);
+const CONTENT_CODES = new Set(['content_policy_violation', 'content_filter', 'sensitive_content', 'moderation_blocked', 'input_moderation_failed']);
+const UNAVAILABLE_CODES = new Set(['no_available_channel', 'model_unavailable', 'channel_selection_failed', 'service_unavailable']);
+/** Hosted service channel (key custody A): the connection itself is gone and needs a new sign-in. */
+const CONNECTION_ENDED_CODES = new Set(['connection_not_found', 'connection_revoked', 'session_inactive', 'session_expired', 'mcp_scope_missing']);
+/** The hosted service, not the user's connection, was refused or sent a request the channel does not serve. */
+const SERVICE_CODES = new Set(['mcp_service_unauthorized', 'mcp_connection_required', 'mcp_route_not_allowed']);
+const DETAIL_FIELDS = [
+    'key_name',
+    'estimated_credits',
+    'account_balance_credits',
+    'total_limit_credits',
+    'used_credits',
+    'remaining_credits',
+    'daily_limit_credits',
+    'daily_used_credits',
+    'reset_timezone',
+    'allowed_models',
+    'expired_at',
+];
+function envelope(body) {
+    if (!body || typeof body !== 'object')
+        return {};
+    const record = body;
+    if (record.error && typeof record.error === 'object')
+        return record.error;
+    // files-api: { success: false, code, msg }; OAuth-style: { error: "x", error_description: "…" }
+    return {
+        code: typeof record.error === 'string' ? record.error : record.code,
+        message: record.msg ?? record.error_description ?? record.message,
+    };
+}
+function text(value) {
+    if (typeof value === 'string' && value.trim())
+        return value.trim();
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return undefined;
+}
+/**
+ * @param mcpLimits the key limits are the account's EvoLink MCP limit: a
+ *   signed-in connection, or the gateway said so with limit_scope "mcp".
+ */
+function categorize(status, code, mode, mcpLimits) {
+    const lower = code.toLowerCase();
+    if (ACCOUNT_CODES.has(lower))
+        return 'account_balance_insufficient';
+    if (KEY_QUOTA_CODES.has(lower))
+        return mcpLimits ? 'mcp_limit_reached' : 'key_quota_exhausted';
+    if (KEY_DAILY_CODES.has(lower))
+        return mcpLimits ? 'mcp_daily_limit_reached' : 'key_daily_quota_exhausted';
+    if (lower === 'mcp_paused')
+        return 'mcp_paused';
+    if (lower === 'mcp_key_expired')
+        return 'mcp_key_expired';
+    // EvoLink turned the MCP channel off (the gateway's MCPChannelEnabled switch): a 503, but not a model problem.
+    if (lower === 'mcp_channel_disabled')
+        return 'mcp_channel_disabled';
+    // The account's MCP key is only ever disabled by "pause all" in the console.
+    if (lower === 'key_disabled')
+        return mode === 'signed_in' ? 'mcp_paused' : 'key_disabled';
+    // A signed-in connection spends the account's MCP key, so an expired key is that key's expiry date, not the connection.
+    if (lower === 'key_expired')
+        return mode === 'signed_in' ? 'mcp_key_expired' : 'key_expired';
+    if (lower === 'key_model_not_allowed')
+        return 'model_not_allowed';
+    if (lower === 'idempotency_conflict')
+        return 'idempotency_conflict';
+    if (lower === 'paid_outcome_unknown')
+        return 'outcome_unknown';
+    if (CONTENT_CODES.has(lower))
+        return 'content_policy';
+    if (UNAVAILABLE_CODES.has(lower) || lower.startsWith('channel:'))
+        return 'model_unavailable';
+    if (CONNECTION_ENDED_CODES.has(lower))
+        return 'connection_ended';
+    if (lower === 'agent_session_unavailable')
+        return 'session_check_unavailable';
+    if (lower === 'mcp_connection_create_failed')
+        return 'connection_setup_failed';
+    if (SERVICE_CODES.has(lower))
+        return 'service_misconfigured';
+    // The gateway did not take the forwarded sign-in token, most likely because it expired during the call.
+    if (lower === 'mcp_token_invalid')
+        return 'sign_in_token_rejected';
+    if (lower === 'user_disabled')
+        return 'account_disabled';
+    // Upload tokens for signed-in connections (POST /v1/files/upload-token): a per-minute cap, and Redis being down.
+    if (lower === 'upload_token_rate_limited')
+        return 'rate_limited';
+    if (lower === 'upload_token_unavailable')
+        return 'server_error';
+    switch (status) {
+        case 401: return 'unauthorized';
+        case 402: return 'account_balance_insufficient';
+        case 403: return 'forbidden';
+        case 404: return 'not_found';
+        case 413: return 'request_too_large';
+        case 429: return 'rate_limited';
+        case 503: return 'model_unavailable';
+    }
+    if (status >= 500)
+        return 'server_error';
+    return 'invalid_request';
+}
+const RETRYABLE = new Set([
+    'key_daily_quota_exhausted',
+    'mcp_daily_limit_reached',
+    'rate_limited',
+    'model_unavailable',
+    'outcome_unknown',
+    'server_error',
+    'session_check_unavailable',
+    'connection_setup_failed',
+    'sign_in_token_rejected',
+]);
+/** Answers about the account's EvoLink MCP limit; their console link is the MCP settings, not API Keys. */
+const MCP_LIMIT_CATEGORIES = new Set(['mcp_limit_reached', 'mcp_daily_limit_reached', 'mcp_paused', 'mcp_key_expired']);
+const KEY_CATEGORIES = new Set([
+    'key_quota_exhausted', 'key_daily_quota_exhausted', 'key_disabled', 'key_expired', 'model_not_allowed',
+]);
+function credits(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return undefined;
+    return `${formatCredits(value)} credits (≈$${formatUsd(value / CREDITS_PER_USD)})`;
+}
+export function formatCredits(value) {
+    return Number(value.toFixed(4)).toString();
+}
+export function formatUsd(value) {
+    if (value === 0)
+        return '0';
+    if (Math.abs(value) >= 1)
+        return value.toFixed(2);
+    if (Math.abs(value) >= 0.01)
+        return value.toFixed(3);
+    return Number(value.toPrecision(2)).toString();
+}
+/** Sentences naming which limit stopped the request; the same words in every client. */
+function headlineFor(category) {
+    switch (category) {
+        case 'mcp_limit_reached':
+            return 'EvoLink MCP spending limit reached. This is the limit set for MCP, not your account balance.';
+        case 'mcp_daily_limit_reached':
+            return 'EvoLink MCP daily limit reached. It resets at midnight; this is not your account balance.';
+        case 'mcp_paused':
+            return 'EvoLink MCP is paused for this account. Resume it in the console; you do not need to reconnect.';
+        case 'mcp_key_expired':
+            return 'EvoLink MCP key has expired. Extend or clear its expiry date in the console; you do not need to reconnect.';
+        case 'account_balance_insufficient':
+            return 'Your EvoLink account balance is too low for this request. The balance is shared by API, web and MCP.';
+        case 'key_quota_exhausted':
+            return 'This API key\'s spending limit is used up. This is the key\'s own limit, not your account balance.';
+        case 'key_daily_quota_exhausted':
+            return 'This API key\'s daily limit is used up. It resets at midnight; this is not your account balance.';
+        case 'connection_ended':
+            return 'This EvoLink connection was disconnected. Reconnect EvoLink in this client.';
+        // The gateway's own text ("Agent session validation…") is shared with the CLI and names an internal check.
+        case 'session_check_unavailable':
+            return 'EvoLink could not check this connection\'s sign-in just now. Retry in a minute; you do not need to reconnect.';
+        default:
+            return undefined;
+    }
+}
+/**
+ * Where the EvoLink MCP limit lives: while it is a key in API Keys, name the key
+ * so the user finds it; a dedicated MCP page needs no key name.
+ */
+function mcpLimitPlace(url, details) {
+    return /\/dashboard\/keys(?:[?#]|$)/.test(url)
+        ? `${url} (the key named "${text(details.key_name) ?? MCP_KEY_NAME}")`
+        : url;
+}
+/** "Limit: …; used: …; left: …." from whatever figures the gateway attached. */
+function limitFigures(details, label) {
+    const parts = [
+        credits(details.total_limit_credits) && `${label}: ${credits(details.total_limit_credits)}`,
+        credits(details.used_credits) && `used: ${credits(details.used_credits)}`,
+        credits(details.remaining_credits) && `left: ${credits(details.remaining_credits)}`,
+    ].filter(Boolean);
+    return parts.length ? `${parts.join('; ')}.` : '';
+}
+function sentences(...parts) {
+    return parts.filter(Boolean).join(' ');
+}
+function nextStep(category, info, mode) {
+    const details = info.details ?? {};
+    const action = info.action_url;
+    const needed = credits(details.estimated_credits);
+    const balance = credits(details.account_balance_credits);
+    const zone = text(details.reset_timezone);
+    switch (category) {
+        case 'account_balance_insufficient':
+            return sentences(balance && `Balance: ${balance}.`, needed && `This request needs about ${needed}.`, `Ask the user to top up at ${action ?? trackedLink(TOP_UP_URL, 'top_up')}, then retry.`);
+        case 'mcp_limit_reached':
+            return sentences(limitFigures(details, 'EvoLink MCP limit'), needed && `This request needs about ${needed}.`, balance && `Account balance: ${balance} (not the problem).`, `Ask the user to raise or remove the EvoLink MCP limit at ${mcpLimitPlace(action ?? trackedLink(MCP_CONSOLE_URL, 'api_keys'), details)}; it is shared by every assistant connected to their EvoLink account.`, 'Do not retry until they have changed it.');
+        case 'mcp_daily_limit_reached': {
+            const used = credits(details.daily_used_credits);
+            const limit = credits(details.daily_limit_credits);
+            return sentences(used && limit && `Today's EvoLink MCP spending: ${used} of the ${limit} daily limit.`, `It resets automatically at midnight${zone ? ` (${zone})` : ''}.`, balance && `Account balance: ${balance} (not the problem).`, `To continue today, ask the user to raise the EvoLink MCP daily limit at ${mcpLimitPlace(action ?? trackedLink(MCP_CONSOLE_URL, 'api_keys'), details)}.`);
+        }
+        case 'mcp_paused':
+            return `Ask the user to resume EvoLink MCP at ${mcpLimitPlace(action ?? trackedLink(MCP_CONSOLE_URL, 'api_keys'), details)} (switch it back on). Do not ask them to reconnect, and do not retry until it is resumed.`;
+        case 'mcp_key_expired': {
+            const expiredAt = typeof details.expired_at === 'number' && Number.isFinite(details.expired_at) && details.expired_at > 0
+                ? new Date(details.expired_at * 1000).toISOString().slice(0, 10)
+                : undefined;
+            return sentences(expiredAt && `The EvoLink MCP key expired on ${expiredAt} (UTC).`, `Ask the user to extend or clear the expiry date of the EvoLink MCP key at ${mcpLimitPlace(action ?? trackedLink(MCP_CONSOLE_URL, 'api_keys'), details)}.`, 'Do not ask them to reconnect, and do not retry until it is changed.');
+        }
+        case 'key_quota_exhausted': {
+            const name = text(details.key_name);
+            return sentences(limitFigures(details, name ? `Limit of API key "${name}"` : 'API key limit'), needed && `This request needs about ${needed}.`, balance && `Account balance: ${balance} (not the problem).`, `Raise this API key's limit at ${action ?? trackedLink(API_KEYS_URL, 'api_keys')}, or use another key.`);
+        }
+        case 'key_daily_quota_exhausted':
+            return `It resets automatically at midnight${zone ? ` (${zone})` : ''}; to continue today, raise this API key's daily limit at ${action ?? trackedLink(API_KEYS_URL, 'api_keys')}.`;
+        case 'key_disabled':
+            return `This API key is disabled. Enable it at ${action ?? trackedLink(API_KEYS_URL, 'api_keys')} or use another key.`;
+        case 'key_expired':
+            return `This API key has expired. Extend it at ${action ?? trackedLink(API_KEYS_URL, 'api_keys')} or use another key.`;
+        case 'model_not_allowed': {
+            const allowed = Array.isArray(details.allowed_models) ? details.allowed_models.slice(0, 20).join(', ') : '';
+            return `This key may not use this model.${allowed ? ` Allowed models: ${allowed}.` : ''} Pick an allowed model, or change the key's model list at ${action ?? trackedLink(API_KEYS_URL, 'api_keys')}.`;
+        }
+        case 'unauthorized':
+            if (mode === 'signed_in')
+                return 'The EvoLink connection was rejected. Ask the user to reconnect EvoLink in this client.';
+            return mode === 'api_key'
+                ? 'The API key was rejected. Ask the user to check the EvoLink API key configured in this client.'
+                : 'The API key was rejected. Check EVOLINK_API_KEY, or run `evolink login` again.';
+        case 'forbidden':
+            return 'Access to this resource is denied for this account.';
+        case 'rate_limited':
+            return `Too many requests. Wait ${info.retry_after_seconds ?? 30} seconds before retrying; do not loop paid submissions.`;
+        case 'invalid_request':
+            return 'Fix the parameter named in the message and retry. get_model lists every parameter with its allowed values.';
+        case 'not_found':
+            return 'Nothing matches this ID. Check it, or use list_tasks to find recent tasks.';
+        case 'content_policy':
+            return 'The prompt or input was blocked by content review. Rephrase it (no real people, brands, explicit or violent content) and retry.';
+        case 'model_unavailable':
+            return 'The model is temporarily unavailable. Retry in a minute, or pick another model with search_models.';
+        case 'idempotency_conflict':
+            return 'This client_request_id was already used for a different request. Use a new client_request_id for a new generation.';
+        case 'outcome_unknown':
+            return 'The earlier submission with this client_request_id is still being processed or its outcome is unknown. Do not submit it again with a new id: wait a minute and retry with the same client_request_id, or look it up with list_tasks.';
+        case 'request_too_large':
+            return 'The request is too large. Pass big files as links (a public URL, or one from upload_file where it is available) instead of inline data.';
+        case 'server_error':
+            return 'EvoLink had a temporary error. Retry in a minute; for paid generations check list_tasks first so the task is not submitted twice.';
+        case 'connection_ended':
+            return 'This EvoLink connection is no longer active (it was revoked, expired, or signed out). Ask the user to reconnect the existing EvoLink connection in this client instead of adding a new one.';
+        case 'session_check_unavailable':
+            return 'EvoLink sign-in verification is temporarily unavailable. Retry in a minute; do not reconnect.';
+        case 'connection_setup_failed':
+            return 'EvoLink could not set up this connection yet. Retry in a minute.';
+        case 'service_misconfigured':
+            return 'The EvoLink MCP service could not authenticate this request. This is a server-side problem, not the user\'s connection: do not reconnect, and try again later.';
+        case 'mcp_channel_disabled':
+            return 'EvoLink has temporarily turned off MCP access. Try again later; switching models, retrying right away or reconnecting will not help.';
+        case 'sign_in_token_rejected':
+            return 'EvoLink did not accept this connection\'s sign-in token; it may have just expired. Retry the call, which carries a refreshed token; if it keeps failing, ask the user to reconnect the existing EvoLink connection in this client.';
+        case 'account_disabled':
+            return 'This EvoLink account is disabled. Ask the user to contact EvoLink support.';
+    }
+}
+/** Classifies one non-2xx gateway or files-api response. */
+export function classifyGatewayError(status, body, retryAfterMs, headerRequestId) {
+    const error = envelope(body);
+    const code = text(error.code);
+    const mode = currentCredentialMode();
+    const mcpScope = text(error.limit_scope)?.toLowerCase() === 'mcp';
+    const category = categorize(status, code ?? '', mode, mcpScope || mode === 'signed_in');
+    const requestId = text(error.request_id) ?? headerRequestId;
+    const rawMessage = text(error.message) ?? `HTTP ${status}`;
+    const message = rawMessage.replace(/\s*\(request id: [^)]*\)\s*$/i, '').slice(0, 600);
+    const details = {};
+    for (const field of DETAIL_FIELDS) {
+        if (error[field] !== undefined && error[field] !== null && error[field] !== '')
+            details[field] = error[field];
+    }
+    let actionUrl;
+    if (category === 'account_balance_insufficient') {
+        actionUrl = trackedLink(siteUrl(text(error.action_url), TOP_UP_URL), 'top_up');
+    }
+    else if (MCP_LIMIT_CATEGORIES.has(category)) {
+        actionUrl = trackedLink(siteUrl(text(error.action_url), MCP_CONSOLE_URL), 'api_keys');
+    }
+    else if (KEY_CATEGORIES.has(category)) {
+        actionUrl = trackedLink(siteUrl(text(error.action_url), API_KEYS_URL), 'api_keys');
+    }
+    const headline = headlineFor(category);
+    const info = {
+        status,
+        category,
+        ...(headline ? { headline } : {}),
+        code,
+        message,
+        next_step: '',
+        retryable: RETRYABLE.has(category),
+        retry_after_seconds: retryAfterMs !== undefined ? Math.max(1, Math.ceil(retryAfterMs / 1000)) : undefined,
+        action_url: actionUrl,
+        request_id: requestId,
+        details: Object.keys(details).length > 0 ? details : undefined,
+    };
+    info.next_step = nextStep(category, info, mode);
+    return info;
+}
+/**
+ * With a headline the first line says which limit it is; the gateway's own
+ * sentence is left out because it speaks of "API key …" even for the MCP key.
+ */
+export function formatGatewayError(info) {
+    const status = `${info.status}${info.code ? ` ${info.code}` : ''}`;
+    const lines = info.headline
+        ? [info.headline, `Next step: ${info.next_step}`, `Error: HTTP ${status}`]
+        : [`[${status}] ${info.message}`, `Next step: ${info.next_step}`];
+    if (info.request_id)
+        lines.push(`Request ID: ${info.request_id}`);
+    return lines.join('\n');
+}
+export function formatApiError(status, body) {
+    return formatGatewayError(classifyGatewayError(status, body));
+}
+const TASK_ERROR_MAP = {
+    content_policy_violation: {
+        suggestion: 'Revise the prompt: avoid real person photos, celebrity names, copyrighted content, NSFW or violence. An illustration style often passes.',
+        retryable: false,
+    },
+    invalid_parameters: {
+        suggestion: 'Check the parameter values (prompt length, image size, duration, resolution) against get_model.',
+        retryable: false,
+    },
+    image_dimension_mismatch: {
+        suggestion: 'The input image does not match the requested aspect ratio. Resize it (for example 1280x720 for 16:9) or change the ratio.',
+        retryable: false,
+    },
+    image_processing_error: {
+        suggestion: 'The input image could not be processed. Use JPG, PNG or WebP under 10 MB at a publicly reachable URL (upload_file gives one).',
+        retryable: false,
+    },
+    request_cancelled: {
+        suggestion: 'The task was cancelled. Submit a new request if it was not intended.',
+        retryable: false,
+    },
+    resource_not_found: {
+        suggestion: 'The task or an input resource was not found or has expired. Check the IDs and links.',
+        retryable: false,
+    },
+    generation_timeout: {
+        suggestion: 'Generation timed out, probably under high load. Retry, or simplify the prompt or lower the resolution.',
+        retryable: true,
+    },
+    quota_exceeded: {
+        suggestion: `The account was over quota or rate limited when the task ran. Wait, then retry; top up at ${TOP_UP_URL} if the balance is low.`,
+        retryable: true,
+    },
+    resource_exhausted: {
+        suggestion: 'Provider capacity was temporarily exhausted. Wait 30–60 seconds and retry.',
+        retryable: true,
+    },
+    generation_failed_no_content: {
+        suggestion: 'The model produced no output, often because of protected content or watermark removal requests. Change the prompt or input and retry.',
+        retryable: true,
+    },
+    service_error: {
+        suggestion: 'Temporary service error. Retry after a minute.',
+        retryable: true,
+    },
+    service_unavailable: {
+        suggestion: 'The service was temporarily unavailable. Retry after 1–2 minutes.',
+        retryable: true,
+    },
+    unknown_error: {
+        suggestion: 'Unknown error. Retry after a minute; if it keeps failing, give the task ID to EvoLink support.',
+        retryable: true,
+    },
+};
+export function getTaskErrorInfo(code) {
+    const info = TASK_ERROR_MAP[code] ?? TASK_ERROR_MAP.unknown_error;
+    // The top-up link is tagged for the caller when the hint is shown, not when the table is built.
+    return info.suggestion.includes(TOP_UP_URL)
+        ? { ...info, suggestion: info.suggestion.replace(TOP_UP_URL, trackedLink(TOP_UP_URL, 'top_up')) }
+        : info;
+}
+export function formatTaskError(error) {
+    const code = error.code ?? 'unknown_error';
+    const info = getTaskErrorInfo(code);
+    const lines = [
+        `Error code: ${code}`,
+        `Message: ${error.message ?? 'No details provided'}`,
+        `Retryable: ${info.retryable ? 'Yes — you can retry this request' : 'No — modify your input before retrying'}`,
+        `Suggestion: ${info.suggestion}`,
+    ];
+    return lines.join('\n');
+}
+//# sourceMappingURL=error-handler.js.map