@north-light/crouter-api 0.3.321 → 0.3.322

package/dist/api/__tests__/integration/client.test.js

@@ -6,6 +6,7 @@ import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { CrtrClient, safeColdStartDiagnostic } from '../../client.js';
+import { localClient } from '../../node-transport.js';
 import { ApiError } from '../../errors.js';
 function startDelayedHealthzServer(socketPath, delayMs) {
     const server = createServer((_req, res) => {
@@ -38,7 +39,7 @@ test('a hang-up mid-request rides out the daemon handover and replays the idempo
     const { server, ready } = startHandoverServer(socketPath);
     try {
         await ready;
-        const client = new CrtrClient({ socketPath, autostart: false, coldStartPollWindowMs: 2_000 });
+        const client = localClient({ socketPath, autostart: false, coldStartPollWindowMs: 2_000 });
         assert.deepEqual(await client.request('GET', '/v1/nodes'), { ok: true, method: 'GET' });
     }
     finally {
@@ -52,7 +53,7 @@ test('an interrupted mutation is not replayed or labelled a daemon handover', as
     const { server, ready } = startHandoverServer(socketPath);
     try {
         await ready;
-        const client = new CrtrClient({ socketPath, autostart: false, coldStartPollWindowMs: 2_000 });
+        const client = localClient({ socketPath, autostart: false, coldStartPollWindowMs: 2_000 });
         await assert.rejects(() => client.request('POST', '/v1/nodes', {}), 
         // Replaying is unsafe (the daemon may have applied it), so this one is the
         // caller's call — but it must not be reported as a daemon that is down.
@@ -68,7 +69,7 @@ test('a non-socket cold-start path surfaces its diagnostic after autostart times
     const socketPath = join(dir, 'crtrd.sock');
     mkdirSync(socketPath);
     const diagnostic = 'crtrd.log (tail):\napi.server.failed: EADDRINUSE';
-    const client = new CrtrClient({
+    const client = localClient({
         socketPath,
         autostart: true,
         onColdSocket: async () => { },
@@ -89,7 +90,7 @@ test('cliClient-style cold start fails loud when the injected poll window is sho
     const socketPath = join(dir, 'crtrd.sock');
     const { server, cancel } = startDelayedHealthzServer(socketPath, 300);
     try {
-        const client = new CrtrClient({
+        const client = localClient({
             socketPath,
             autostart: true,
             onColdSocket: async () => {
@@ -111,7 +112,7 @@ test('a disabled-autostart client waits for an externally managed listener witho
     const { server, cancel } = startDelayedHealthzServer(socketPath, 100);
     let spawnAttempts = 0;
     try {
-        const client = new CrtrClient({
+        const client = localClient({
             socketPath,
             autostart: false,
             onColdSocket: async () => { spawnAttempts += 1; },
@@ -132,7 +133,7 @@ test('availability expiry keeps the final transport failure inside one wall-cloc
     const server = createServer((_req, _res) => { });
     let listenTimer;
     try {
-        const client = new CrtrClient({
+        const client = localClient({
             socketPath,
             autostart: true,
             timeoutMs: 5_000,
@@ -150,6 +151,21 @@ test('availability expiry keeps the final transport failure inside one wall-cloc
         rmSync(dir, { recursive: true, force: true });
     }
 });
+test('a caller abort with a custom reason is request_aborted', async () => {
+    const controller = new AbortController();
+    const client = new CrtrClient({
+        baseUrl: 'http://fixture.test',
+        fetch: async (_input, init) => await new Promise((_resolve, reject) => {
+            const signal = init?.signal;
+            if (signal === null || signal === undefined)
+                throw new Error('request signal is required');
+            signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+        }),
+    });
+    const request = client.request('GET', '/healthz', undefined, { signal: controller.signal });
+    controller.abort(new Error('caller custom abort'));
+    await assert.rejects(request, (error) => error instanceof ApiError && error.code === 'request_aborted');
+});
 test('safeColdStartDiagnostic returns undefined for an absent hook', () => {
     assert.equal(safeColdStartDiagnostic(undefined), undefined);
 });

package/dist/api/client.d.ts

@@ -14,7 +14,7 @@ import type { DeleteProfileRequest, DeleteProfileResultDTO, EnsureProfileRequest
 import type { FilePeekDTO } from './dto/files.js';
 import type { MemoryDocRefDTO } from './dto/memory.js';
 import type { ChatInventoryDTO, ProspectiveChatInventoryDTO, ProspectiveChatInventoryQuery } from './dto/chat-inventory.js';
-import type { CredentialRemovalResultDTO, CredentialResultDTO, InstallCredentialRequest, ModelAuthListDTO } from './dto/modelauth.js';
+import type { CredentialRemovalResultDTO, CredentialResultDTO, InstallCredentialRequest, ModelAuthListDTO, ModelAuthReadinessDTO, ModelAuthReadinessQuery } from './dto/modelauth.js';
 import type { CancelReviewRequest, CreateReviewRequest, ListReviewsQuery, ReviewCancelResultDTO, ReviewDocumentBaseDTO, ReviewDTO, ReviewListDTO, ReviewSubmitResultDTO } from './dto/reviews.js';
 import type { CreateReviewCommentRequest, EditReviewCommentRequest, ListReviewCommentsQuery, ReadReviewCommentEventsQuery, ReviewCommentActionRequest, ReviewCommentDetailDTO, ReviewCommentEventsDTO, ReviewCommentForkDTO, ReviewCommentListDTO, ReviewCommentMutationDTO, ReviewCommentRangeBatchRequest, ReviewCommentRangeBatchResultDTO } from './dto/review-comments.js';
 import type { CancelInboxTicketRequest, CanceledTicketResultDTO, InboxListDTO, InboxPageDTO, InboxPageHistoryDTO, InboxPageResponseDTO, InboxTicketIdDTO, PageFeedbackResolutionDTO, PageResponsesDTO, PageTicketResultDTO, RespondInboxPageRequest } from './dto/inbox.js';
@@ -25,16 +25,18 @@ import type { BrokerExtensionStateDTO, BrokerExecutionRequest, BrokerGeneratedNa
 import type { AcknowledgeMailRequest, AcknowledgeMailResultDTO, ClaimMailRequest, ClaimMailResultDTO } from './dto/mail.js';
 import type { BrokerFaultInputDTO, BrokerFaultRequest, BrokerFaultResultDTO, BrokerProviderRetryRequest, BrokerProviderRetryResultDTO, BrokerTurnRequest, BrokerTurnResultDTO, NodeFaultClearResultDTO, RecoveryStateDTO } from './dto/recovery.js';
 export interface CrtrClientOptions {
-    /** Unix socket path (default local transport). Exactly one of socketPath|baseUrl. */
-    socketPath?: string;
-    /** `http(s)://host:port` for TCP/remote transport. */
-    baseUrl?: string;
+    /** `http(s)://host:port` for a TCP/remote transport. */
+    baseUrl: string;
+    /** Fetch implementation. The global Web fetch is used unless a caller supplies one. */
+    fetch?: typeof fetch;
     /** Extra headers, e.g. `{ authorization: 'Bearer <token>' }` when the target
      *  crtrd's TCP listener has `CRTRD_TOKEN` set (unix-socket transport is
      *  never checked, and a TCP daemon with no token set ignores this too). */
     headers?: Record<string, string>;
-    /** Autostart on a cold socket (default true for socketPath, false for baseUrl). */
+    /** Retry a cold local connection through this hook once when enabled. */
     autostart?: boolean;
+    /** Maximum retries for transient GET, HEAD, and DELETE requests. Defaults to 2. */
+    maxRetries?: number;
     /** Per-request timeout in ms (default 30_000). */
     timeoutMs?: number;
     /** Injected daemon-start hook (spec §7.1). Called once on a cold socket when
@@ -64,22 +66,26 @@ export declare function waitForDaemonAvailability({ windowMs, probe, initialErro
     now?: () => number;
     sleep?: (ms: number) => Promise<void> | void;
 }): Promise<void>;
+export interface CrtrRequestOptions {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    timeout?: number;
+    maxRetries?: number;
+}
 export declare class CrtrClient {
-    private readonly socketPath?;
-    private readonly baseUrl?;
+    private readonly baseUrl;
+    private readonly fetch;
     private readonly headers;
     private readonly autostart;
     private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly localSocketTransport;
     private readonly onColdSocket?;
     private readonly coldStartDiagnostic?;
     private readonly coldStartPollWindowMs;
     /** Guards against invoking the daemon-start hook more than once per client. */
     private coldStartAttempted;
     constructor(opts: CrtrClientOptions);
-    /** Construct a client bound to the default local socket with autostart on. Pass
-     *  `onColdSocket` to enable the daemon-spawn hook (spec §7.1); without it a cold
-     *  socket fails loud with `daemon_unavailable`. */
-    static forLocalSocket(opts?: Omit<CrtrClientOptions, 'socketPath' | 'baseUrl'>): CrtrClient;
     healthz(): Promise<HealthDTO>;
     /** One `/healthz` observation without cold-socket recovery. Availability
      * waiters own retry policy and pass their remaining wall-clock budget here. */
@@ -219,6 +225,7 @@ export declare class CrtrClient {
     /** Force-delete or detach one profile by exact id or unique name. */
     deleteProfile(name: string, req: DeleteProfileRequest): Promise<DeleteProfileResultDTO>;
     listModelAuth(): Promise<ModelAuthListDTO>;
+    getModelAuthReadiness(query?: ModelAuthReadinessQuery): Promise<ModelAuthReadinessDTO>;
     installCredential(provider: string, req: InstallCredentialRequest): Promise<CredentialResultDTO>;
     removeCredential(provider: string): Promise<CredentialRemovalResultDTO>;
     createReview(req: CreateReviewRequest): Promise<ReviewDTO>;
@@ -310,10 +317,12 @@ export declare class CrtrClient {
     canvasRoster(): Promise<RosterDTO>;
     prune(req: PruneRequest): Promise<PruneResultDTO>;
     /** Raw request for routes not yet method-wrapped. Applies the same
-     *  autostart + error-mapping semantics. */
-    request<T>(method: string, path: string, body?: unknown, timeoutMs?: number): Promise<T>;
-    /** The unparsed request: cold-socket and interrupted-response recovery, no
-     * JSON parse. Every wrapper goes through here; only non-JSON routes call it directly. */
+     *  autostart + retry + error-mapping semantics. */
+    request<T>(method: string, path: string, body?: unknown, opts?: CrtrRequestOptions): Promise<T>;
+    /** The unparsed request: cold-socket and interrupted-response recovery, plus
+     *  the §7 retry policy (connection errors and 429/5xx on GET/HEAD/DELETE
+     *  only — POST/PATCH are never replayed once a request has actually been
+     *  sent). No JSON parse; every wrapper goes through here. */
     private send;
     private nodePath;
     /** Validate a background job id before route construction. Job ids arrive
@@ -343,7 +352,11 @@ export declare class CrtrClient {
      *  agent argv, so a bad one is a plausible request the server would also
      *  reject, not a caller-bug `TypeError` like `ticketId`. */
     private commentPath;
+    /** The one fetch path (§1). Resolves as soon as headers arrive — the body
+     *  stays an unread `ReadableStream` on the returned `Response`, so a caller
+     *  that wants to stream (SSE, later) never waits on a buffered body. */
     private transport;
+    private retainRequestLifetime;
     private isColdSocketError;
     /** A connection torn down MID-request (Node's "socket hang up" / a broken
      * pipe). It establishes only that the response was interrupted, not why. */

package/dist/api/client.js

@@ -1,40 +1,14 @@
-// CrtrClient — the typed HTTP+WS client over crtrd's API (spec §3.4).
+// CrtrClient — the typed fetch client over crtrd's API.
 //
-// PURITY (spec §3.1): the ONLY runtime imports are Node built-ins
-// (`node:http`, `node:https`, `node:os`, `node:path`) plus `src/api/*`. Never
-// `core/*` / `node:sqlite` / TUI. The daemon-spawn logic lives in `core`/
-// `daemon`, which this module may not import — so autostart is delegated to an
-// injectable `onColdSocket` hook the CLI wires in (spec §7.1). A cold socket
-// always gets one bounded availability observation; the hook only permits spawning.
-//
-// TRANSPORT (spec O-1): `node:http`/`node:https` `request()` — NO `undici`.
-// unix socket via `{ socketPath }`; TCP/remote via a parsed `baseUrl`.
-import { envHomeOverride } from '../shared/env.js';
-import { request as httpRequest } from 'node:http';
-import { request as httpsRequest } from 'node:https';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
+// The root entry is browser-safe: Node's unix-socket fetch implementation and
+// local path resolution live exclusively in `api/node-transport.ts`.
 import { ApiError, isErrorBody } from './errors.js';
 import { routes } from './routes.js';
 import { isSafeNodeId } from './dto/common.js';
 import { isSafeBashJobId } from './dto/bash-jobs.js';
 import { isSafeCronId, } from './dto/crons.js';
-/** Filesystem/scope constants mirrored from `core/types.ts` (`CRTR_DIR_NAME`)
- *  and `core/canvas/paths.ts` (`crtrHome`/`apiSocketPath`). Duplicated — not
- *  imported — to keep the exported `/api` contract dependency-light; the two
- *  MUST agree on the resolved socket path. */
-const CRTR_DIR_NAME = '.crouter';
-const SOCKET_BASENAME = 'crtrd.sock';
-/** Resolve crtrd's default unix socket path the same way `apiSocketPath()` does,
- *  via Node built-ins only (no `core/canvas/paths.ts` import). */
-function defaultSocketPath() {
-    const override = envHomeOverride();
-    const home = override !== undefined && override !== ''
-        ? override
-        : join(homedir(), CRTR_DIR_NAME, 'canvas');
-    return join(home, SOCKET_BASENAME);
-}
 const DEFAULT_TIMEOUT_MS = 30_000;
+const LOCAL_SOCKET_FETCH = Symbol.for('@north-light/crouter-api/local-socket-fetch');
 /** Default bounded window to wait for `/healthz` to come up after
  *  `onColdSocket`, when the caller does not pass `coldStartPollWindowMs`. */
 const HEALTHZ_POLL_WINDOW_MS = 10_000;
@@ -64,41 +38,34 @@ export async function waitForDaemonAvailability({ windowMs, probe, initialError,
     }
 }
 export class CrtrClient {
-    socketPath;
     baseUrl;
+    fetch;
     headers;
     autostart;
     timeoutMs;
+    maxRetries;
+    localSocketTransport;
     onColdSocket;
     coldStartDiagnostic;
     coldStartPollWindowMs;
     /** Guards against invoking the daemon-start hook more than once per client. */
     coldStartAttempted = false;
     constructor(opts) {
-        const hasSocket = opts.socketPath !== undefined && opts.socketPath !== '';
-        const hasBaseUrl = opts.baseUrl !== undefined && opts.baseUrl !== '';
-        if (hasSocket === hasBaseUrl) {
-            throw new TypeError('CrtrClient requires exactly one of socketPath | baseUrl');
-        }
-        if (hasSocket)
-            this.socketPath = opts.socketPath;
-        if (hasBaseUrl)
-            this.baseUrl = new URL(opts.baseUrl);
+        if (opts.baseUrl === '')
+            throw new TypeError('CrtrClient requires baseUrl');
+        this.baseUrl = new URL(opts.baseUrl);
+        this.fetch = opts.fetch ?? globalThis.fetch;
         this.headers = { ...opts.headers };
-        this.autostart = opts.autostart ?? hasSocket;
+        this.autostart = opts.autostart ?? false;
         this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = opts.maxRetries ?? 2;
+        this.localSocketTransport = this.fetch[LOCAL_SOCKET_FETCH] === true;
         if (opts.onColdSocket !== undefined)
             this.onColdSocket = opts.onColdSocket;
         if (opts.coldStartDiagnostic !== undefined)
             this.coldStartDiagnostic = opts.coldStartDiagnostic;
         this.coldStartPollWindowMs = opts.coldStartPollWindowMs ?? HEALTHZ_POLL_WINDOW_MS;
     }
-    /** Construct a client bound to the default local socket with autostart on. Pass
-     *  `onColdSocket` to enable the daemon-spawn hook (spec §7.1); without it a cold
-     *  socket fails loud with `daemon_unavailable`. */
-    static forLocalSocket(opts) {
-        return new CrtrClient({ socketPath: defaultSocketPath(), autostart: true, ...opts });
-    }
     // Health / status
     healthz() {
         return this.request('GET', routes.healthz());
@@ -106,13 +73,13 @@ export class CrtrClient {
     /** One `/healthz` observation without cold-socket recovery. Availability
      * waiters own retry policy and pass their remaining wall-clock budget here. */
     async probeHealthz(timeoutMs) {
-        const response = await this.transport('GET', routes.healthz(), undefined, undefined, timeoutMs);
+        const response = await this.transport('GET', routes.healthz(), undefined, { timeout: timeoutMs });
         // A restricted daemon is alive and deliberately answers its health DTO with
         // 503. Preserve that state for daemon startup management instead of treating
         // the expected non-2xx status as a generic API failure.
         if (response.status === 503) {
             try {
-                const health = JSON.parse(response.text);
+                const health = await response.clone().json();
                 if (typeof health.startup_blocked === 'string')
                     return health;
             }
@@ -156,7 +123,7 @@ export class CrtrClient {
         if (waitSeconds !== undefined && (!Number.isInteger(waitSeconds) || waitSeconds < 0 || waitSeconds > 25)) {
             throw new RangeError('waitSeconds must be an integer between 0 and 25');
         }
-        return this.request('GET', withQuery(routes.nodeOutcome(this.nodePath(id)), { wait: waitSeconds }), undefined, (waitSeconds ?? 0) * 1_000 + this.timeoutMs);
+        return this.request('GET', withQuery(routes.nodeOutcome(this.nodePath(id)), { wait: waitSeconds }), undefined, { timeout: (waitSeconds ?? 0) * 1_000 + this.timeoutMs });
     }
     /** Register or replace an armed target for terminal-outcome delivery. */
     registerOutcomeDelivery(id, req) {
@@ -438,6 +405,9 @@ export class CrtrClient {
     listModelAuth() {
         return this.request('GET', routes.modelAuths());
     }
+    getModelAuthReadiness(query) {
+        return this.request('GET', withQuery(routes.modelAuthReadiness(), query));
+    }
     installCredential(provider, req) {
         return this.request('PUT', routes.modelAuth(provider), req);
     }
@@ -632,29 +602,54 @@ export class CrtrClient {
     }
     // Escape hatch
     /** Raw request for routes not yet method-wrapped. Applies the same
-     *  autostart + error-mapping semantics. */
-    async request(method, path, body, timeoutMs) {
-        return parse(await this.send(method, path, body, undefined, timeoutMs));
-    }
-    /** The unparsed request: cold-socket and interrupted-response recovery, no
-     * JSON parse. Every wrapper goes through here; only non-JSON routes call it directly. */
-    async send(method, path, body, extraHeaders, timeoutMs) {
+     *  autostart + retry + error-mapping semantics. */
+    async request(method, path, body, opts) {
         try {
-            return await this.transport(method, path, body, extraHeaders, timeoutMs);
+            return await parse(await this.send(method, path, body, opts));
         }
-        catch (err) {
-            if (this.isColdSocketError(err)) {
-                try {
-                    await this.handleColdSocket(err);
-                    return await this.transport(method, path, body, extraHeaders, timeoutMs);
+        catch (error) {
+            throw toTransportApiError(error, opts?.signal);
+        }
+    }
+    /** The unparsed request: cold-socket and interrupted-response recovery, plus
+     *  the §7 retry policy (connection errors and 429/5xx on GET/HEAD/DELETE
+     *  only — POST/PATCH are never replayed once a request has actually been
+     *  sent). No JSON parse; every wrapper goes through here. */
+    async send(method, path, body, opts = {}) {
+        const idempotent = method === 'GET' || method === 'HEAD' || method === 'DELETE';
+        const maxRetries = opts.maxRetries ?? this.maxRetries;
+        for (let attempt = 0;; attempt++) {
+            let response;
+            try {
+                response = await this.transport(method, path, body, opts);
+            }
+            catch (err) {
+                if (this.isColdSocketError(err)) {
+                    try {
+                        await this.handleColdSocket(err);
+                        response = await this.transport(method, path, body, opts);
+                    }
+                    catch (recoveryError) {
+                        throw toTransportApiError(recoveryError, opts.signal);
+                    }
+                }
+                else if (this.isInterruptedSocketError(err) && this.localSocketTransport && (!idempotent || attempt < maxRetries)) {
+                    return await this.rideOutInterruptedRequest(method, path, body, opts);
                 }
-                catch (recoveryError) {
-                    throw toTransportApiError(recoveryError);
+                else if (idempotent && attempt < maxRetries && !isAbortError(err, opts.signal) && (!this.localSocketTransport || !this.isInterruptedSocketError(err))) {
+                    await sleepMs(retryDelayMs(attempt + 1));
+                    continue;
                 }
+                else {
+                    throw toTransportApiError(err, opts.signal);
+                }
+            }
+            if (idempotent && attempt < maxRetries && isRetryableStatus(response.status)) {
+                await drainResponseBody(response);
+                await sleepMs(retryDelayMs(attempt + 1));
+                continue;
             }
-            if (this.isInterruptedSocketError(err))
-                return await this.rideOutInterruptedRequest(method, path, body, extraHeaders, timeoutMs);
-            throw toTransportApiError(err);
+            return response;
         }
     }
     // internals
@@ -721,85 +716,103 @@ export class CrtrClient {
         }
         return id;
     }
-    transport(method, path, body, extraHeaders, timeoutMs = this.timeoutMs) {
-        const usingHttps = this.baseUrl?.protocol === 'https:';
-        const doRequest = usingHttps ? httpsRequest : httpRequest;
+    /** The one fetch path (§1). Resolves as soon as headers arrive — the body
+     *  stays an unread `ReadableStream` on the returned `Response`, so a caller
+     *  that wants to stream (SSE, later) never waits on a buffered body. */
+    transport(method, path, body, opts = {}) {
         const payload = body === undefined ? undefined : JSON.stringify(body);
-        const headers = { accept: 'application/json', ...this.headers, ...extraHeaders };
-        if (payload !== undefined) {
+        const headers = { accept: 'application/json', ...this.headers, ...opts.headers };
+        if (payload !== undefined)
             headers['content-type'] = 'application/json';
-            headers['content-length'] = String(Buffer.byteLength(payload));
+        const timeoutMs = opts.timeout ?? this.timeoutMs;
+        const controller = new AbortController();
+        const timer = timeoutMs > 0
+            ? setTimeout(() => controller.abort(new DOMException('request timed out', 'TimeoutError')), timeoutMs)
+            : undefined;
+        const externalSignal = opts.signal;
+        const onExternalAbort = () => controller.abort(externalSignal?.reason);
+        if (externalSignal !== undefined) {
+            if (externalSignal.aborted)
+                controller.abort(externalSignal.reason);
+            else
+                externalSignal.addEventListener('abort', onExternalAbort, { once: true });
         }
-        const options = {
-            method,
-            path,
-            headers,
-            timeout: timeoutMs,
+        const finish = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            externalSignal?.removeEventListener('abort', onExternalAbort);
         };
-        if (this.socketPath !== undefined) {
-            options.socketPath = this.socketPath;
-        }
-        else if (this.baseUrl !== undefined) {
-            options.protocol = this.baseUrl.protocol;
-            options.hostname = this.baseUrl.hostname;
-            if (this.baseUrl.port !== '')
-                options.port = this.baseUrl.port;
+        return this.fetch(new URL(path, this.baseUrl), { method, headers, body: payload, signal: controller.signal })
+            .then((response) => this.retainRequestLifetime(response, finish, () => controller.signal.aborted ? controller.signal.reason : undefined), (error) => {
+            finish();
+            throw error;
+        });
+    }
+    retainRequestLifetime(response, finish, abortReason) {
+        if (response.body === null) {
+            finish();
+            return response;
         }
-        return new Promise((resolve, reject) => {
-            const req = doRequest(options, (res) => {
-                const chunks = [];
-                res.on('data', (chunk) => chunks.push(chunk));
-                res.on('end', () => {
-                    const received = {};
-                    for (const [name, value] of Object.entries(res.headers)) {
-                        if (value !== undefined)
-                            received[name] = Array.isArray(value) ? value.join(', ') : value;
+        const reader = response.body.getReader();
+        let finished = false;
+        const close = () => {
+            if (finished)
+                return;
+            finished = true;
+            finish();
+        };
+        const body = new ReadableStream({
+            async pull(controller) {
+                try {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        close();
+                        controller.close();
                     }
-                    resolve({ status: res.statusCode ?? 0, text: Buffer.concat(chunks).toString('utf8'), headers: received });
-                });
-                res.on('error', reject);
-            });
-            req.on('error', reject);
-            req.on('timeout', () => {
-                req.destroy(Object.assign(new Error('request timed out'), { code: 'ETIMEDOUT' }));
-            });
-            if (payload !== undefined)
-                req.write(payload);
-            req.end();
+                    else {
+                        controller.enqueue(value);
+                    }
+                }
+                catch (error) {
+                    close();
+                    controller.error(abortReason() ?? error);
+                }
+            },
+            async cancel(reason) {
+                close();
+                await reader.cancel(reason);
+            },
         });
+        return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
     }
     isColdSocketError(err) {
-        if (this.socketPath === undefined)
-            return false;
-        const code = err?.code;
+        const code = transportErrorCode(err);
         return code === 'ECONNREFUSED' || code === 'ENOENT' || code === 'ENOTSOCK';
     }
     /** A connection torn down MID-request (Node's "socket hang up" / a broken
      * pipe). It establishes only that the response was interrupted, not why. */
     isInterruptedSocketError(err) {
-        if (this.socketPath === undefined)
-            return false;
-        const code = err?.code;
+        const code = transportErrorCode(err);
         return code === 'ECONNRESET' || code === 'EPIPE';
     }
     /** Wait for the local API after an interrupted response. GET/HEAD can retry
      * because they are idempotent. A mutation may already have been applied, so
      * it never replays. */
-    async rideOutInterruptedRequest(method, path, body, extraHeaders, timeoutMs) {
+    async rideOutInterruptedRequest(method, path, body, opts = {}) {
         try {
             await this.awaitAvailability();
         }
         catch (error) {
-            throw toTransportApiError(error);
+            throw toTransportApiError(error, opts.signal);
         }
         if (method !== 'GET' && method !== 'HEAD') {
             throw new ApiError(503, 'daemon_request_interrupted', `crtrd connection ended before this ${method} response; the request may or may not have been applied.`);
         }
         try {
-            return await this.transport(method, path, body, extraHeaders, timeoutMs);
+            return await this.transport(method, path, body, opts);
         }
         catch (err) {
-            throw toTransportApiError(err);
+            throw toTransportApiError(err, opts.signal);
         }
     }
     async awaitAvailability(initialError) {
@@ -807,18 +820,19 @@ export class CrtrClient {
             windowMs: this.coldStartPollWindowMs,
             initialError,
             probe: async (timeoutMs) => {
-                const response = await this.transport('GET', routes.healthz(), undefined, undefined, timeoutMs);
+                const response = await this.transport('GET', routes.healthz(), undefined, { timeout: timeoutMs });
                 if (response.status >= 200 && response.status < 300)
                     return;
+                const text = await response.text();
                 try {
-                    const health = JSON.parse(response.text);
+                    const health = JSON.parse(text);
                     if (typeof health.startup_blocked === 'string')
                         return;
                 }
                 catch {
                     // The normal unavailable error below carries the response body.
                 }
-                throw new ApiError(response.status, 'daemon_health_unavailable', `crtrd health check returned HTTP ${response.status}: ${response.text.slice(0, 500)}`);
+                throw new ApiError(response.status, 'daemon_health_unavailable', `crtrd health check returned HTTP ${response.status}: ${text.slice(0, 500)}`);
             },
         });
     }
@@ -859,11 +873,12 @@ function withQuery(base, query) {
     const qs = params.toString();
     return qs === '' ? base : `${base}?${qs}`;
 }
-/** Parse a raw response into `T`, or throw `ApiError` on non-2xx. A 204/empty
- *  body yields `undefined` (callers that type `void`/optional handle it). */
-function parse(res) {
+/** Parse a response into `T` — the first (and here, only) read of its body —
+ *  or throw `ApiError` on non-2xx. A 204/empty body yields `undefined`
+ *  (callers that type `void`/optional handle it). */
+async function parse(res) {
     const ok = res.status >= 200 && res.status < 300;
-    const trimmed = res.text.trim();
+    const trimmed = (await res.text()).trim();
     let payload;
     if (trimmed !== '') {
         try {
@@ -872,23 +887,77 @@ function parse(res) {
         catch {
             if (ok)
                 return undefined;
-            throw new ApiError(res.status, 'invalid_response', res.text.slice(0, 500));
+            throw new ApiError(res.status, 'invalid_response', trimmed.slice(0, 500), undefined, res.headers);
         }
     }
     if (ok)
         return payload;
     if (isErrorBody(payload)) {
-        throw new ApiError(res.status, payload.error.code, payload.error.message, payload.error.details);
+        throw new ApiError(res.status, payload.error.code, payload.error.message, payload.error.details, res.headers);
     }
-    throw new ApiError(res.status, 'internal', `request failed with status ${res.status}`);
+    throw new ApiError(res.status, 'internal', `request failed with status ${res.status}`, undefined, res.headers);
+}
+/** `429`/`5xx` are the only statuses the §7 retry policy replays. */
+function isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+/** A response abandoned mid-retry must have its stream drained, or the
+ *  underlying connection (and, over a unix socket, the daemon's handler) is
+ *  held open by a reader that will never arrive. */
+async function drainResponseBody(res) {
+    try {
+        await res.body?.cancel();
+    }
+    catch {
+        // Best-effort — the response is being discarded either way.
+    }
+}
+/** Exponential backoff for the §7 retry policy: 250ms, 500ms, 1s, capped at 2s. */
+function retryDelayMs(attempt) {
+    return Math.min(2_000, 250 * 2 ** (attempt - 1));
+}
+/** The underlying `errno`-style code beneath a fetch failure. Native `fetch`
+ *  wraps a connection error as `TypeError('fetch failed', { cause })`; the
+ *  Node-only socket `fetch` (`api/node-transport.ts`) preserves the same
+ *  shape so both transports classify identically here. */
+function transportErrorCode(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    const direct = err.code;
+    if (typeof direct === 'string')
+        return direct;
+    const cause = err.cause;
+    if (typeof cause === 'object' && cause !== null) {
+        const causeCode = cause.code;
+        if (typeof causeCode === 'string')
+            return causeCode;
+    }
+    return undefined;
+}
+/** True when a transport throw is the caller's OWN abort, as opposed to the
+ *  client's internal per-request timeout — an aborted request must never be
+ *  retried, whichever reason fired. */
+function isAbortError(err, signal) {
+    if (signal?.aborted)
+        return true;
+    return err instanceof DOMException && (err.name === 'AbortError' || err.name === 'TimeoutError');
 }
 /** Map a transport-layer throw (never an HTTP status) to an `ApiError`. A
  *  connection refusal here means the daemon is unreachable and autostart could
  *  not recover it. */
-function toTransportApiError(err) {
+function toTransportApiError(err, signal) {
+    if (signal?.aborted) {
+        return new ApiError(0, 'request_aborted', 'request aborted by caller signal');
+    }
     if (err instanceof ApiError)
         return err;
-    const code = err?.code;
+    if (err instanceof DOMException && err.name === 'TimeoutError') {
+        return new ApiError(504, 'request_timeout', `crtrd request timed out: ${err.message}`);
+    }
+    if (err instanceof DOMException && err.name === 'AbortError') {
+        return new ApiError(0, 'request_aborted', 'request aborted by caller signal');
+    }
+    const code = transportErrorCode(err);
     const message = err instanceof Error ? err.message : String(err);
     if (code === 'ECONNREFUSED' || code === 'ENOENT' || code === 'ENOTSOCK') {
         return new ApiError(503, 'daemon_unavailable', `crtrd is not reachable: ${message}`);

package/dist/api/dto/modelauth.d.ts

@@ -66,6 +66,21 @@ export type ModelAuthProviderStatusDTO = {
 export interface ModelAuthListDTO {
     providers: ModelAuthProviderStatusDTO[];
 }
+/** Inputs that select the exact provider a new root node would use. */
+export interface ModelAuthReadinessQuery {
+    profile?: string;
+    cwd?: string;
+    kind?: string;
+    model?: string;
+}
+/** `GET /v1/model-auth/readiness` — credential state for the provider selected by a prospective root launch. */
+export interface ModelAuthReadinessDTO {
+    provider: string;
+    model: string;
+    credential: 'ready' | 'missing' | 'unusable';
+    reason?: 'invalid_grant';
+    rate_limited_until?: string | null;
+}
 /** `DELETE /v1/model-auth/{provider}` — all user credentials removed for one provider. */
 export interface CredentialRemovalResultDTO {
     provider: string;

package/dist/api/errors.d.ts

@@ -9,14 +9,17 @@ export interface ErrorBody {
 /** Thrown by `CrtrClient` on a non-2xx response (or a synthesized transport
  *  failure such as an unreachable daemon). Carries the HTTP status, the stable
  *  machine `code` from the `ErrorBody`, and optional structured `details`. */
-export declare class ApiError extends Error {
+export declare class APIError extends Error {
     readonly status: number;
     readonly code: string;
     readonly details?: unknown;
-    constructor(status: number, code: string, message: string, details?: unknown);
+    readonly headers: Headers;
+    constructor(status: number, code: string, message: string, details?: unknown, headers?: HeadersInit);
 }
+/** @deprecated Use APIError. Kept as the in-repo compatibility alias. */
+export { APIError as ApiError };
 /** A local API transport failure has stable status/code identity, independent
  * of message prose. */
-export declare function isDaemonTransportApiError(error: unknown): error is ApiError;
+export declare function isDaemonTransportApiError(error: unknown): error is APIError;
 /** Type guard for an `ErrorBody`-shaped parsed payload. */
 export declare function isErrorBody(value: unknown): value is ErrorBody;

package/dist/api/errors.js

@@ -5,23 +5,27 @@
 /** Thrown by `CrtrClient` on a non-2xx response (or a synthesized transport
  *  failure such as an unreachable daemon). Carries the HTTP status, the stable
  *  machine `code` from the `ErrorBody`, and optional structured `details`. */
-export class ApiError extends Error {
+export class APIError extends Error {
     status;
     code;
     details;
-    constructor(status, code, message, details) {
+    headers;
+    constructor(status, code, message, details, headers) {
         super(message);
-        this.name = 'ApiError';
+        this.name = 'APIError';
         this.status = status;
         this.code = code;
+        this.headers = new Headers(headers);
         if (details !== undefined)
             this.details = details;
     }
 }
+/** @deprecated Use APIError. Kept as the in-repo compatibility alias. */
+export { APIError as ApiError };
 /** A local API transport failure has stable status/code identity, independent
  * of message prose. */
 export function isDaemonTransportApiError(error) {
-    if (!(error instanceof ApiError))
+    if (!(error instanceof APIError))
         return false;
     return (error.status === 503 && (error.code === 'daemon_unavailable'
         || error.code === 'transport_error'

package/dist/api/index.d.ts

@@ -1,6 +1,6 @@
 export { CrtrClient, waitForDaemonAvailability } from './client.js';
-export type { CrtrClientOptions } from './client.js';
-export { ApiError, isErrorBody } from './errors.js';
+export type { CrtrClientOptions, CrtrRequestOptions } from './client.js';
+export { APIError, ApiError, isErrorBody } from './errors.js';
 export type { ErrorBody } from './errors.js';
 export { API_VERSION, routes } from './routes.js';
 export * from '../shared/generated-context.js';

package/dist/api/index.js

@@ -2,7 +2,7 @@
 // route constants, error contract, and the typed `CrtrClient`. Dependency-light
 // by design (spec §3.1): Node built-ins + `src/api/*` only.
 export { CrtrClient, waitForDaemonAvailability } from './client.js';
-export { ApiError, isErrorBody } from './errors.js';
+export { APIError, ApiError, isErrorBody } from './errors.js';
 export { API_VERSION, routes } from './routes.js';
 export * from '../shared/generated-context.js';
 export * from './dto/common.js';

package/dist/api/node-transport.d.ts

@@ -0,0 +1,18 @@
+import { CrtrClient, type CrtrClientOptions } from './client.js';
+/** Resolve crtrd's default unix socket path the same way `apiSocketPath()` does,
+ *  via Node built-ins only (no `core/canvas/paths.ts` import). */
+export declare function defaultSocketPath(): string;
+/** A standard `fetch` bound to one unix socket, built on `node:http` with
+ *  `{ socketPath }`. The returned `Response`'s body is a live `ReadableStream`
+ *  fed as bytes arrive — never buffered before the caller sees headers —
+ *  which is what lets `CrtrClient` serve a streaming route (SSE) later without
+ *  a second transport. Connection failures are wrapped as `TypeError('fetch
+ *  failed', { cause })`, matching the shape native `fetch` throws, so
+ *  `CrtrClient`'s cold-socket/interrupted-request classification (`err.cause.code`)
+ *  reads identically off either transport. */
+export declare function socketFetch(socketPath: string): typeof fetch;
+/** Construct a client bound to the default local socket with autostart on.
+ *  Without `onColdSocket`, a cold socket fails with `daemon_unavailable`. */
+export declare function localClient(opts?: Omit<CrtrClientOptions, 'baseUrl' | 'fetch'> & {
+    socketPath?: string;
+}): CrtrClient;

package/dist/api/node-transport.js

@@ -0,0 +1,101 @@
+// The Node-only half of `@north-light/crouter-api`: crtrd's default unix
+// socket path, a `fetch` implementation that speaks it, and `localClient()` —
+// the one-line way to get a `CrtrClient` bound to the owner's own daemon.
+//
+// This is a SEPARATE package entry (`@north-light/crouter-api/node`) from the
+// root so a browser bundle that imports the root never resolves `node:http`,
+// `node:os`, or `node:path`. Import from here, never re-export it off the root.
+import { request as httpRequest } from 'node:http';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { CrtrClient } from './client.js';
+import { envHomeOverride } from '../shared/env.js';
+/** Filesystem/scope constants mirrored from `core/types.ts` (`CRTR_DIR_NAME`)
+ *  and `core/canvas/paths.ts` (`crtrHome`/`apiSocketPath`). Duplicated — not
+ *  imported — to keep the exported `/api` contract dependency-light; the two
+ *  MUST agree on the resolved socket path. */
+const CRTR_DIR_NAME = '.crouter';
+const SOCKET_BASENAME = 'crtrd.sock';
+const LOCAL_SOCKET_FETCH = Symbol.for('@north-light/crouter-api/local-socket-fetch');
+/** Resolve crtrd's default unix socket path the same way `apiSocketPath()` does,
+ *  via Node built-ins only (no `core/canvas/paths.ts` import). */
+export function defaultSocketPath() {
+    const override = envHomeOverride();
+    const home = override !== undefined && override !== ''
+        ? override
+        : join(homedir(), CRTR_DIR_NAME, 'canvas');
+    return join(home, SOCKET_BASENAME);
+}
+/** A standard `fetch` bound to one unix socket, built on `node:http` with
+ *  `{ socketPath }`. The returned `Response`'s body is a live `ReadableStream`
+ *  fed as bytes arrive — never buffered before the caller sees headers —
+ *  which is what lets `CrtrClient` serve a streaming route (SSE) later without
+ *  a second transport. Connection failures are wrapped as `TypeError('fetch
+ *  failed', { cause })`, matching the shape native `fetch` throws, so
+ *  `CrtrClient`'s cold-socket/interrupted-request classification (`err.cause.code`)
+ *  reads identically off either transport. */
+export function socketFetch(socketPath) {
+    const fetchOverSocket = function (input, init = {}) {
+        const url = input instanceof URL ? input : new URL(typeof input === 'string' ? input : input.url);
+        const method = init.method ?? 'GET';
+        const headers = {};
+        if (init.headers !== undefined) {
+            for (const [name, value] of new Headers(init.headers).entries())
+                headers[name] = value;
+        }
+        const payload = typeof init.body === 'string' ? init.body : undefined;
+        if (payload !== undefined)
+            headers['content-length'] = String(Buffer.byteLength(payload));
+        return new Promise((resolvePromise, reject) => {
+            const req = httpRequest({ socketPath, path: url.pathname + url.search, method, headers }, (res) => {
+                const body = new ReadableStream({
+                    start(controller) {
+                        res.on('data', (chunk) => controller.enqueue(new Uint8Array(chunk)));
+                        res.on('end', () => controller.close());
+                        res.on('error', (err) => controller.error(err));
+                    },
+                    cancel() {
+                        res.destroy();
+                    },
+                });
+                const responseHeaders = new Headers();
+                for (const [name, value] of Object.entries(res.headers)) {
+                    if (value === undefined)
+                        continue;
+                    for (const one of Array.isArray(value) ? value : [value])
+                        responseHeaders.append(name, one);
+                }
+                resolvePromise(new Response(body, { status: res.statusCode ?? 0, statusText: res.statusMessage, headers: responseHeaders }));
+            });
+            req.on('error', (err) => reject(new TypeError('fetch failed', { cause: err })));
+            const signal = init.signal;
+            const abort = () => {
+                req.destroy();
+                reject(signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
+            };
+            if (signal !== null && signal !== undefined) {
+                if (signal.aborted) {
+                    abort();
+                    return;
+                }
+                signal.addEventListener('abort', abort, { once: true });
+            }
+            if (payload !== undefined)
+                req.write(payload);
+            req.end();
+        });
+    };
+    fetchOverSocket[LOCAL_SOCKET_FETCH] = true;
+    return fetchOverSocket;
+}
+/** Construct a client bound to the default local socket with autostart on.
+ *  Without `onColdSocket`, a cold socket fails with `daemon_unavailable`. */
+export function localClient(opts = {}) {
+    const { socketPath, ...rest } = opts;
+    return new CrtrClient({
+        baseUrl: 'http://localhost',
+        fetch: socketFetch(socketPath ?? defaultSocketPath()),
+        autostart: true,
+        ...rest,
+    });
+}

package/dist/api/routes.d.ts

@@ -109,6 +109,7 @@ export declare const routes: {
     readonly profileResume: (name: string) => string;
     readonly profileMetadata: (name: string) => string;
     readonly modelAuths: () => string;
+    readonly modelAuthReadiness: () => string;
     readonly modelAuth: (provider: string) => string;
     readonly filePeek: () => string;
     readonly memoryResolve: () => string;

package/dist/api/routes.js

@@ -138,6 +138,7 @@ export const routes = {
     profileMetadata: (name) => `${V}/profiles/${name}/metadata`,
     // Model auth
     modelAuths: () => `${V}/model-auth`,
+    modelAuthReadiness: () => `${V}/model-auth/readiness`,
     modelAuth: (provider) => `${V}/model-auth/${provider}`,
     // Host file read (browser file-peek panel). The absolute path rides as a
     // `path` query param, not a path segment — it is not a single safe segment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter-api",
-  "version": "0.3.321",
+  "version": "0.3.322",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",
@@ -12,6 +12,12 @@
       "require": "./dist/api/index.js",
       "default": "./dist/api/index.js"
     },
+    "./node": {
+      "types": "./dist/api/node-transport.d.ts",
+      "import": "./dist/api/node-transport.js",
+      "require": "./dist/api/node-transport.js",
+      "default": "./dist/api/node-transport.js"
+    },
     "./plugin-manifest": {
       "types": "./dist/api/plugin-manifest-schema.d.ts",
       "import": "./dist/api/plugin-manifest-schema.js",