@aisa-one/cli 0.2.4 → 0.5.0

package/dist/json-text.js

@@ -0,0 +1,60 @@
+/**
+ * Parse application JSON while keeping number tokens as strings at their
+ * structural locations. Strings are copied with escapes so digits inside
+ * quotes are not treated as numbers.
+ *
+ * `--json` must keep using the original raw body; this is only for human
+ * rendering and local inspection.
+ */
+export function parseJsonKeepingNumberTokens(source) {
+    return JSON.parse(quoteNumberTokens(source));
+}
+export function quoteNumberTokens(source) {
+    let out = "";
+    let i = 0;
+    while (i < source.length) {
+        const c = source[i];
+        if (c === '"') {
+            const copied = copyJsonString(source, i);
+            out += copied.text;
+            i = copied.end;
+            continue;
+        }
+        if (c === "-" || (c >= "0" && c <= "9")) {
+            const match = source.slice(i).match(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/);
+            if (match) {
+                out += JSON.stringify(match[0]);
+                i += match[0].length;
+                continue;
+            }
+        }
+        out += c;
+        i++;
+    }
+    return out;
+}
+function copyJsonString(source, start) {
+    let i = start;
+    let text = source[i++];
+    while (i < source.length) {
+        const c = source[i++];
+        text += c;
+        if (c === "\\" && i < source.length) {
+            text += source[i++];
+            continue;
+        }
+        if (c === '"')
+            break;
+    }
+    return { text, end: i };
+}
+/** Exact token from a value produced by parseJsonKeepingNumberTokens. */
+export function numberToken(value) {
+    if (typeof value === "string" && /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(value)) {
+        return value;
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Number.isInteger(value) ? value.toString() : undefined;
+    }
+    return undefined;
+}

package/dist/router.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Deployed Tool Router origin (nginx / tools.aisa.one). Paths already include
+ * `/v1/tool-router/...`, so this is an origin, not the LLM `/v1` base.
+ * OpenAPI still lists api.aisa.one; that host 404s these paths.
+ */
+export declare const DEFAULT_ROUTER_URL = "https://tools.aisa.one";
+/** Origin/prefix before `/v1/tool-router/...`. Harness and tests set this. */
+export declare const ROUTER_URL_ENV = "AISA_ROUTER_BASE_URL";
+export declare const ROUTER_PATHS: {
+    readonly search: "/v1/tool-router/aisa-search-tool";
+    readonly schema: "/v1/tool-router/aisa-batch-get-schema";
+    readonly quote: "/v1/tool-router/aisa-batch-quote";
+    readonly call: "/v1/tool-router/aisa-batch-use";
+};
+export type RouterOperation = keyof typeof ROUTER_PATHS;
+/**
+ * Origin of the shared Tool Router HTTP service.
+ *
+ * Independent of resolveBases(): those rebuild `/v1` and `/apis/v1` for the
+ * LLM gateway and integration catalog. A test harness points this at a
+ * controlled Router via AISA_ROUTER_BASE_URL or config routerUrl.
+ */
+export declare function resolveRouterBase(): string;
+export interface RouterRequest {
+    operation: RouterOperation;
+    /** Raw application JSON. Sent unchanged so numeric tokens survive. */
+    body: string;
+    /** Bearer credential without the "Bearer " prefix, if any. */
+    apiKey?: string;
+}
+export interface RouterHttpResult {
+    status: number;
+    raw: string;
+}
+/**
+ * POST one Router operation. Never retries: quote and use are not safe to
+ * replay, and search/schema must not hide a failed attempt.
+ */
+export declare function routerPost(request: RouterRequest): Promise<RouterHttpResult>;

package/dist/router.js

