@juspay/neurolink 11.29.2 → 11.30.0

package/dist/cli/parser.js

@@ -23,6 +23,9 @@ import { ObservabilityCommandFactory } from "./commands/observability.js";
 import { TelemetryCommandFactory } from "./commands/telemetry.js";
 import { proxyStartCommand, proxyStatusCommand, proxyTelemetryCommand, proxySetupCommand, proxyGuardCommand, proxyInstallCommand, proxyUninstallCommand, } from "./commands/proxy.js";
 import { proxyAnalyzeCommand } from "./commands/proxyAnalyze.js";
+import { proxyShareCommand } from "./commands/proxyShare.js";
+import { proxyPeerCommand } from "./commands/proxyPeer.js";
+import { proxyExposeCommand } from "./commands/proxyExpose.js";
 import { proxyReplayCommand } from "./commands/proxyReplay.js";
 import { EvaluateCommandFactory } from "./commands/evaluate.js";
 import { TaskCommandFactory } from "./commands/task.js";
@@ -215,6 +218,9 @@ export function initializeCliParser() {
         builder: (yargs) => yargs
             .command(proxyStartCommand)
             .command(proxyStatusCommand)
+            .command(proxyShareCommand)
+            .command(proxyPeerCommand)
+            .command(proxyExposeCommand)
             .command(proxyAnalyzeCommand)
             .command(proxyReplayCommand)
             .command(proxyTelemetryCommand)
@@ -222,7 +228,7 @@ export function initializeCliParser() {
             .command(proxyGuardCommand)
             .command(proxyInstallCommand)
             .command(proxyUninstallCommand)
-            .demandCommand(1, "Please specify a proxy subcommand: start, status, analyze, replay <export|compare>, telemetry <setup|start|stop|status|logs|import-dashboard>, setup, guard, install, or uninstall"),
+            .demandCommand(1, "Please specify a proxy subcommand: start, status, share <create|provision|url|list|status|pause|resume|revoke|topup|set|link|rotate|level|note|notes|receipts|delete>, peer <add|request|sync|receipts|net|redeem|list|status|test|remove|pause|resume|set>, expose, analyze, replay <export|compare>, telemetry <setup|start|stop|status|logs|import-dashboard>, setup, guard, install, or uninstall"),
         handler: () => { },
     })
         // Evaluate Command Group - Using EvaluateCommandFactory

package/dist/proxy/peerStore.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Peers this node may borrow capacity from.
+ *
+ * The borrower's half of peer sharing. Each entry is a lender's exposed proxy
+ * plus the share token they issued; the lender remains the authority on what
+ * that token may do, so nothing here tries to second-guess a grant's policy.
+ *
+ * Peer cooldowns are kept here rather than in `accountCooldown.ts` on purpose.
+ * A peer is not an account: its unavailability reasons are grant-shaped
+ * ("paused", "exhausted") rather than window-shaped, and the account cooldown
+ * store's Anthropic quota keying is documented as label-based, which a peer key
+ * has no business participating in.
+ *
+ * @module proxy/peerStore
+ */
+import type { ProxyPeer, ProxyPeerCooldownReason, ProxyPeerInput, ProxyPeerObservation, ProxyPeerPendingProvision } from "../types/index.js";
+export declare function initPeerStore(peersFilePath: string): void;
+export declare function listPeers(): Promise<ProxyPeer[]>;
+export declare function getPeer(name: string): Promise<ProxyPeer | undefined>;
+/**
+ * Peers worth trying right now, in the order they should be tried.
+ *
+ * Disabled and cooling peers are dropped rather than sorted last: a borrowed
+ * request is already the fallback path, and spending its latency budget on a
+ * peer that just said "paused" helps nobody.
+ */
+export declare function selectBorrowablePeers(now?: number): Promise<ProxyPeer[]>;
+export declare function addPeer(input: ProxyPeerInput): Promise<ProxyPeer>;
+export declare function removePeer(name: string): Promise<boolean>;
+export declare function setPeerEnabled(name: string, enabled: boolean): Promise<ProxyPeer | undefined>;
+export declare function updatePeer(name: string, patch: {
+    priority?: number;
+    note?: string;
+    url?: string;
+    token?: string;
+    receiptSecret?: string;
+    reciprocalPeer?: string;
+    lastReceiptSequence?: number;
+    /** `null` clears an outstanding provisioning request. */
+    pendingProvision?: ProxyPeerPendingProvision | null;
+}): Promise<ProxyPeer | undefined>;
+/** How long a peer should be left alone after this kind of refusal. */
+export declare function peerCooldownMs(reason: ProxyPeerCooldownReason): number;
+/**
+ * Park a peer after a refusal.
+ *
+ * `retryAfterSeconds` from the lender wins when it is longer than our default —
+ * the lender knows when its window turns over and we do not — up to a week.
+ */
+export declare function coolPeer(name: string, reason: ProxyPeerCooldownReason, retryAfterSeconds?: number): Promise<void>;
+/** Clear a cooldown after a peer serves successfully. */
+export declare function recordPeerSuccess(name: string, observation?: ProxyPeerObservation): Promise<void>;

