jaitus 0.3.12 → 0.3.13

package/src/api.js

@@ -1,140 +1,174 @@
-// ─── Talking to Jaitus ──────────────────────────────────────────────────────────
-//
-// The CLI is the only client of the gateway. Every failure it gets back is turned into
-// a JaitusError here, at the edge, so no caller ever has an HTTP body in its hands to
-// print — see errors.js for why that matters.
-
-import { endpoints } from './config.js';
-import { signedIn, withAuth } from './session.js';
-import { fromGatewayBody, fromNetwork, JaitusError } from './errors.js';
-
-export class NotSignedIn extends Error {}
-
-// fetch() has no timeout of its own, and the gateway's worst case is minutes of
-// serial failover across provider keys — so a sick window used to pin the CLI on
-// "Working..." forever. Every call below carries its own ceiling: slow becomes a
-// `timeout` JaitusError (retryable by the agent loop, shown with a request id)
-// instead of eternity. The caller's signal (Esc) still wins: it aborts through the
-// same controller, and only a genuine user abort reads as one.
-const MESSAGES_TIMEOUT_MS = 10 * 60 * 1000; // streamed turns can legitimately run minutes
-const API_TIMEOUT_MS = 30 * 1000;           // dashboard calls are small JSON
-
-// Combine an optional caller signal with a timeout into one signal.
-// Manual combine (not AbortSignal.any): .any needs Node 20.3+, this works everywhere.
-function withTimeout(signal, ms) {
-  const ctrl = new AbortController();
-  let timedOut = false;
-  const timer = setTimeout(() => {
-    timedOut = true;
-    try { ctrl.abort(new DOMException('Request timed out', 'TimeoutError')); }
-    catch { try { ctrl.abort(); } catch { /* already gone */ } }
-  }, ms);
-  if (timer.unref) timer.unref();
-  const onAbort = () => {
-    clearTimeout(timer);
-    try { ctrl.abort(signal.reason); } catch { try { ctrl.abort(); } catch { /* already gone */ } }
-  };
-  if (signal) {
-    if (signal.aborted) onAbort();
-    else signal.addEventListener('abort', onAbort, { once: true });
-  }
-  return {
-    signal: ctrl.signal,
-    // True only when OUR timer fired. A user abort also lands here as an AbortError,
-    // but signal.aborted is set then — never mistake Esc for a timeout.
-    timedOut: () => timedOut && !signal?.aborted,
-    cleanup: () => { clearTimeout(timer); signal?.removeEventListener?.('abort', onAbort); },
-  };
-}
-
-function timeoutError() {
-  return new JaitusError({ code: 'timeout', status: 504, message: 'Jaitus took too long to respond. Try again.' });
-}
-
-// The context window the gateway last advertised, or null before it has been asked.
-let contextWindowSeen = null;
-export const advertisedContextWindow = () => contextWindowSeen;
-
-export function createClient() {
-  const { baseUrl } = endpoints();
-  if (!signedIn()) throw new NotSignedIn('Not signed in. Run `jaitus login` first.');
-
-  // x-jaitus-features: what this build understands, so the gateway can use newer error
-  // codes (a used-up usage window) without an older CLI reading them as "went wrong".
-  const base = { 'Content-Type': 'application/json', 'user-agent': 'jaitus-cli', 'x-jaitus-features': 'usage-window' };
-  const headers = (token) => ({ ...base, authorization: `Bearer ${token}` });
-
-  return {
-    baseUrl,
-
-    /** POST /v1/messages. Returns the raw Response so the caller can stream it. */
-    async messages(body, { signal } = {}) {
-      // The timer is deliberately NOT cleared when headers arrive: a stall can happen
-      // mid-body too (headers fast, tokens never come), and only the stream reader ends
-      // that. Aborting a finished request is harmless; the timer never holds the
-      // process open (unref). 10 minutes: streamed agentic turns legitimately run long.
-      const t = withTimeout(signal, MESSAGES_TIMEOUT_MS);
-      try {
-        return await withAuth((token) => fetch(`${baseUrl}/v1/messages`, {
-          method: 'POST',
-          headers: headers(token),
-          body: JSON.stringify(body),
-          signal: t.signal,
-        }));
-      } catch (cause) {
-        if (cause?.name === 'JaitusError') throw cause;
-        if (t.timedOut()) throw timeoutError();
-        if (cause?.name === 'AbortError') throw cause;
-        throw fromNetwork(cause);
-      }
-    },
-
-    /** A dashboard API call, returning parsed JSON. */
-    async api(pathname, init = {}) {
-      const t = withTimeout(init.signal, API_TIMEOUT_MS);
-      let res;
-      try {
-        res = await withAuth((token) => fetch(`${baseUrl}/api${pathname}`, {
-          ...init,
-          headers: { ...headers(token), ...(init.headers || {}) },
-          signal: t.signal,
-        }));
-        const body = await res.json().catch(() => ({}));
-        return { ok: res.ok, status: res.status, body };
-      } catch (cause) {
-        if (cause?.name === 'JaitusError') throw cause;
-        if (t.timedOut()) throw timeoutError();
-        if (cause?.name === 'AbortError') throw cause;
-        throw fromNetwork(cause);
-      } finally {
-        t.cleanup();
-      }
-    },
-
-    /** Model ids the gateway advertises. */
-    async models() {
-      const t = withTimeout(undefined, API_TIMEOUT_MS);
-      let res;
-      try {
-        res = await withAuth((token) => fetch(`${baseUrl}/v1/models`, { headers: headers(token), signal: t.signal }));
-      } catch (cause) {
-        t.cleanup();
-        if (cause?.name === 'JaitusError') throw cause;
-        if (t.timedOut()) throw timeoutError();
-        if (cause?.name === 'AbortError') throw cause;
-        throw fromNetwork(cause);
-      }
-      const body = await res.json().catch(() => ({}));
-      t.cleanup();
-      if (!res.ok) throw fromGatewayBody(res.status, body, { requestId: res.headers.get('x-request-id') || '' });
-      const models = (body?.data || []).map((m) => m?.id).filter(Boolean);
-      // How much conversation fits, as the gateway computed it for this account.
-      const ctx = (body?.data || []).map((m) => Number(m?.context_window)).find((n) => n > 0);
-      if (ctx) contextWindowSeen = ctx;
-      // An empty list is a service fault, not something the user can fix — and naming
-      // the gateway's model map to them would be naming our internals.
-      if (!models.length) throw new JaitusError({ code: 'unavailable', status: 502 });
-      return models;
-    },
-  };
-}
+// ─── Talking to Jaitus ──────────────────────────────────────────────────────────
+//
+// The CLI is the only client of the gateway. Every failure it gets back is turned into
+// a JaitusError here, at the edge, so no caller ever has an HTTP body in its hands to
+// print — see errors.js for why that matters.
+
+import { endpoints } from './config.js';
+import { signedIn, withAuth } from './session.js';
+import { fromGatewayBody, fromNetwork, JaitusError } from './errors.js';
+
+export class NotSignedIn extends Error {}
+
+// fetch() has no timeout of its own, so a request the gateway never answered used to
+// pin the CLI on "Working..." forever. Every call below carries a deadline: slow
+// becomes a `timeout` JaitusError (retryable by the agent loop, shown with a request
+// id) instead of eternity. The caller's signal (Esc) still wins: it aborts through the
+// same controller, and only a genuine user abort reads as one.
+//
+// A turn is bounded by SILENCE, not by its length. Until the reply starts, the gateway
+// may be failing over between provider keys (each gets a 20-45 s budget), so the first
+// byte gets a few minutes. Once it starts, the gateway writes a heartbeat at least every
+// 10 s for as long as the provider is working, so 90 s without a single byte means the
+// connection is dead — while a long, healthy answer streams for as long as it needs.
+// (A fixed 10-minute ceiling on the whole request used to cut long answers off and
+// start them again from nothing.)
+// (Overridable only so the tests can drive a stall in under a second.)
+const FIRST_BYTE_TIMEOUT_MS = Number(process.env.JAITUS_FIRST_BYTE_MS) || 3 * 60 * 1000;
+const STREAM_IDLE_TIMEOUT_MS = Number(process.env.JAITUS_STREAM_IDLE_MS) || 90 * 1000;
+const API_TIMEOUT_MS = 30 * 1000;           // dashboard calls are small JSON
+
+// Combine an optional caller signal with a restartable deadline into one signal.
+// Manual combine (not AbortSignal.any): .any needs Node 20.3+, this works everywhere.
+function withTimeout(signal, ms) {
+  const ctrl = new AbortController();
+  let timedOut = false;
+  let timer = null;
+  const arm = (after) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      timedOut = true;
+      try { ctrl.abort(new DOMException('Request timed out', 'TimeoutError')); }
+      catch { try { ctrl.abort(); } catch { /* already gone */ } }
+    }, after);
+    if (timer.unref) timer.unref();
+  };
+  arm(ms);
+  const onAbort = () => {
+    clearTimeout(timer);
+    try { ctrl.abort(signal.reason); } catch { try { ctrl.abort(); } catch { /* already gone */ } }
+  };
+  if (signal) {
+    if (signal.aborted) onAbort();
+    else signal.addEventListener('abort', onAbort, { once: true });
+  }
+  return {
+    signal: ctrl.signal,
+    // True only when OUR timer fired. A user abort also lands here as an AbortError,
+    // but signal.aborted is set then — never mistake Esc for a timeout.
+    timedOut: () => timedOut && !signal?.aborted,
+    /** Start the deadline again from now (with a new length). */
+    restart: (after) => { if (!ctrl.signal.aborted) arm(after); },
+    cleanup: () => { clearTimeout(timer); signal?.removeEventListener?.('abort', onAbort); },
+  };
+}
+
+/**
+ * The response with its body watched for silence: every chunk restarts the idle
+ * deadline, and the end of the body (or the reader letting go of it) stops the timer
+ * and drops the caller's abort listener, so nothing outlives the request.
+ */
+function watchedResponse(res, t, idleMs) {
+  if (!res.body) { t.cleanup(); return res; }
+  t.restart(idleMs);
+  const body = res.body.pipeThrough(new TransformStream({
+    transform(chunk, controller) { t.restart(idleMs); controller.enqueue(chunk); },
+    flush() { t.cleanup(); },
+    cancel() { t.cleanup(); },
+  }));
+  return new Response(body, { status: res.status, statusText: res.statusText, headers: res.headers });
+}
+
+function timeoutError() {
+  return new JaitusError({ code: 'timeout', status: 504, message: 'Jaitus took too long to respond. Try again.' });
+}
+
+// The context window the gateway last advertised, or null before it has been asked.
+let contextWindowSeen = null;
+export const advertisedContextWindow = () => contextWindowSeen;
+
+export function createClient() {
+  const { baseUrl } = endpoints();
+  if (!signedIn()) throw new NotSignedIn('Not signed in. Run `jaitus login` first.');
+
+  // x-jaitus-features: what this build understands, so the gateway can use newer error
+  // codes (a used-up usage window) without an older CLI reading them as "went wrong".
+  const base = { 'Content-Type': 'application/json', 'user-agent': 'jaitus-cli', 'x-jaitus-features': 'usage-window' };
+  const headers = (token) => ({ ...base, authorization: `Bearer ${token}` });
+
+  return {
+    baseUrl,
+
+    /** POST /v1/messages. Returns the raw Response so the caller can stream it. */
+    async messages(body, { signal } = {}) {
+      const t = withTimeout(signal, FIRST_BYTE_TIMEOUT_MS);
+      let res;
+      try {
+        res = await withAuth((token) => fetch(`${baseUrl}/v1/messages`, {
+          method: 'POST',
+          headers: headers(token),
+          body: JSON.stringify(body),
+          signal: t.signal,
+        }));
+      } catch (cause) {
+        t.cleanup();
+        if (cause?.name === 'JaitusError') throw cause;
+        if (t.timedOut()) throw timeoutError();
+        if (cause?.name === 'AbortError') throw cause;
+        throw fromNetwork(cause);
+      }
+      // A mid-body stall (headers fast, then nothing) aborts the body; the reader sees
+      // an AbortError while the caller's signal is NOT aborted, and turns it into a
+      // timeout — keeping whatever already arrived (agent/loop.js).
+      return watchedResponse(res, t, STREAM_IDLE_TIMEOUT_MS);
+    },
+
+    /** A dashboard API call, returning parsed JSON. */
+    async api(pathname, init = {}) {
+      const t = withTimeout(init.signal, API_TIMEOUT_MS);
+      let res;
+      try {
+        res = await withAuth((token) => fetch(`${baseUrl}/api${pathname}`, {
+          ...init,
+          headers: { ...headers(token), ...(init.headers || {}) },
+          signal: t.signal,
+        }));
+        const body = await res.json().catch(() => ({}));
+        return { ok: res.ok, status: res.status, body };
+      } catch (cause) {
+        if (cause?.name === 'JaitusError') throw cause;
+        if (t.timedOut()) throw timeoutError();
+        if (cause?.name === 'AbortError') throw cause;
+        throw fromNetwork(cause);
+      } finally {
+        t.cleanup();
+      }
+    },
+
+    /** Model ids the gateway advertises. */
+    async models() {
+      const t = withTimeout(undefined, API_TIMEOUT_MS);
+      let res;
+      try {
+        res = await withAuth((token) => fetch(`${baseUrl}/v1/models`, { headers: headers(token), signal: t.signal }));
+      } catch (cause) {
+        t.cleanup();
+        if (cause?.name === 'JaitusError') throw cause;
+        if (t.timedOut()) throw timeoutError();
+        if (cause?.name === 'AbortError') throw cause;
+        throw fromNetwork(cause);
+      }
+      const body = await res.json().catch(() => ({}));
+      t.cleanup();
+      if (!res.ok) throw fromGatewayBody(res.status, body, { requestId: res.headers.get('x-request-id') || '' });
+      const models = (body?.data || []).map((m) => m?.id).filter(Boolean);
+      // How much conversation fits, as the gateway computed it for this account.
+      const ctx = (body?.data || []).map((m) => Number(m?.context_window)).find((n) => n > 0);
+      if (ctx) contextWindowSeen = ctx;
+      // An empty list is a service fault, not something the user can fix — and naming
+      // the gateway's model map to them would be naming our internals.
+      if (!models.length) throw new JaitusError({ code: 'unavailable', status: 502 });
+      return models;
+    },
+  };
+}