@@ -0,0 +1,59 @@
+import { getConfig } from "./config.js";
+import { httpFetch } from "./utils/http.js";
+/**
+ * Deployed Tool Router origin (nginx / tools.aisa.one). Paths already include
+ * `/v1/tool-router/...`, so this is an origin, not the LLM `/v1` base.
+ * OpenAPI still lists api.aisa.one; that host 404s these paths.
+ */
+export const DEFAULT_ROUTER_URL = "https://tools.aisa.one";
+/** Origin/prefix before `/v1/tool-router/...`. Harness and tests set this. */
+export const ROUTER_URL_ENV = "AISA_ROUTER_BASE_URL";
+export const ROUTER_PATHS = {
+    search: "/v1/tool-router/aisa-search-tool",
+    schema: "/v1/tool-router/aisa-batch-get-schema",
+    quote: "/v1/tool-router/aisa-batch-quote",
+    call: "/v1/tool-router/aisa-batch-use",
+};
+/**
+ * Origin of the shared Tool Router HTTP service.
+ *
+ * Independent of resolveBases(): those rebuild `/v1` and `/apis/v1` for the
+ * LLM gateway and integration catalog. A test harness points this at a
+ * controlled Router via AISA_ROUTER_BASE_URL or config routerUrl.
+ */
+export function resolveRouterBase() {
+    const env = process.env[ROUTER_URL_ENV];
+    if (env && env.trim())
+        return stripTrailingSlash(env.trim());
+    const configured = getConfig("routerUrl");
+    if (typeof configured === "string" && configured.trim()) {
+        return stripTrailingSlash(configured.trim());
+    }
+    return DEFAULT_ROUTER_URL;
+}
+function stripTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+/**
+ * POST one Router operation. Never retries: quote and use are not safe to
+ * replay, and search/schema must not hide a failed attempt.
+ */
+export async function routerPost(request) {
+    const url = `${resolveRouterBase()}${ROUTER_PATHS[request.operation]}`;
+    const headers = {
+        "Content-Type": "application/json",
+        "x-aisa-source": "cli",
+    };
+    if (request.apiKey) {
+        headers.Authorization = `Bearer ${request.apiKey}`;
+    }
+    const res = await httpFetch(url, {
+        method: "POST",
+        headers,
+        body: request.body,
+        idempotent: false,
+        // Never follow: a 307/308 to aisa-batch-use would keep POST+body+auth.
+        redirect: "manual",
+    });
+    return { status: res.status, raw: await res.text() };
+}

package/dist/skills-registry.js

@@ -1,5 +1,6 @@
 import { readCache, writeCache, touchCache } from "./cache.js";
 import { pool } from "./utils/pool.js";
+import { httpFetch, INFO_TIMEOUT_MS } from "./utils/http.js";
 /**
  * GitHub-backed skill registry.
  *
@@ -76,8 +77,10 @@ async function loadSkillIndex(refresh) {
         return cached.data;
     let res;
     try {
-        res = await fetch(`${GH_API}/git/trees/main?recursive=1`, {
+        res = await httpFetch(`${GH_API}/git/trees/main?recursive=1`, {
             headers: ghHeaders(refresh ? undefined : cached?.etag),
+            idempotent: true,
+            timeoutMs: INFO_TIMEOUT_MS,
         });
     }
     catch (err) {
@@ -151,7 +154,10 @@ function skillMdBlob(slug, index) {
     return index.blobs[slug]?.find((b) => b.path === `${slug}/SKILL.md`);
 }
 export async function fetchSkillMarkdown(slug) {
-    const res = await fetch(`${GH_RAW}/${slug}/SKILL.md`);
+    const res = await httpFetch(`${GH_RAW}/${slug}/SKILL.md`, {
+        idempotent: true,
+        timeoutMs: INFO_TIMEOUT_MS,
+    });
     if (!res.ok)
         throw new Error(`Cannot read ${slug}/SKILL.md: ${res.status}`);
     return res.text();
@@ -203,7 +209,10 @@ export async function fetchSkillFiles(slug, index) {
     const blobs = index.blobs[slug] || [];
     const prefix = `${slug}/`;
     const results = await pool(blobs.map((blob) => async () => {
-        const res = await fetch(`${GH_RAW}/${blob.path}`);
+        const res = await httpFetch(`${GH_RAW}/${blob.path}`, {
+            idempotent: true,
+            timeoutMs: INFO_TIMEOUT_MS,
+        });
         if (!res.ok)
             throw new Error(`${blob.path}: ${res.status}`);
         return {

package/dist/utils/banner.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Print it, or don't — silence is the right answer more often than it looks.
+ *
+ * Nothing is drawn into a pipe: a banner in a log file or a CI transcript is
+ * noise that someone has to scroll past, and the escape codes make it worse.
+ * Nothing is drawn into a window too narrow to hold it either, because a
+ * wrapped banner is a smear, which is worse than no banner at all.
+ */
+export declare function printBanner(): void;