package/dist/proxy/peerStore.js

@@ -0,0 +1,324 @@
+/**
+ * Peers this node may borrow capacity from.
+ *
+ * The borrower's half of peer sharing. Each entry is a lender's exposed proxy
+ * plus the share token they issued; the lender remains the authority on what
+ * that token may do, so nothing here tries to second-guess a grant's policy.
+ *
+ * Peer cooldowns are kept here rather than in `accountCooldown.ts` on purpose.
+ * A peer is not an account: its unavailability reasons are grant-shaped
+ * ("paused", "exhausted") rather than window-shaped, and the account cooldown
+ * store's Anthropic quota keying is documented as label-based, which a peer key
+ * has no business participating in.
+ *
+ * @module proxy/peerStore
+ */
+import { readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { AsyncMutex } from "../utils/asyncMutex.js";
+import { logger } from "../utils/logger.js";
+import { writeJsonSnapshotAtomically } from "./snapshotPersistence.js";
+const PEERS_FILE = "proxy-peers.json";
+const RELOAD_TTL_MS = 1_000;
+/**
+ * How long a peer is left alone after each refusal kind.
+ *
+ * "Exhausted" and "withheld" are the lender's capacity talking, and that
+ * recovers on a window boundary rather than in seconds — retrying sooner just
+ * burns latency on every request. "Paused" is a human decision, so the wait is
+ * long but not punitive. Transport trouble gets the shortest wait, because it
+ * is the one most likely to clear on its own.
+ */
+const COOLDOWN_MS_BY_REASON = {
+    exhausted: 900_000,
+    withheld: 600_000,
+    paused: 300_000,
+    revoked: 86_400_000,
+    expired: 86_400_000,
+    unreachable: 60_000,
+    upstream_error: 120_000,
+};
+let customPeersFilePath = null;
+let cache = {};
+let cacheLoadedAt = 0;
+let cacheMtimeMs = -1;
+let cacheValid = false;
+const mutationMutex = new AsyncMutex();
+export function initPeerStore(peersFilePath) {
+    customPeersFilePath = peersFilePath;
+    cache = {};
+    cacheLoadedAt = 0;
+    cacheMtimeMs = -1;
+    cacheValid = false;
+}
+function getPeersFilePath() {
+    return customPeersFilePath ?? join(homedir(), ".neurolink", PEERS_FILE);
+}
+function isPeer(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.name === "string" &&
+        typeof candidate.url === "string" &&
+        typeof candidate.token === "string" &&
+        // Both are load-bearing on the read path and `addPeer` always writes them:
+        // `listPeers` sorts on `priority`, and a non-boolean `enabled` would drop
+        // the peer from `selectBorrowablePeers` with no explanation.
+        typeof candidate.priority === "number" &&
+        typeof candidate.enabled === "boolean");
+}
+/**
+ * Is this error simply "the file is not there yet"?
+ *
+ * The distinction is load-bearing. An absent file genuinely is an empty map —
+ * nothing has been written yet. Every *other* `stat`/read failure (`EACCES`,
+ * `EIO`, `EMFILE`, a full descriptor table) is a failure to observe the file,
+ * and answering one with an empty map is how a whole store gets erased: a
+ * caller passing `force` is about to `persist()` the map back over the real
+ * contents it just failed to read.
+ */
+function isMissingFileError(error) {
+    return error?.code === "ENOENT";
+}
+async function ensureLoaded(options = {}) {
+    const now = Date.now();
+    if (!options.force && cacheValid && now - cacheLoadedAt < RELOAD_TTL_MS) {
+        return;
+    }
+    const path = getPeersFilePath();
+    let mtimeMs;
+    try {
+        mtimeMs = (await stat(path)).mtimeMs;
+    }
+    catch (error) {
+        if (!isMissingFileError(error)) {
+            // Not "no file" but "could not look" — see `isMissingFileError`. Let it
+            // out: a mutation must abort rather than persist an empty map over a
+            // store it never managed to read.
+            throw error;
+        }
+        cache = {};
+        cacheMtimeMs = -1;
+        cacheLoadedAt = now;
+        cacheValid = true;
+        return;
+    }
+    // A forced load skips this. mtime is the fast path for a read, not a
+    // correctness check for a write: several filesystems stamp it at one-second
+    // granularity, so a write landing in the same second as our last read is
+    // indistinguishable from no write at all — and every caller passing `force`
+    // is about to persist the whole map back over whatever it missed.
+    if (!options.force && cacheValid && mtimeMs === cacheMtimeMs) {
+        cacheLoadedAt = now;
+        return;
+    }
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        cache = Object.fromEntries(Object.entries(parsed?.peers ?? {}).filter((entry) => isPeer(entry[1])));
+    }
+    catch (error) {
+        if (options.force) {
+            // A mutation is about to write the whole map back. Treating a corrupt
+            // file as empty here would make that write the thing that finishes the
+            // corruption off, so the mutation aborts and the file survives for a
+            // human to look at. Read paths below keep the tolerant behaviour.
+            throw error;
+        }
+        logger.always(`[proxy] peer list unreadable, treating as empty: ${error instanceof Error ? error.message : String(error)}`);
+        cache = {};
+    }
+    cacheMtimeMs = mtimeMs;
+    cacheLoadedAt = now;
+    cacheValid = true;
+}
+async function persist() {
+    const file = { schemaVersion: 1, peers: cache };
+    await writeJsonSnapshotAtomically(getPeersFilePath(), file);
+    try {
+        cacheMtimeMs = (await stat(getPeersFilePath())).mtimeMs;
+    }
+    catch {
+        cacheMtimeMs = -1;
+    }
+    cacheLoadedAt = Date.now();
+    cacheValid = true;
+}
+function normalizeName(name) {
+    return name.trim().toLowerCase();
+}
+export async function listPeers() {
+    await ensureLoaded();
+    return Object.values(cache).sort((a, b) => a.priority - b.priority || a.createdAt - b.createdAt);
+}
+export async function getPeer(name) {
+    await ensureLoaded();
+    return cache[normalizeName(name)];
+}
+/**
+ * Peers worth trying right now, in the order they should be tried.
+ *
+ * Disabled and cooling peers are dropped rather than sorted last: a borrowed
+ * request is already the fallback path, and spending its latency budget on a
+ * peer that just said "paused" helps nobody.
+ */
+export async function selectBorrowablePeers(now = Date.now()) {
+    const peers = await listPeers();
+    return peers.filter((peer) => peer.enabled && !(peer.cooldownUntil && peer.cooldownUntil > now));
+}
+export async function addPeer(input) {
+    return mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const key = normalizeName(input.name);
+        const now = Date.now();
+        const existing = cache[key];
+        const peer = {
+            schemaVersion: 1,
+            name: input.name.trim(),
+            url: input.url.replace(/\/+$/, ""),
+            token: input.token,
+            ...(input.receiptSecret
+                ? { receiptSecret: input.receiptSecret }
+                : existing?.receiptSecret
+                    ? { receiptSecret: existing.receiptSecret }
+                    : {}),
+            priority: input.priority ?? existing?.priority ?? 100,
+            enabled: existing?.enabled ?? true,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+            ...(input.note ? { note: input.note } : {}),
+        };
+        cache[key] = peer;
+        await persist();
+        return peer;
+    });
+}
+export async function removePeer(name) {
+    return mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const key = normalizeName(name);
+        if (!cache[key]) {
+            return false;
+        }
+        delete cache[key];
+        await persist();
+        return true;
+    });
+}
+export async function setPeerEnabled(name, enabled) {
+    return mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const key = normalizeName(name);
+        const peer = cache[key];
+        if (!peer) {
+            return undefined;
+        }
+        const updated = {
+            ...peer,
+            enabled,
+            updatedAt: Date.now(),
+            // Re-enabling clears the cooldown: the operator is explicitly saying to
+            // try again, and making them wait out a timer they can see would be a
+            // control that does not control anything.
+            ...(enabled ? { cooldownUntil: 0 } : {}),
+        };
+        cache[key] = updated;
+        await persist();
+        return updated;
+    });
+}
+export async function updatePeer(name, patch) {
+    return mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const key = normalizeName(name);
+        const peer = cache[key];
+        if (!peer) {
+            return undefined;
+        }
+        const updated = {
+            ...peer,
+            ...(patch.priority !== undefined ? { priority: patch.priority } : {}),
+            ...(patch.note !== undefined ? { note: patch.note } : {}),
+            ...(patch.url ? { url: patch.url.replace(/\/+$/, "") } : {}),
+            ...(patch.token ? { token: patch.token } : {}),
+            ...(patch.receiptSecret ? { receiptSecret: patch.receiptSecret } : {}),
+            ...(patch.reciprocalPeer ? { reciprocalPeer: patch.reciprocalPeer } : {}),
+            ...(patch.lastReceiptSequence !== undefined
+                ? { lastReceiptSequence: patch.lastReceiptSequence }
+                : {}),
+            updatedAt: Date.now(),
+        };
+        if (patch.pendingProvision !== undefined) {
+            if (patch.pendingProvision === null) {
+                delete updated.pendingProvision;
+            }
+            else {
+                updated.pendingProvision = patch.pendingProvision;
+            }
+        }
+        cache[key] = updated;
+        await persist();
+        return updated;
+    });
+}
+/** How long a peer should be left alone after this kind of refusal. */
+export function peerCooldownMs(reason) {
+    return COOLDOWN_MS_BY_REASON[reason];
+}
+/**
+ * The longest a peer is ever parked.
+ *
+ * A lender legitimately says "a week" when a weekly window is what recovers, but
+ * `retry-after` is a number from another machine and a malformed one would park
+ * a working peer effectively forever.
+ */
+const MAX_COOLDOWN_MS = 604_800_000;
+/**
+ * Park a peer after a refusal.
+ *
+ * `retryAfterSeconds` from the lender wins when it is longer than our default —
+ * the lender knows when its window turns over and we do not — up to a week.
+ */
+export async function coolPeer(name, reason, retryAfterSeconds) {
+    await mutationMutex.runExclusive(async () => {
+        // Force: `persist()` writes the whole map back, so a cooldown recorded on a
+        // TTL-fresh snapshot would revert a token rotation or a removal the CLI made
+        // in the window since this process last read the file.
+        await ensureLoaded({ force: true });
+        const key = normalizeName(name);
+        const peer = cache[key];
+        if (!peer) {
+            return;
+        }
+        const suggested = (retryAfterSeconds ?? 0) * 1000;
+        const until = Date.now() +
+            Math.min(MAX_COOLDOWN_MS, Math.max(peerCooldownMs(reason), Number.isFinite(suggested) ? suggested : 0));
+        cache[key] = {
+            ...peer,
+            cooldownUntil: until,
+            cooldownReason: reason,
+            updatedAt: Date.now(),
+        };
+        await persist();
+    });
+}
+/** Clear a cooldown after a peer serves successfully. */
+export async function recordPeerSuccess(name, observation) {
+    await mutationMutex.runExclusive(async () => {
+        await ensureLoaded({ force: true });
+        const key = normalizeName(name);
+        const peer = cache[key];
+        if (!peer) {
+            return;
+        }
+        cache[key] = {
+            ...peer,
+            cooldownUntil: 0,
+            lastUsedAt: Date.now(),
+            updatedAt: Date.now(),
+            ...(observation ? { lastObservation: observation } : {}),
+        };
+        await persist();
+    });
+}