package/src/errors.js

@@ -1,106 +1,120 @@
-// ─── What the CLI says when something fails ─────────────────────────────────────
-//
-// The gateway answers every failure with a `jaitus_*` code from one catalog. This file
-// is the CLI's half of that contract: a code maps to a title and a hint written here,
-// and anything WITHOUT a known code — an HTML page from a proxy, a body in some other
-// shape, a code this build has never heard of — becomes "something went wrong in
-// Jaitus" plus the request id. The CLI never prints an error body it does not
-// recognise, because the only text that is safe to show is text we wrote.
-
-const CATALOG = {
-  auth_required: { title: 'Not signed in', hint: 'Type /login to sign in (or run `jaitus login`).' },
-  session_expired: { title: 'Signed out', hint: 'Type /login to sign in again (or run `jaitus login`).' },
-  account_suspended: { title: 'Account suspended', hint: 'Contact support if you think this is a mistake.' },
-  email_unverified: { title: 'Email not verified', hint: 'Open the verification link in your inbox, then retry.' },
-  free_limit_reached: { title: 'Free prompts used up', hint: 'Subscribe on the website, then retry this turn.' },
-  free_request_too_large: { title: 'Too large for the free plan', hint: 'Run /compact or start a new session, or subscribe.' },
-  plan_limit_reached: { title: 'Monthly allowance used', hint: 'It resets at the start of your next period, or upgrade on the website. /usage shows where you are.' },
-  rate_limited: { title: 'Slow down', hint: 'Wait a moment, then retry.' },
-  context_too_long: { title: 'Conversation too long', hint: 'Run /compact, or start a new session.' },
-  request_too_large: { title: 'Request too large', hint: 'Usually images: remove some, or run /compact to drop old ones. Images over 3.5 MB are shrunk automatically.' },
-  daily_limit_reached: { title: 'Usage limit reached', hint: 'It refills automatically. /usage shows where you are.' },
-  window_limit_reached: { title: 'This usage window is used up', hint: 'It refills when the window ends — the rest of your month is still there. /usage shows when.' },
-  token_expired: { title: 'Signed out', hint: 'Type /login to sign in again (or run `jaitus login`).' },
-  refresh_race: { title: 'Sign-in was being renewed', hint: 'Try again.' },
-  content_blocked: { title: 'Request refused', hint: 'Rephrase the request and try again.' },
-  bad_request: { title: 'Request not accepted', hint: 'Try again; if it repeats, run /debug and contact support.' },
-  model_unavailable: { title: 'Model unavailable', hint: 'Run /model to pick another.' },
-  busy: { title: 'Jaitus is busy', hint: 'Try again in a minute.' },
-  unavailable: { title: 'Jaitus is unavailable', hint: 'Try again shortly. `jaitus doctor` checks your side.' },
-  maintenance: { title: 'Down for maintenance', hint: 'Try again shortly.' },
-  timeout: { title: 'Timed out', hint: 'Try again.' },
-  interrupted: { title: 'Response interrupted', hint: 'Try again.' },
-  internal: { title: 'Something went wrong', hint: 'Try again; if it keeps happening, contact support with the request id.' },
-};
-
-const GENERIC = 'Something went wrong in Jaitus.';
-
-export class JaitusError extends Error {
-  constructor({ code = 'internal', message, status = 0, requestId = '', retryAfter = null } = {}) {
-    const known = Object.prototype.hasOwnProperty.call(CATALOG, code) ? code : 'internal';
-    super(message || GENERIC);
-    this.name = 'JaitusError';
-    this.code = known;
-    this.status = status;
-    this.requestId = requestId;
-    this.retryAfter = retryAfter;
-    this.title = CATALOG[known].title;
-    this.hint = CATALOG[known].hint;
-  }
-}
-
-/**
- * An error body from the gateway → a JaitusError.
- *
- * The gateway's message is shown ONLY when the body carries a recognised `jaitus_`
- * code, because only then is it guaranteed to be our wording (it may carry specifics,
- * like how many free prompts there were). Otherwise the message is ours, generic.
- */
-export function fromGatewayBody(status, body, { requestId = '', retryAfter = null } = {}) {
-  let parsed = body;
-  if (typeof body === 'string') {
-    try { parsed = JSON.parse(body); } catch { parsed = null; }
-  }
-  const err = parsed?.error || null;
-  const rawCode = String(err?.code || '');
-  const code = rawCode.startsWith('jaitus_') ? rawCode.slice(7) : '';
-  const known = code && Object.prototype.hasOwnProperty.call(CATALOG, code);
-  const id = String(parsed?.request_id || requestId || '');
-  return new JaitusError({
-    code: known ? code : 'internal',
-    message: known && typeof err?.message === 'string' && err.message.trim() ? err.message.trim() : GENERIC,
-    status,
-    requestId: id,
-    retryAfter,
-  });
-}
-
-/** A failed fetch Response → a JaitusError, reading the body once. */
-export async function fromResponse(res) {
-  const text = await res.text().catch(() => '');
-  const requestId = res.headers?.get?.('x-request-id') || '';
-  const retryAfter = Number(res.headers?.get?.('retry-after')) || null;
-  return fromGatewayBody(res.status, text, { requestId, retryAfter });
-}
-
-/**
- * fetch() threw before any response — the network, not the service. This is the one
- * failure where the true cause is on the user's side and worth naming plainly.
- */
-export function fromNetwork(cause) {
-  if (cause?.name === 'AbortError') return cause;
-  const error = new JaitusError({
-    code: 'unavailable',
-    message: 'Could not reach Jaitus. Check your internet connection.',
-  });
-  error.title = 'Cannot reach Jaitus';
-  error.hint = 'Check your connection, then run `jaitus doctor`.';
-  error.cause = cause;
-  return error;
-}
-
-export function isJaitusError(e) {
-  return e instanceof JaitusError || e?.name === 'JaitusError';
-}
-
-export const ERROR_CODES = Object.freeze(Object.keys(CATALOG));
+// ─── What the CLI says when something fails ─────────────────────────────────────
+//
+// The gateway answers every failure with a `jaitus_*` code from one catalog. This file
+// is the CLI's half of that contract: a code maps to a title and a hint written here,
+// and anything WITHOUT a known code — an HTML page from a proxy, a body in some other
+// shape, a code this build has never heard of — becomes "something went wrong in
+// Jaitus" plus the request id. The CLI never prints an error body it does not
+// recognise, because the only text that is safe to show is text we wrote.
+
+const CATALOG = {
+  auth_required: { title: 'Not signed in', hint: 'Type /login to sign in (or run `jaitus login`).' },
+  session_expired: { title: 'Signed out', hint: 'Type /login to sign in again (or run `jaitus login`).' },
+  account_suspended: { title: 'Account suspended', hint: 'Contact support if you think this is a mistake.' },
+  email_unverified: { title: 'Email not verified', hint: 'Open the verification link in your inbox, then retry.' },
+  free_limit_reached: { title: 'Free prompts used up', hint: 'Subscribe on the website, then retry this turn.' },
+  free_request_too_large: { title: 'Too large for the free plan', hint: 'Run /compact or start a new session, or subscribe.' },
+  plan_limit_reached: { title: 'Monthly allowance used', hint: 'It resets at the start of your next period, or upgrade on the website. /usage shows where you are.' },
+  rate_limited: { title: 'Slow down', hint: 'Wait a moment, then retry.' },
+  context_too_long: { title: 'Conversation too long', hint: 'Run /compact, or start a new session.' },
+  request_too_large: { title: 'Request too large', hint: 'Usually images: remove some, or run /compact to drop old ones. Images over 3.5 MB are shrunk automatically.' },
+  daily_limit_reached: { title: 'Usage limit reached', hint: 'It refills automatically. /usage shows where you are.' },
+  window_limit_reached: { title: 'This usage window is used up', hint: 'It refills when the window ends — the rest of your month is still there. /usage shows when.' },
+  token_expired: { title: 'Signed out', hint: 'Type /login to sign in again (or run `jaitus login`).' },
+  refresh_race: { title: 'Sign-in was being renewed', hint: 'Try again.' },
+  content_blocked: { title: 'Request refused', hint: 'Rephrase the request and try again.' },
+  bad_request: { title: 'Request not accepted', hint: 'Try again; if it repeats, run /debug and contact support.' },
+  model_unavailable: { title: 'Model unavailable', hint: 'Run /model to pick another.' },
+  busy: { title: 'Jaitus is busy', hint: 'Try again in a minute.' },
+  unavailable: { title: 'Jaitus is unavailable', hint: 'Try again shortly. `jaitus doctor` checks your side.' },
+  maintenance: { title: 'Down for maintenance', hint: 'Try again shortly.' },
+  timeout: { title: 'Timed out', hint: 'Try again.' },
+  interrupted: { title: 'Response interrupted', hint: 'Try again.' },
+  internal: { title: 'Something went wrong', hint: 'Try again; if it keeps happening, contact support with the request id.' },
+};
+
+const GENERIC = 'Something went wrong in Jaitus.';
+
+export class JaitusError extends Error {
+  constructor({ code = 'internal', message, status = 0, requestId = '', retryAfter = null } = {}) {
+    const known = Object.prototype.hasOwnProperty.call(CATALOG, code) ? code : 'internal';
+    super(message || GENERIC);
+    this.name = 'JaitusError';
+    this.code = known;
+    this.status = status;
+    this.requestId = requestId;
+    this.retryAfter = retryAfter;
+    this.title = CATALOG[known].title;
+    this.hint = CATALOG[known].hint;
+  }
+}
+
+/**
+ * An error body from the gateway → a JaitusError.
+ *
+ * The gateway's message is shown ONLY when the body carries a recognised `jaitus_`
+ * code, because only then is it guaranteed to be our wording (it may carry specifics,
+ * like how many free prompts there were). Otherwise the message is ours, generic.
+ */
+export function fromGatewayBody(status, body, { requestId = '', retryAfter = null } = {}) {
+  let parsed = body;
+  if (typeof body === 'string') {
+    try { parsed = JSON.parse(body); } catch { parsed = null; }
+  }
+  const err = parsed?.error || null;
+  const rawCode = String(err?.code || '');
+  const code = rawCode.startsWith('jaitus_') ? rawCode.slice(7) : '';
+  const known = code && Object.prototype.hasOwnProperty.call(CATALOG, code);
+  const id = String(parsed?.request_id || requestId || '');
+  // No Jaitus code on a gateway-class status: the answer came from the proxy in front of
+  // the gateway (its timeout page, a 502 while a deploy restarts the server), not from
+  // the gateway. Those are "not right now" — said plainly and retried — never the
+  // dead-end "Something went wrong" they used to read as.
+  if (!known && (status === 504 || status === 524)) {
+    return new JaitusError({ code: 'timeout', status, requestId: id, retryAfter, message: 'Jaitus took too long to answer and the connection was closed on the way. Try again.' });
+  }
+  if (!known && (status === 502 || status === 503 || (status >= 520 && status <= 530))) {
+    return new JaitusError({ code: 'unavailable', status, requestId: id, retryAfter, message: 'Jaitus could not be reached just now. Try again in a moment.' });
+  }
+  return new JaitusError({
+    code: known ? code : 'internal',
+    message: known && typeof err?.message === 'string' && err.message.trim() ? err.message.trim() : GENERIC,
+    status,
+    requestId: id,
+    retryAfter,
+  });
+}
+
+/** A failed fetch Response → a JaitusError, reading the body once. */
+export async function fromResponse(res) {
+  const text = await res.text().catch(() => '');
+  const requestId = res.headers?.get?.('x-request-id') || '';
+  const retryAfter = Number(res.headers?.get?.('retry-after')) || null;
+  const error = fromGatewayBody(res.status, text, { requestId, retryAfter });
+  // The gateway says trying again cannot help yet (e.g. no provider is switched on):
+  // report it at once instead of retrying behind "Working…".
+  if (res.headers?.get?.('x-jaitus-retry') === 'no') error.noRetry = true;
+  return error;
+}
+
+/**
+ * fetch() threw before any response — the network, not the service. This is the one
+ * failure where the true cause is on the user's side and worth naming plainly.
+ */
+export function fromNetwork(cause) {
+  if (cause?.name === 'AbortError') return cause;
+  const error = new JaitusError({
+    code: 'unavailable',
+    message: 'Could not reach Jaitus. Check your internet connection.',
+  });
+  error.title = 'Cannot reach Jaitus';
+  error.hint = 'Check your connection, then run `jaitus doctor`.';
+  error.cause = cause;
+  return error;
+}
+
+export function isJaitusError(e) {
+  return e instanceof JaitusError || e?.name === 'JaitusError';
+}
+
+export const ERROR_CODES = Object.freeze(Object.keys(CATALOG));