package/dist/utils/banner.js

@@ -0,0 +1,41 @@
+import chalk from "chalk";
+/**
+ * The two lines that open `aisa connect`.
+ *
+ * A banner is seen once with pleasure and then several hundred times, so the
+ * question is not which one looks best the first time but which one is still
+ * bearable the twentieth. That rules out the tall ones: six lines of block
+ * letters push the thing a person actually came to read below the fold, every
+ * single run.
+ *
+ * Two lines, 46 columns. AIsa in the brand orange, `connect` in grey beside
+ * it — the same order of importance the page gives them. Half-block glyphs,
+ * which every monospace font has, rather than a face that needs one.
+ */
+const AISA = ["▄▀█ █ █▀ ▄▀█", "█▀█ █ ▄█ █▀█"];
+const CONNECT = ["█▀▀ █▀█ █▄░█ █▄░█ █▀▀ █▀▀ ▀█▀", "█▄▄ █▄█ █░▀█ █░▀█ ██▄ █▄▄ ░█░"];
+/** Both halves plus the gap and the leading space. */
+const WIDTH = 1 + 12 + 3 + 29;
+/**
+ * Print it, or don't — silence is the right answer more often than it looks.
+ *
+ * Nothing is drawn into a pipe: a banner in a log file or a CI transcript is
+ * noise that someone has to scroll past, and the escape codes make it worse.
+ * Nothing is drawn into a window too narrow to hold it either, because a
+ * wrapped banner is a smear, which is worse than no banner at all.
+ */
+export function printBanner() {
+    if (!process.stdout.isTTY)
+        return;
+    if (process.env.NO_COLOR || process.env.CI)
+        return;
+    if ((process.stdout.columns || 80) < WIDTH + 2)
+        return;
+    const orange = chalk.hex("#c2410c");
+    const grey = chalk.hex("#a8a29e");
+    console.log("");
+    for (let i = 0; i < 2; i++) {
+        console.log(" " + orange.bold(AISA[i]) + "   " + grey(CONNECT[i]));
+    }
+    console.log("");
+}

package/dist/utils/browser.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Can this machine put a page in front of the person using it?
+ *
+ * Nobody should have to tell a tool it is on a server. Asking the user to
+ * pass a flag for it means asking them to know a word — "headless" — for a
+ * situation the machine can read for itself, and to know it before anything
+ * has gone wrong. The signals are unambiguous enough:
+ *
+ *   · a session that arrived over SSH has its browser at the other end of
+ *     the connection; opening one here puts it on a screen nobody is at
+ *   · a Linux box with no display server has no browser to open at all
+ *   · CI has nobody watching by definition
+ *
+ * Being wrong is cheap in one direction and not the other. Deciding we
+ * cannot open a browser when we could costs one printed URL. Deciding we
+ * can when we cannot leaves a person watching a terminal that is waiting
+ * for a click nobody will ever make.
+ */
+export declare function canOpenBrowser(): boolean;

package/dist/utils/browser.js