package/dist/proxy/peerTransport.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Forwarding a borrowed request to a lender's proxy.
+ *
+ * The wire format is unchanged Anthropic Messages in both directions, so this is
+ * a passthrough, not a translation: the lender's proxy speaks exactly what the
+ * borrower's client already sent. That is what makes peer borrowing cheap
+ * compared with the provider fallback chain, which has to reshape the request
+ * for a different API.
+ *
+ * **Reading the refusal, not the status.** A lender's 429 can mean "your grant
+ * is spent" or "the upstream throttled me"; those want opposite reactions from
+ * the borrower. The distinction is carried in `x-neurolink-grant-reason`, so
+ * that header — not the status code — decides how long the peer is parked.
+ *
+ * @module proxy/peerTransport
+ */
+import type { ProxyPeer, ProxyPeerAttempt, ProxyPeerCooldownReason } from "../types/index.js";
+/**
+ * Map a lender's refusal to how long the peer should be left alone.
+ *
+ * Anything not recognized is treated as an upstream problem rather than a grant
+ * problem — the conservative reading, since it recovers soonest.
+ */
+export declare function peerReasonFromRefusal(grantReason: string | null): ProxyPeerCooldownReason;
+/**
+ * Send one request to one peer.
+ *
+ * On success the upstream `Response` is handed back with only an idle deadline
+ * wrapped around its body, so a stream keeps streaming — buffering it here
+ * would add the whole generation time to time-to-first-token on a path that is
+ * already a second hop.
+ */
+export declare function forwardToPeer(args: {
+    peer: ProxyPeer;
+    body: string;
+    stream: boolean;
+    signal?: AbortSignal;
+}): Promise<ProxyPeerAttempt>;