@@ -0,0 +1,31 @@
+/**
+ * Can this machine put a page in front of the person using it?
+ *
+ * Nobody should have to tell a tool it is on a server. Asking the user to
+ * pass a flag for it means asking them to know a word — "headless" — for a
+ * situation the machine can read for itself, and to know it before anything
+ * has gone wrong. The signals are unambiguous enough:
+ *
+ *   · a session that arrived over SSH has its browser at the other end of
+ *     the connection; opening one here puts it on a screen nobody is at
+ *   · a Linux box with no display server has no browser to open at all
+ *   · CI has nobody watching by definition
+ *
+ * Being wrong is cheap in one direction and not the other. Deciding we
+ * cannot open a browser when we could costs one printed URL. Deciding we
+ * can when we cannot leaves a person watching a terminal that is waiting
+ * for a click nobody will ever make.
+ */
+export function canOpenBrowser() {
+    // An explicit answer always wins — scripts, containers, and anyone whose
+    // setup we guessed wrong about.
+    if (process.env.AISA_NO_BROWSER)
+        return false;
+    if (process.env.SSH_CONNECTION || process.env.SSH_TTY || process.env.SSH_CLIENT)
+        return false;
+    if (process.env.CI)
+        return false;
+    if (process.platform === "darwin" || process.platform === "win32")
+        return true;
+    return Boolean(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+}

package/dist/utils/exec.d.ts

@@ -0,0 +1,43 @@
+import { type SpawnSyncReturns } from "node:child_process";
+/**
+ * Every child process this CLI starts goes through here.
+ *
+ * The reason is one bug we shipped twice: Node's `execFile` and `spawnSync`
+ * default to a 1 MB output buffer, and a global npm install prints more than
+ * that. On overflow Node kills the child and reports an error — after the
+ * package is already on disk — so a successful install read as a failure and
+ * the run went into a pointless retry (or hung waiting on it). Anything that
+ * shells out to a package manager, a vendor installer or an agent's own CLI
+ * can exceed 1 MB, so the buffer is raised in one place rather than
+ * remembered at 21 call sites.
+ *
+ * Timeouts live here too: a child with no timeout is a run that can hang for
+ * ever. Callers that legitimately need longer pass their own.
+ */
+/** Beyond anything an installer or a client CLI prints. */
+export declare const MAX_OUTPUT_BYTES: number;
+/** Enough for an agent install over a slow link; short of forever. */
+export declare const DEFAULT_TIMEOUT_MS = 300000;
+/** For a quick question to a local binary (`--version`, `mcp list`). */
+export declare const QUICK_TIMEOUT_MS = 20000;
+export interface RunOptions {
+    timeout?: number;
+    /** Passed through when a command must see specific variables. */
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+}
+/** Run a binary with arguments. Rejects on a non-zero exit, like execFile. */
+export declare function run(file: string, args: readonly string[], options?: RunOptions): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/** Run a shell command line (pipelines, `a; b`). Never rejects: the caller
+ *  decides what a non-zero exit means, which is almost never "give up". */
+export declare function runShell(command: string, options?: RunOptions): Promise<{
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    detail: string;
+}>;
+/** Ask a local binary something and wait for the answer. */
+export declare function runSync(file: string, args: readonly string[], options?: RunOptions): SpawnSyncReturns<string>;

package/dist/utils/exec.js

@@ -0,0 +1,61 @@
+import { execFile, spawnSync } from "node:child_process";
+import { promisify } from "node:util";
+/**
+ * Every child process this CLI starts goes through here.
+ *
+ * The reason is one bug we shipped twice: Node's `execFile` and `spawnSync`
+ * default to a 1 MB output buffer, and a global npm install prints more than
+ * that. On overflow Node kills the child and reports an error — after the
+ * package is already on disk — so a successful install read as a failure and
+ * the run went into a pointless retry (or hung waiting on it). Anything that
+ * shells out to a package manager, a vendor installer or an agent's own CLI
+ * can exceed 1 MB, so the buffer is raised in one place rather than
+ * remembered at 21 call sites.
+ *
+ * Timeouts live here too: a child with no timeout is a run that can hang for
+ * ever. Callers that legitimately need longer pass their own.
+ */
+/** Beyond anything an installer or a client CLI prints. */
+export const MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+/** Enough for an agent install over a slow link; short of forever. */
+export const DEFAULT_TIMEOUT_MS = 300_000;
+/** For a quick question to a local binary (`--version`, `mcp list`). */
+export const QUICK_TIMEOUT_MS = 20_000;
+const execFileRaw = promisify(execFile);
+/** Run a binary with arguments. Rejects on a non-zero exit, like execFile. */
+export function run(file, args, options = {}) {
+    return execFileRaw(file, [...args], {
+        timeout: options.timeout ?? DEFAULT_TIMEOUT_MS,
+        maxBuffer: MAX_OUTPUT_BYTES,
+        env: options.env,
+        cwd: options.cwd,
+        encoding: "utf8",
+    });
+}
+/** Run a shell command line (pipelines, `a; b`). Never rejects: the caller
+ *  decides what a non-zero exit means, which is almost never "give up". */
+export async function runShell(command, options = {}) {
+    try {
+        const { stdout, stderr } = await run("/bin/sh", ["-c", command], options);
+        return { ok: true, stdout, stderr, detail: "" };
+    }
+    catch (e) {
+        const err = e;
+        return {
+            ok: false,
+            stdout: err.stdout ?? "",
+            stderr: err.stderr ?? "",
+            detail: err.message.split("\n")[0],
+        };
+    }
+}
+/** Ask a local binary something and wait for the answer. */
+export function runSync(file, args, options = {}) {
+    return spawnSync(file, [...args], {
+        timeout: options.timeout ?? QUICK_TIMEOUT_MS,
+        maxBuffer: MAX_OUTPUT_BYTES,
+        env: options.env,
+        cwd: options.cwd,
+        encoding: "utf8",
+    });
+}

package/dist/utils/http.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Every HTTP request this CLI makes goes through here.
+ *
+ * Two things were missing from the bare `fetch` calls this replaces, and both
+ * were felt: no timeout, so a stalled connection hung the command with no way
+ * out; and no retry, so a single dropped packet surfaced as `Error: fetch
+ * failed` with nothing else to go on. Measured against the live gateway on
+ * 2026-08-24, roughly one call in three failed that way on a flaky link.
+ *
+ * This is the HTTP twin of utils/exec.ts, and exists for the same reason: the
+ * fix belongs in one place rather than being remembered at every call site.
+ *
+ * ── What is retried ────────────────────────────────────────────────────────
+ *
+ * Only requests the caller marks idempotent. That is not the same as "GET":
+ * this CLI sends POST for reads (tavily/scholar search, screener, MCP
+ * tools/list) *and* for writes (posting a tweet, minting a key, submitting a
+ * video job). Retrying the second group posts twice, mints two keys, or bills
+ * a second generation, so the default is one attempt and callers opt in.
+ *
+ * `chat` is deliberately left out of the opt-in even though a completion is
+ * semantically a read: it is billed per call, and a response lost after the
+ * server already produced it would charge the user twice. Better to let them
+ * decide to send it again.
+ *
+ * The proper fix for that last case is an `Idempotency-Key` header the gateway
+ * dedupes on (the Stripe model). That needs server-side support, so it is a
+ * cross-repo change for later, not something to fake here.
+ */
+/** 1 initial attempt + 2 retries. At the observed ~1/3 transient failure rate
+ *  this takes the odds of a command failing from ~33% to ~4%; a fourth attempt
+ *  only reaches ~1% and makes every genuine failure slower to report. */
+export declare const MAX_ATTEMPTS = 3;
+/** Catalog, health and other /info reads — small payloads from a CDN edge. */
+export declare const INFO_TIMEOUT_MS = 10000;
+/** A normal authenticated API call. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export interface HttpOptions extends RequestInit {
+    timeoutMs?: number;
+    /** Opt in to retries. See the note above: this must mean "safe to send
+     *  twice", not merely "does not modify anything". */
+    idempotent?: boolean;
+    /** Overrides MAX_ATTEMPTS; ignored unless idempotent. */
+    maxAttempts?: number;
+}
+/**
+ * Fetch with a timeout, and retries when the caller says it is safe.
+ *
+ * Throws the last error if every attempt failed at the network level; returns
+ * the last Response if the failures were HTTP statuses, so callers keep their
+ * existing error handling for 4xx/5xx bodies.
+ */
+export declare function httpFetch(url: string, options?: HttpOptions): Promise<Response>;

package/dist/utils/http.js

@@ -0,0 +1,124 @@
+/**
+ * Every HTTP request this CLI makes goes through here.
+ *
+ * Two things were missing from the bare `fetch` calls this replaces, and both
+ * were felt: no timeout, so a stalled connection hung the command with no way
+ * out; and no retry, so a single dropped packet surfaced as `Error: fetch
+ * failed` with nothing else to go on. Measured against the live gateway on
+ * 2026-08-24, roughly one call in three failed that way on a flaky link.
+ *
+ * This is the HTTP twin of utils/exec.ts, and exists for the same reason: the
+ * fix belongs in one place rather than being remembered at every call site.
+ *
+ * ── What is retried ────────────────────────────────────────────────────────
+ *
+ * Only requests the caller marks idempotent. That is not the same as "GET":
+ * this CLI sends POST for reads (tavily/scholar search, screener, MCP
+ * tools/list) *and* for writes (posting a tweet, minting a key, submitting a
+ * video job). Retrying the second group posts twice, mints two keys, or bills
+ * a second generation, so the default is one attempt and callers opt in.
+ *
+ * `chat` is deliberately left out of the opt-in even though a completion is
+ * semantically a read: it is billed per call, and a response lost after the
+ * server already produced it would charge the user twice. Better to let them
+ * decide to send it again.
+ *
+ * The proper fix for that last case is an `Idempotency-Key` header the gateway
+ * dedupes on (the Stripe model). That needs server-side support, so it is a
+ * cross-repo change for later, not something to fake here.
+ */
+/** 1 initial attempt + 2 retries. At the observed ~1/3 transient failure rate
+ *  this takes the odds of a command failing from ~33% to ~4%; a fourth attempt
+ *  only reaches ~1% and makes every genuine failure slower to report. */
+export const MAX_ATTEMPTS = 3;
+/** Catalog, health and other /info reads — small payloads from a CDN edge. */
+export const INFO_TIMEOUT_MS = 10_000;
+/** A normal authenticated API call. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+const BASE_BACKOFF_MS = 300;
+/** Agents fan out many calls at once; identical backoff would resynchronise
+ *  them into a second wave against a gateway that is already struggling. */
+const JITTER = 0.3;
+/** Transient by nature: the request never reached a decision, or the server
+ *  said it could not decide right now. 4xx is excluded on purpose — a bad key
+ *  or a malformed parameter fails the same way every time. */
+const RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504]);
+function backoffMs(attempt) {
+    const base = BASE_BACKOFF_MS * Math.pow(3, attempt - 1); // 300, 900
+    const spread = base * JITTER;
+    return Math.round(base - spread + Math.random() * spread * 2);
+}
+/** Honour the server's own instruction when it gives one — it knows how
+ *  overloaded it is far better than a fixed schedule does. Both the seconds
+ *  and the HTTP-date forms are allowed by RFC 9110. */
+function retryAfterMs(res) {
+    const raw = res.headers.get("retry-after");
+    if (!raw)
+        return undefined;
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const date = Date.parse(raw);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+/** Never wait longer than this on a Retry-After — a gateway asking for an hour
+ *  should end the command, not silently park it. */
+const MAX_RETRY_AFTER_MS = 30_000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Fetch with a timeout, and retries when the caller says it is safe.
+ *
+ * Throws the last error if every attempt failed at the network level; returns
+ * the last Response if the failures were HTTP statuses, so callers keep their
+ * existing error handling for 4xx/5xx bodies.
+ */
+export async function httpFetch(url, options = {}) {
+    const { timeoutMs = DEFAULT_TIMEOUT_MS, idempotent = false, maxAttempts, ...init } = options;
+    const attempts = idempotent ? (maxAttempts ?? MAX_ATTEMPTS) : 1;
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            const res = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+            if (attempt === attempts || !RETRYABLE_STATUS.has(res.status))
+                return res;
+            const after = retryAfterMs(res);
+            if (after !== undefined && after > MAX_RETRY_AFTER_MS)
+                return res;
+            await sleep(after ?? backoffMs(attempt));
+        }
+        catch (e) {
+            lastError = e;
+            if (attempt === attempts)
+                break;
+            await sleep(backoffMs(attempt));
+        }
+    }
+    throw asHelpfulError(lastError, url, attempts);
+}
+/**
+ * `TypeError: fetch failed` is what undici reports for DNS failures, refused
+ * connections, TLS errors and resets alike, and on its own it tells the user
+ * nothing they can act on. Name the host, say how many attempts were made,
+ * and keep the underlying cause attached.
+ */
+function asHelpfulError(cause, url, attempts) {
+    const host = (() => {
+        try {
+            return new URL(url).host;
+        }
+        catch {
+            return url;
+        }
+    })();
+    const err = cause;
+    const detail = err?.name === "TimeoutError" || err?.name === "AbortError"
+        ? "timed out"
+        : err?.cause?.code
+            ? `${err.cause.code}`
+            : (err?.message ?? "network error");
+    const tries = attempts > 1 ? ` after ${attempts} attempts` : "";
+    const wrapped = new Error(`Could not reach ${host}${tries} — ${detail}`);
+    if (cause instanceof Error)
+        wrapped.cause = cause;
+    return wrapped;
+}