package/dist/proxy/peerTransport.js

@@ -0,0 +1,242 @@
+/**
+ * Forwarding a borrowed request to a lender's proxy.
+ *
+ * The wire format is unchanged Anthropic Messages in both directions, so this is
+ * a passthrough, not a translation: the lender's proxy speaks exactly what the
+ * borrower's client already sent. That is what makes peer borrowing cheap
+ * compared with the provider fallback chain, which has to reshape the request
+ * for a different API.
+ *
+ * **Reading the refusal, not the status.** A lender's 429 can mean "your grant
+ * is spent" or "the upstream throttled me"; those want opposite reactions from
+ * the borrower. The distinction is carried in `x-neurolink-grant-reason`, so
+ * that header — not the status code — decides how long the peer is parked.
+ *
+ * @module proxy/peerTransport
+ */
+import { logger } from "../utils/logger.js";
+import { coolPeer, recordPeerSuccess } from "./peerStore.js";
+/** A peer is a fallback, so it gets a short leash before we move on. */
+const PEER_CONNECT_TIMEOUT_MS = 15_000;
+/**
+ * Longest silence tolerated once a peer has started answering.
+ *
+ * The connect timer is cleared as soon as headers arrive, which on a streamed
+ * response is long before the answer is. Without a second deadline a lender
+ * that opens the stream and then stops writing holds our client open forever —
+ * a borrowed request is the fallback path and should never be the one that
+ * hangs. Generous, because a long thinking pause is a legitimate silence.
+ */
+const PEER_IDLE_TIMEOUT_MS = 120_000;
+/**
+ * Map a lender's refusal to how long the peer should be left alone.
+ *
+ * Anything not recognized is treated as an upstream problem rather than a grant
+ * problem — the conservative reading, since it recovers soonest.
+ */
+export function peerReasonFromRefusal(grantReason) {
+    switch (grantReason) {
+        case "exhausted":
+            return "exhausted";
+        case "paused":
+            return "paused";
+        case "revoked":
+            return "revoked";
+        case "expired":
+            return "expired";
+        case "reserve_floor":
+        case "spillover_inactive":
+        case "slice_exhausted":
+        case "no_capacity":
+            return "withheld";
+        case "missing_token":
+        case "unknown_token":
+        case "malformed_token":
+            // The lender does not recognize us at all. Treat it like a revocation:
+            // retrying a token the lender has forgotten cannot start working again.
+            return "revoked";
+        default:
+            // No grant reason means the lender never got as far as our grant — this
+            // is its own upstream or credential trouble, not a statement about us.
+            // Reading a bare 401 as a revocation would park a perfectly good peer for
+            // a day because the lender briefly had no usable account.
+            return "upstream_error";
+    }
+}
+/**
+ * A numeric header, or `undefined` when the peer did not send one.
+ *
+ * `Number(null)` and `Number("")` are both `0`, and `0` passes
+ * `Number.isFinite` — so reading these headers directly turns "the lender said
+ * nothing" into "the lender said zero", which on a remaining-coins header reads
+ * as an exhausted peer.
+ */
+function numericHeader(response, name) {
+    const raw = response.headers.get(name);
+    if (raw === null || raw.trim() === "") {
+        return undefined;
+    }
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+function observationFrom(response) {
+    const remaining = numericHeader(response, "x-neurolink-grant-remaining-coins");
+    return {
+        observedAt: Date.now(),
+        ...(response.headers.get("x-neurolink-grant-status")
+            ? { grantStatus: response.headers.get("x-neurolink-grant-status") ?? "" }
+            : {}),
+        ...(response.headers.get("x-neurolink-grant-reason")
+            ? { grantReason: response.headers.get("x-neurolink-grant-reason") ?? "" }
+            : {}),
+        ...(remaining !== undefined ? { remainingCoins: remaining } : {}),
+    };
+}
+/**
+ * Re-arm a deadline on every chunk, and abandon the peer if one never comes.
+ *
+ * The body is passed through rather than buffered: the point of handing the
+ * upstream response back is that a stream keeps streaming, and collecting it
+ * here would add the whole generation time to time-to-first-token on a path
+ * that is already a second hop.
+ */
+function withIdleDeadline(response, peer, controller) {
+    const body = response.body;
+    if (!body) {
+        return response;
+    }
+    let idle;
+    const disarm = () => {
+        if (idle !== undefined) {
+            clearTimeout(idle);
+            idle = undefined;
+        }
+    };
+    const arm = () => {
+        disarm();
+        idle = setTimeout(() => {
+            logger.always(`[proxy] peer=${peer.name} went quiet mid-response; abandoning it`);
+            // Cool it here as well. The success path cleared this peer's cooldown the
+            // moment the response headers arrived, which is long before a body stops
+            // arriving — so a peer that answers 200 and then stalls would otherwise
+            // stay perfectly healthy in the store and be picked again, and again, for
+            // the same stall. Failing mid-body is a failure like any other.
+            void coolPeer(peer.name, "unreachable").catch((error) => {
+                logger.debug(`[proxy] could not cool peer=${peer.name} after a stall: ${error instanceof Error ? error.message : String(error)}`);
+            });
+            // Aborting the fetch errors the stream, which is what the caller needs to
+            // see — a truncated answer presented as a complete one would be worse.
+            controller.abort();
+        }, PEER_IDLE_TIMEOUT_MS);
+        idle.unref?.();
+    };
+    const watched = body.pipeThrough(new TransformStream({
+        start: arm,
+        transform(chunk, target) {
+            arm();
+            target.enqueue(chunk);
+        },
+        flush: disarm,
+    }));
+    controller.signal.addEventListener("abort", disarm, { once: true });
+    return new Response(watched, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}
+/**
+ * Send one request to one peer.
+ *
+ * On success the upstream `Response` is handed back with only an idle deadline
+ * wrapped around its body, so a stream keeps streaming — buffering it here
+ * would add the whole generation time to time-to-first-token on a path that is
+ * already a second hop.
+ */
+export async function forwardToPeer(args) {
+    const { peer, body, stream } = args;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), PEER_CONNECT_TIMEOUT_MS);
+    if (args.signal) {
+        if (args.signal.aborted) {
+            controller.abort();
+        }
+        else {
+            args.signal.addEventListener("abort", () => controller.abort(), {
+                once: true,
+            });
+        }
+    }
+    try {
+        const response = await fetch(`${peer.url}/v1/messages`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-neurolink-share-token": peer.token,
+                accept: stream ? "text/event-stream" : "application/json",
+            },
+            body,
+            signal: controller.signal,
+        });
+        if (response.ok) {
+            // Outside the classification below on purpose. This is bookkeeping over a
+            // response that already succeeded, and a disk that will not take the note
+            // says nothing about the peer — letting it fall through to the catch
+            // would cool a peer that had just answered correctly.
+            await recordPeerSuccess(peer.name, observationFrom(response)).catch((error) => {
+                logger.debug(`[proxy] could not record success for peer=${peer.name}: ${error instanceof Error ? error.message : String(error)}`);
+            });
+            return {
+                ok: true,
+                response: withIdleDeadline(response, peer, controller),
+                peer,
+            };
+        }
+        const grantReason = response.headers.get("x-neurolink-grant-reason");
+        const reason = peerReasonFromRefusal(grantReason);
+        const retryAfter = numericHeader(response, "retry-after");
+        await coolPeer(peer.name, reason, retryAfter);
+        // The body is drained but deliberately not surfaced: it is the lender's
+        // wording about the lender's pool, and forwarding it to our client would
+        // leak their account state into an error our client cannot act on.
+        await response.text().catch(() => "");
+        logger.always(`[proxy] peer=${peer.name} declined (${reason}); cooling before retry`);
+        return {
+            ok: false,
+            peer,
+            status: response.status,
+            reason,
+            message: `peer ${peer.name} declined: ${reason}`,
+            ...(retryAfter !== undefined ? { retryAfterSeconds: retryAfter } : {}),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (args.signal?.aborted) {
+            // Our own client hung up, and the abort we are catching is the one we
+            // forwarded on its behalf. The peer did nothing wrong — cooling it here
+            // would let a client that cancels quickly take a whole mesh out of
+            // rotation one peer per cancellation.
+            logger.debug(`[proxy] peer=${peer.name} attempt cancelled by the caller: ${message}`);
+            return {
+                ok: false,
+                peer,
+                reason: "unreachable",
+                message: `peer ${peer.name} attempt cancelled`,
+            };
+        }
+        await coolPeer(peer.name, "unreachable").catch((coolError) => {
+            logger.debug(`[proxy] could not cool peer=${peer.name}: ${coolError instanceof Error ? coolError.message : String(coolError)}`);
+        });
+        logger.always(`[proxy] peer=${peer.name} unreachable: ${message}`);
+        return {
+            ok: false,
+            peer,
+            reason: "unreachable",
+            message: `peer ${peer.name} unreachable`,
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}