package/dist/utils/install-method.d.ts

@@ -0,0 +1,36 @@
+/**
+ * How this copy of the CLI got onto the machine.
+ *
+ * `aisa update` used to run `npm install -g @aisa-one/cli@latest` no matter
+ * how the caller had installed it. For a pnpm or bun user that does not
+ * update anything — it installs a *second* copy under npm's prefix, which
+ * then shadows theirs or is shadowed by it depending on PATH order, and the
+ * version they see afterwards is whichever won. For someone running through
+ * `npx` it is stranger still: npx already resolves the latest published
+ * version on every invocation, so there was nothing to update in the first
+ * place and the command silently installed a global they never asked for.
+ *
+ * There is no manifest recording the installer, so this reads the one thing
+ * that does remember: where the running file sits on disk. Each package
+ * manager has its own place, and none of them look alike.
+ */
+export type InstallKind = "npx" | "npm" | "pnpm" | "bun" | "yarn" | "source" | "unknown";
+export interface InstallMethod {
+    kind: InstallKind;
+    /** The path the verdict was read from — worth printing when it is unknown. */
+    path: string;
+    /**
+     * What would update it, or undefined when nothing would: npx is current by
+     * definition, and a working copy is updated with git.
+     */
+    command?: string;
+}
+/**
+ * Read the verdict off a path.
+ *
+ * Separate from the caller so it can be tested against the shapes each
+ * manager produces without installing five package managers.
+ */
+export declare function classifyPath(p: string): InstallKind;
+/** Where this process is running from, and what would update it. */
+export declare function detectInstall(from?: string): InstallMethod;