@north-light/api 0.0.0 → 0.3.415

package/dist/api/client.js

@@ -0,0 +1,1388 @@
+// CrtrClient — the typed fetch client over crtrd's API.
+//
+// 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';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const LOCAL_SOCKET_FETCH = Symbol.for('@north-light/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;
+const HEALTHZ_POLL_INTERVAL_MS = 200;
+/** One strict wall-clock availability window shared by local API clients and
+ * daemon management. Each probe gets only the budget remaining at its start. */
+export async function waitForDaemonAvailability({ windowMs, probe, initialError, pollIntervalMs = HEALTHZ_POLL_INTERVAL_MS, retry = () => true, now = Date.now, sleep = sleepMs, }) {
+    const deadline = now() + windowMs;
+    let lastError = initialError;
+    for (;;) {
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            throw lastError ?? new Error('crtrd availability window expired without a probe failure');
+        try {
+            await probe(remaining);
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            if (!retry(error))
+                throw error;
+        }
+        const afterProbe = deadline - now();
+        if (afterProbe <= 0)
+            throw lastError;
+        await sleep(Math.min(pollIntervalMs, afterProbe));
+    }
+}
+/** The one error a call raises when its deadline passes (or a wait would pass it): status 504, code `deadline_exceeded`,
+ *  `details: { deadline_at, reason, retry_after_s? }`. */
+/** The longest delay a timer accepts (2^31-1 ms, about 24.8 days); a longer deadline would fire at once. */
+export const MAX_TIMER_MS = 2_147_483_647;
+export function deadlineExceeded(deadlineAt, reason = 'elapsed', retryAfterS) {
+    const message = reason === 'retry_after'
+        ? `the server asked to retry after ${retryAfterS}s, which is later than the call's deadline (${new Date(deadlineAt).toISOString()}); not waiting`
+        : `the call's deadline (${new Date(deadlineAt).toISOString()}) passed`;
+    return new ApiError(504, 'deadline_exceeded', message, {
+        deadline_at: deadlineAt, reason, ...(retryAfterS === undefined ? {} : { retry_after_s: retryAfterS }),
+    });
+}
+const budgetExhausted = (deadlineAt) => deadlineExceeded(deadlineAt ?? Date.now());
+export class CrtrClient {
+    baseUrl;
+    fetch;
+    headers;
+    autostart;
+    timeoutMs;
+    maxRetries;
+    localSocketTransport;
+    onColdSocket;
+    coldStartDiagnostic;
+    coldStartFailure;
+    coldStartPollWindowMs;
+    /** Set when the last availability wait ended on a daemon startup failure, whose message already says why. */
+    startupFailureReported = false;
+    /** Guards against invoking the daemon-start hook more than once per client. */
+    coldStartAttempted = false;
+    constructor(opts) {
+        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 ?? 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;
+        if (opts.coldStartFailure !== undefined)
+            this.coldStartFailure = opts.coldStartFailure;
+        this.coldStartPollWindowMs = opts.coldStartPollWindowMs ?? HEALTHZ_POLL_WINDOW_MS;
+    }
+    // Health / status
+    healthz() {
+        return this.request('GET', routes.healthz());
+    }
+    /** 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, { 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 = await response.clone().json();
+                if (typeof health.startup_blocked === 'string')
+                    return health;
+            }
+            catch {
+                // `parse` below reports malformed/non-health 503 responses normally.
+            }
+        }
+        return parse(response);
+    }
+    status() {
+        return this.request('GET', routes.status());
+    }
+    /** Busy and next-due state, the truth behind sandbox sleep and wake. */
+    due() {
+        return this.request('GET', routes.due());
+    }
+    /** Ask the daemon to replace itself with a successor running the currently
+     *  selected runtime generation. Answers before the handover starts, so a
+     *  caller living inside a node the handover will tear down still gets a
+     *  settled result. */
+    restartDaemon() {
+        return this.request('POST', routes.daemonRestart());
+    }
+    admitDaemon() {
+        return this.request('POST', routes.daemonAdmit());
+    }
+    migrateState(req) {
+        return this.request('POST', routes.daemonMigrate(), req);
+    }
+    // Nodes
+    appendNodeLog(id, req) {
+        return this.request('POST', routes.nodeLog(this.nodePath(id)), req);
+    }
+    async putNodeTelemetry(id, req) {
+        await this.request('PUT', routes.nodeTelemetry(this.nodePath(id)), req);
+    }
+    async putNodeRecap(id, req) {
+        await this.request('PUT', routes.nodeRecap(this.nodePath(id)), req);
+    }
+    readNodeInboxReport(id, ref, executionId) {
+        return this.request('GET', withQuery(routes.nodeInboxReport(this.nodePath(id)), { ref, execution_id: executionId }));
+    }
+    readNodePassiveMessage(id, ref) {
+        return this.request('GET', withQuery(routes.nodePassiveMessage(this.nodePath(id)), { ref }));
+    }
+    nodePushedFinal(id, req) {
+        return this.request('POST', routes.nodePushedFinal(this.nodePath(id)), req);
+    }
+    createNode(req) {
+        return this.request('POST', routes.nodes(), req);
+    }
+    /** List canvas nodes with composable row filters. `include: 'activity'` adds
+     * latest/canonical reports and pending-human counts in the same response. */
+    listNodes(q) {
+        return this.request('GET', withQuery(routes.nodes(), q));
+    }
+    getNode(id) {
+        return this.request('GET', routes.node(this.nodePath(id)));
+    }
+    /** Read a node outcome, optionally awaiting it for at most 25 seconds. This
+     * is a GET so the client can safely replay it across daemon handover. */
+    getNodeOutcome(id, { waitSeconds } = {}) {
+        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, { timeout: (waitSeconds ?? 0) * 1_000 + this.timeoutMs });
+    }
+    /** Open the raw server-sent event response for a node. The caller owns SSE
+     * parsing and must consume or cancel the response body. Streams deliberately
+     * have no client wall-clock timeout. */
+    getNodeEvents(id, query = {}, options = {}) {
+        if (query.after !== undefined && (!Number.isSafeInteger(query.after) || query.after < 0)) {
+            throw new RangeError('after must be a non-negative safe integer');
+        }
+        return this.transport('GET', withQuery(routes.nodeEvents(this.nodePath(id)), query), undefined, {
+            ...options,
+            headers: { accept: 'text/event-stream', ...(options.headers ?? {}) },
+            timeout: 0,
+        });
+    }
+    /** Parsed NDJSON hints, consumed eagerly and line by line. The caller must
+     * cancel with `signal` when done; no wall-clock timeout applies to the stream. */
+    async *getBrokerSignals(id, executionId, options = {}) {
+        const response = await this.send('GET', withQuery(routes.nodeBrokerSignals(this.nodePath(id)), { execution_id: executionId }), undefined, {
+            ...options, headers: { accept: 'application/x-ndjson', ...(options.headers ?? {}) }, timeout: 0,
+        });
+        if (!response.ok) {
+            await parse(response);
+            return;
+        }
+        if (response.body === null)
+            throw new ApiError(response.status, 'invalid_response', 'broker signal stream has no body');
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let newline;
+                while ((newline = buffer.indexOf('\n')) !== -1) {
+                    const line = buffer.slice(0, newline);
+                    buffer = buffer.slice(newline + 1);
+                    if (line !== '')
+                        yield JSON.parse(line);
+                }
+            }
+            buffer += decoder.decode();
+            if (buffer.trim() !== '')
+                throw new ApiError(502, 'invalid_response', 'broker signal stream ended mid-line');
+        }
+        finally {
+            await reader.cancel().catch(() => { });
+        }
+    }
+    // Structured requests
+    createStructuredRequest(req, options) {
+        // A synchronous admission is one held exchange. Replaying a POST after a
+        // reset can create work the caller has already stopped waiting for, and
+        // cold-socket recovery consumes its fixed end-to-end budget.
+        if (req.mode === 'sync')
+            return this.sendOnce('POST', '/v1/structured-requests', req, options);
+        return this.request('POST', '/v1/structured-requests', req, options);
+    }
+    getStructuredRequest(requestId, { wait = 0, budgetMs } = {}) {
+        if (!Number.isInteger(wait) || wait < 0 || wait > 25) {
+            throw new RangeError('wait must be an integer between 0 and 25');
+        }
+        return this.request('GET', withQuery(`/v1/structured-requests/${this.requestPath(requestId)}`, { wait }), undefined, { budgetMs });
+    }
+    cancelStructuredRequest(requestId, options) {
+        return this.request('POST', `/v1/structured-requests/${this.requestPath(requestId)}/cancel`, {}, options);
+    }
+    /** Register or replace an armed target for terminal-outcome delivery. */
+    registerOutcomeDelivery(id, req) {
+        return this.request('PUT', routes.nodeOutcomeDelivery(this.nodePath(id)), req);
+    }
+    getOutcomeDelivery(id) {
+        return this.request('GET', routes.nodeOutcomeDelivery(this.nodePath(id)));
+    }
+    /** Disarm an unsettled outcome-delivery registration. */
+    async disarmOutcomeDelivery(id) {
+        await this.request('DELETE', routes.nodeOutcomeDelivery(this.nodePath(id)));
+    }
+    listBashJobs(id) {
+        return this.request('GET', routes.nodeJobs(this.nodePath(id)));
+    }
+    stopBashJob(id, jobId) {
+        return this.request('DELETE', routes.nodeJob(this.nodePath(id), this.jobPath(jobId)));
+    }
+    sendMessage(id, req) {
+        return this.request('POST', routes.nodeMessages(this.nodePath(id)), req);
+    }
+    /** First-class interrupt (the human Esc): cancels pending undelivered
+     *  human-send inbox entries, then aborts a live in-flight turn. NEVER
+     *  revives a dormant target. */
+    interruptNode(id) {
+        return this.request('POST', routes.nodeInterrupt(this.nodePath(id)), {});
+    }
+    pushReport(id, req) {
+        return this.request('POST', routes.nodeReports(this.nodePath(id)), req);
+    }
+    submitResult(id, req) {
+        return this.request('POST', routes.nodeResult(this.nodePath(id)), req);
+    }
+    forkNode(id) {
+        return this.request('POST', routes.nodeFork(this.nodePath(id)), {});
+    }
+    reviveNode(id, req) {
+        return this.request('POST', routes.nodeRevive(this.nodePath(id)), req ?? {});
+    }
+    relaunchRoot(id) {
+        return this.request('POST', routes.nodeRelaunchRoot(this.nodePath(id)), {});
+    }
+    bindBrokerSession(id, req) {
+        return this.request('POST', routes.nodeBrokerSessionBound(this.nodePath(id)), req);
+    }
+    settleBroker(id, req) {
+        return this.request('POST', routes.nodeBrokerSettle(this.nodePath(id)), req);
+    }
+    completeBrokerPark(id, req) {
+        return this.request('POST', routes.nodeBrokerParkComplete(this.nodePath(id)), req);
+    }
+    recordBrokerParkActivity(id, req) {
+        return this.request('POST', routes.nodeBrokerParkActivity(this.nodePath(id)), req);
+    }
+    async recordBrokerTelemetry(id, req) {
+        await this.request('POST', routes.nodeBrokerTelemetry(this.nodePath(id)), req);
+    }
+    claimNodeMail(id, req) {
+        return this.request('POST', routes.nodeMailClaim(this.nodePath(id)), req);
+    }
+    acknowledgeNodeMail(id, req) {
+        return this.request('POST', routes.nodeMailAcknowledge(this.nodePath(id)), req);
+    }
+    recordBrokerTurn(id, req) {
+        return this.request('POST', routes.brokerTurn(this.nodePath(id)), req);
+    }
+    mutateBrokerProviderRetry(id, req) {
+        return this.request('POST', routes.brokerProviderRetry(this.nodePath(id)), req);
+    }
+    mutateBrokerFault(id, req) {
+        return this.request('POST', routes.brokerFault(this.nodePath(id)), req);
+    }
+    getBrokerRecovery(id, expectedExecutionId) {
+        return this.request('GET', `${routes.brokerRecovery(this.nodePath(id))}?expected_execution_id=${encodeURIComponent(expectedExecutionId)}`);
+    }
+    recordNodeFault(id, req) {
+        return this.request('POST', routes.nodeFault(this.nodePath(id)), req);
+    }
+    clearNodeFault(id, opts = {}) {
+        const query = new URLSearchParams();
+        if (opts.link !== undefined)
+            query.set('link', opts.link);
+        if (opts.preserve_episode !== undefined)
+            query.set('preserve_episode', String(opts.preserve_episode));
+        const suffix = query.size === 0 ? '' : `?${query.toString()}`;
+        return this.request('DELETE', `${routes.nodeFault(this.nodePath(id))}${suffix}`);
+    }
+    commitBrokerModel(id, req) {
+        return this.request('POST', routes.nodeBrokerModel(this.nodePath(id)), req);
+    }
+    brokerExtensionState(id) {
+        return this.request('GET', routes.nodeBrokerExtensionState(this.nodePath(id)));
+    }
+    commitBrokerGeneratedName(id, req) {
+        return this.request('POST', routes.nodeBrokerGeneratedName(this.nodePath(id)), req);
+    }
+    commitBrokerPersonaAck(id, req) {
+        return this.request('POST', routes.nodeBrokerPersonaAck(this.nodePath(id)), req);
+    }
+    closeNode(id, req) {
+        return this.request('POST', routes.nodeClose(this.nodePath(id)), req ?? {});
+    }
+    recycleNode(id) {
+        return this.request('POST', routes.nodeRecycle(this.nodePath(id)), {});
+    }
+    demoteNode(id) {
+        return this.request('POST', routes.nodeDemote(this.nodePath(id)), {});
+    }
+    promoteNode(id, req) {
+        return this.request('POST', routes.nodePromote(this.nodePath(id)), req);
+    }
+    yieldNode(id, req) {
+        return this.request('POST', routes.nodeYield(this.nodePath(id)), req);
+    }
+    waitNode(id, req) {
+        return this.request('POST', routes.nodeWait(this.nodePath(id)), req);
+    }
+    listKinds() {
+        return this.request('GET', routes.kinds());
+    }
+    /** A model change may first wait up to 30 s for a starting broker's view
+     *  socket and then 15 s for its ack, so it gets that budget on top. */
+    patchConfig(id, patch) {
+        return this.request('PATCH', routes.nodeConfig(this.nodePath(id)), patch, patch.model !== undefined ? { timeout: 45_000 + this.timeoutMs } : undefined);
+    }
+    /** Land + close the node's managed git worktree (spec §6.2). Server-side
+     *  because it interleaves a canvas WRITE with a git land transaction and
+     *  crtrd is the repo host (same principle as spawnChild's creation git). */
+    closeWorktree(id) {
+        return this.request('POST', routes.nodeWorktreeClose(this.nodePath(id)), {});
+    }
+    abandonWorktree(id, req) {
+        return this.request('POST', routes.nodeWorktreeAbandon(this.nodePath(id)), req);
+    }
+    /** Re-queue a permanently failed push delivery or daemon action with a fresh attempt budget. */
+    retryDelivery(deliveryId) {
+        return this.request('POST', routes.deliveryRetry(deliveryId), {});
+    }
+    listQuarantinedWorktrees() {
+        return this.request('GET', routes.quarantinedWorktrees());
+    }
+    /** Effective per-app memory and disk caps and whether this host enforces them. */
+    showLimits() {
+        return this.request('GET', routes.limits());
+    }
+    setAppLimits(app, req) {
+        return this.request('PUT', routes.limitsApp(app), req);
+    }
+    removeAppLimits(app, fields) {
+        return this.request('DELETE', withQuery(routes.limitsApp(app), { fields: fields.join(',') }));
+    }
+    /** Every space on the runtime with its size. */
+    listSpaces() {
+        return this.request('GET', routes.spaces());
+    }
+    subscribe(id, req) {
+        return this.request('POST', routes.nodeSubscriptions(this.nodePath(id)), req);
+    }
+    // Focuses (viewer registry)
+    // The tmux verbs that open/move/close a viewer pane run LOCALLY in the
+    // caller's session (placement-tmux); only the canvas.db focus rows route here.
+    // Reads GC lazily server-side, so a returned row is always live; a `null` body
+    // is the normal "no viewer" answer, not a 404.
+    listFocuses() {
+        return this.request('GET', routes.focuses());
+    }
+    focusOf(nodeId) {
+        return this.request('GET', withQuery(routes.focusByNode(), { node_id: nodeId }));
+    }
+    focusByPane(pane) {
+        return this.request('GET', withQuery(routes.focusByPane(), { pane }));
+    }
+    registerFocus(req) {
+        return this.request('POST', routes.focuses(), req);
+    }
+    async setFocusPane(focusId, req) {
+        await this.request('PATCH', routes.focus(focusId), req);
+    }
+    async closeFocus(focusId) {
+        await this.request('DELETE', routes.focus(focusId));
+    }
+    async unsubscribe(id, target) {
+        await this.request('DELETE', routes.nodeSubscription(this.nodePath(id), this.nodePath(target)));
+    }
+    /** Arm one cron (`POST /v1/crons`) — the server mints the cron_id. */
+    armCron(req) {
+        return this.request('POST', routes.crons(), req);
+    }
+    /** Crons visible to the caller (`GET /v1/crons`). With `q.profile` that is
+     *  that profile's crons plus every global one; omit it only for a
+     *  canvas-home-wide provenance read ("which crons did node X arm"). */
+    listCrons(q) {
+        return this.request('GET', withQuery(routes.crons(), q));
+    }
+    /** One cron with its run-log ring (`GET /v1/crons/:cronId`). */
+    showCron(cronId, q) {
+        return this.request('GET', withQuery(routes.cron(this.cronPath(cronId)), q));
+    }
+    /** Pause one cron (`POST /v1/crons/:cronId/pause`) — stops firing, keeps config+history. */
+    pauseCron(cronId, q) {
+        return this.request('POST', withQuery(routes.cronPause(this.cronPath(cronId)), q), {});
+    }
+    /** Resume one paused cron (`POST /v1/crons/:cronId/resume`). */
+    resumeCron(cronId, q) {
+        return this.request('POST', withQuery(routes.cronResume(this.cronPath(cronId)), q), {});
+    }
+    /** Run one cron NOW, out of band (`POST /v1/crons/:cronId/run`) — synchronous:
+     *  resolves with the settled run record after the subprocess closes. Does not
+     *  advance the schedule or consume a one-shot; never escalates. */
+    runCron(cronId, q) {
+        return this.request('POST', withQuery(routes.cronRun(this.cronPath(cronId)), q), {});
+    }
+    /** Cancel one cron (`DELETE /v1/crons/:cronId`, idempotent). */
+    async cancelCron(cronId, q) {
+        await this.request('DELETE', withQuery(routes.cron(this.cronPath(cronId)), q));
+    }
+    /** Bare eligibility poke (`POST /v1/crons/poke`): re-dues every held active
+     *  cron now — "something changed; re-check now". Canvas-wide, label-free,
+     *  idempotent, and free when nothing is held. */
+    pokeCrons() {
+        return this.request('POST', routes.cronsPoke(), {});
+    }
+    ensureAttach(id, req) {
+        return this.request('POST', routes.nodeAttach(this.nodePath(id)), req ?? {});
+    }
+    // Reads / feed
+    getReports(id, q) {
+        return this.request('GET', withQuery(routes.nodeReports(this.nodePath(id)), q));
+    }
+    getTranscript(id, q) {
+        return this.request('GET', withQuery(routes.nodeTranscript(this.nodePath(id)), q));
+    }
+    getSnapshot(id) {
+        return this.request('GET', routes.nodeSnapshot(this.nodePath(id)));
+    }
+    /** The node-config subject substrate gates evaluate against. */
+    nodeSubject(id) {
+        return this.request('GET', routes.nodeSubject(this.nodePath(id)));
+    }
+    getNodeMessages(id, q) {
+        return this.request('GET', withQuery(routes.nodeMessages(this.nodePath(id)), q));
+    }
+    /** The node's conversation exactly as it ran — raw `.jsonl` bytes plus the
+     *  assembled system prompt. For exports; `getSnapshot` is for renderers. */
+    getSession(id) {
+        return this.request('GET', routes.nodeSession(this.nodePath(id)));
+    }
+    /** What a non-terminal chat surface may offer for this node: the chat-capable
+     *  slash commands its live engine registered, and the memory documents an
+     *  inline `/name` token resolves to. Never revives — a node whose broker is
+     *  not live answers `broker_live: false` with empty arrays. */
+    getChatInventory(id) {
+        return this.request('GET', routes.nodeChatInventory(this.nodePath(id)));
+    }
+    getProspectiveChatInventory(q) {
+        return this.request('GET', withQuery(routes.prospectiveChatInventory(), q));
+    }
+    getContext(id) {
+        return this.request('GET', routes.nodeContext(this.nodePath(id)));
+    }
+    // Host file read
+    /** Read an absolute host path (capped, `truncated` when clipped). */
+    peekFile(path, encoding, options) {
+        return this.request('GET', withQuery(routes.filePeek(), { path, encoding }), undefined, options);
+    }
+    writeFile(path, content, encoding, options) {
+        return this.request('POST', routes.fileWrite(), { path, content, encoding }, options);
+    }
+    listFiles(path, limit, options) {
+        return this.request('GET', withQuery(routes.fileList(), { path, limit }), undefined, options);
+    }
+    runBash(params, options) {
+        return this.request('POST', routes.bash(), params, options);
+    }
+    // Canvas objects and documents
+    /** `crtr canvas` shared verbs. A ref is a name (with or without `[[ ]]`) or a raw object id. */
+    objects = {
+        read: (ref, query) => this.request('GET', withQuery(routes.object(ref), query)),
+        list: (query) => this.request('GET', withQuery(routes.objects(), query)),
+        search: (request) => this.request('POST', routes.objectsSearch(), request),
+        watch: (ref, request = {}) => this.request('POST', routes.objectWatch(ref), request),
+        unwatch: (ref, query) => this.request('DELETE', withQuery(routes.objectWatch(ref), query)),
+        edges: (ref, query) => this.request('GET', withQuery(routes.objectEdges(ref), query)),
+    };
+    /** `crtr doc` write verbs. */
+    docs = {
+        write: (request) => this.request('POST', routes.docs(), request),
+        edit: (ref, request) => this.request('PATCH', routes.doc(ref), request),
+        move: (ref, request) => this.request('POST', routes.docMove(ref), request),
+        delete: (ref) => this.request('DELETE', routes.doc(ref)),
+        history: (ref, query) => this.request('GET', withQuery(routes.docHistory(ref), query)),
+        lint: (request = {}) => this.request('POST', routes.docsLint(), request),
+    };
+    /** Package (builtin and plugin) documents. */
+    documents = {
+        reconcilePackages: () => this.request('POST', routes.documentsReconcilePackages()),
+    };
+    /** The broker's delivery of one node activity. */
+    nodeDelivery(id, request) {
+        return this.request('POST', routes.nodeDelivery(this.nodePath(id)), request);
+    }
+    /** A person's dry run of one delivery activity, for a live or hypothetical node. Writes nothing. */
+    deliveryDryRun(request) {
+        return this.request('POST', routes.deliveryDryRun(), request);
+    }
+    /** Record a backgrounded bash command as a job object. */
+    recordBackgroundedJob(id, jobId, request) {
+        return this.request('POST', routes.nodeJobBackground(this.nodePath(id), this.jobPath(jobId)), request);
+    }
+    // Profiles
+    /** Create-or-return by name. Supplied `projects` are shape-checked even when
+     *  the profile already exists; their directories are only required to exist
+     *  when this call creates the profile. */
+    ensureProfile(name, req) {
+        return this.request('PUT', routes.profile(name), req ?? {});
+    }
+    /** Create a profile of the caller's app; a name it already holds is refused. */
+    createProfile(req) {
+        return this.request('POST', routes.profiles(), req);
+    }
+    listProfiles() {
+        return this.request('GET', routes.profiles());
+    }
+    /** Rename, set the default kind, or add or remove one project. */
+    updateProfile(name, req) {
+        return this.request('PATCH', routes.profile(name), req);
+    }
+    listAppEnv() {
+        return this.request('GET', routes.appEnv());
+    }
+    setAppEnv(variable, value) {
+        return this.request('PUT', routes.appEnvVar(variable), { value });
+    }
+    removeAppEnv(variable) {
+        return this.request('DELETE', routes.appEnvVar(variable));
+    }
+    listProfileEnv(name) {
+        return this.request('GET', routes.profileEnv(name));
+    }
+    setProfileEnv(name, variable, value) {
+        return this.request('PUT', routes.profileEnvVar(name, variable), { value });
+    }
+    removeProfileEnv(name, variable) {
+        return this.request('DELETE', routes.profileEnvVar(name, variable));
+    }
+    getProfile(name) {
+        return this.request('GET', routes.profile(name));
+    }
+    pauseProfile(name) {
+        return this.request('POST', routes.profilePause(name), {});
+    }
+    resumeProfile(name) {
+        return this.request('POST', routes.profileResume(name), {});
+    }
+    /** Merge and remove entries in a profile's metadata map. */
+    updateProfileMetadata(name, req) {
+        return this.request('PATCH', routes.profileMetadata(name), req);
+    }
+    /** Force-delete or detach one profile by exact id or unique name. */
+    deleteProfile(name, req) {
+        return this.request('DELETE', routes.profile(name), req);
+    }
+    // Model auth
+    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);
+    }
+    removeCredential(provider) {
+        return this.request('DELETE', routes.modelAuth(provider));
+    }
+    /** `model_auth.start` — the daemon runs the vendor OAuth; the caller only shows `url`. */
+    startModelAuth(req) {
+        return this.request('POST', routes.modelAuthFlows(), req, { timeout: 30_000 + this.timeoutMs });
+    }
+    /** `model_auth.complete` — hand the daemon the code the vendor showed. */
+    completeModelAuth(flowId, req) {
+        return this.request('POST', routes.modelAuthFlowComplete(flowId), req, { timeout: 35_000 + this.timeoutMs });
+    }
+    /** `model_auth.cancel` — end an in-flight flow the person gave up on; it writes nothing. */
+    cancelModelAuth(flowId) {
+        return this.request('POST', routes.modelAuthFlowCancel(flowId), {});
+    }
+    /** A flow's state; `waitSeconds` (1-25) long-polls until it leaves `pending`. */
+    getModelAuthFlow(flowId, waitSeconds) {
+        return this.request('GET', withQuery(routes.modelAuthFlow(flowId), { wait: waitSeconds }), undefined, { timeout: (waitSeconds ?? 0) * 1_000 + this.timeoutMs });
+    }
+    // Daemon-owned document reviews and comments
+    createReview(req) {
+        return this.request('POST', routes.humanReviews(), req);
+    }
+    listReviews(query) {
+        return this.request('GET', withQuery(routes.humanReviews(), query));
+    }
+    getReview(reviewId) {
+        return this.request('GET', routes.humanReview(this.reviewPath(reviewId)));
+    }
+    submitReview(reviewId) {
+        return this.request('POST', routes.humanReviewSubmit(this.reviewPath(reviewId)), {});
+    }
+    cancelReview(reviewId, req = {}) {
+        return this.request('POST', routes.humanReviewCancel(this.reviewPath(reviewId)), req);
+    }
+    getReviewDocumentBase(reviewId) {
+        return this.request('GET', routes.humanReviewDocument(this.reviewPath(reviewId)));
+    }
+    createReviewComment(reviewId, req) {
+        const path = reviewId === undefined ? 'self' : this.reviewPath(reviewId);
+        return this.request('POST', routes.humanReviewComments(path), req);
+    }
+    listReviewComments(reviewId, query) {
+        const path = reviewId === undefined ? 'self' : this.reviewPath(reviewId);
+        return this.request('GET', withQuery(routes.humanReviewComments(path), query));
+    }
+    readReviewCommentEvents(reviewId, query) {
+        return this.request('GET', withQuery(routes.humanReviewCommentEvents(this.reviewPath(reviewId)), query));
+    }
+    updateReviewCommentRanges(reviewId, req) {
+        return this.request('POST', routes.humanReviewCommentRanges(this.reviewPath(reviewId)), req);
+    }
+    getReviewComment(commentId) {
+        return this.request('GET', routes.humanComment(this.commentPath(commentId)));
+    }
+    editReviewComment(commentId, req) {
+        return this.request('POST', routes.humanCommentEdit(this.commentPath(commentId)), req);
+    }
+    resolveReviewComment(commentId, req = {}) {
+        return this.request('POST', routes.humanCommentResolve(this.commentPath(commentId)), req);
+    }
+    reopenReviewComment(commentId, req = {}) {
+        return this.request('POST', routes.humanCommentReopen(this.commentPath(commentId)), req);
+    }
+    deleteReviewComment(commentId, req = {}) {
+        return this.request('POST', routes.humanCommentDelete(this.commentPath(commentId)), req);
+    }
+    forkReviewComment(commentId) {
+        return this.request('POST', routes.humanCommentFork(this.commentPath(commentId)), {});
+    }
+    // ---- Humanloop inbox (crouter cloud crouter-inbox v1, inbox-contract.md §A) --
+    /** Pending page/review tickets across every available crouter-owned
+     *  humanloop root. */
+    listHumanInbox() {
+        return this.request('GET', routes.humanInbox());
+    }
+    /** Read one page ticket by its opaque ticket id (pending, resolved, or canceled). */
+    getHumanInboxPage(ticketId) {
+        return this.request('GET', routes.humanInboxTicket(this.ticketId(ticketId)));
+    }
+    /** All page tickets, oldest first (pending, resolved, or canceled) —
+     *  home-wide, or narrowed to one raising node when `nodeId` is given. */
+    getInboxHistory(nodeId) {
+        if (nodeId === undefined) {
+            return this.request('GET', routes.humanInbox() + '/history');
+        }
+        if (typeof nodeId !== 'string' || nodeId === '') {
+            throw new TypeError(`invalid node id: ${JSON.stringify(nodeId)}`);
+        }
+        return this.request('GET', withQuery(routes.humanInbox() + '/history', { node_id: nodeId }));
+    }
+    /** Submit responses for a page ticket. Single-assignment server-side: a competing
+     *  resolution races to `ticket_already_resolved`. */
+    respondHumanInboxPage(ticketId, request) {
+        return this.request('POST', routes.humanInboxRespond(this.ticketId(ticketId)), request);
+    }
+    /** Autosave partial page work. Omitted slots are permitted in progress updates. */
+    postInboxProgress(ticketId, responses) {
+        return this.request('POST', routes.humanInboxProgress(this.ticketId(ticketId)), { responses });
+    }
+    /** Get the published response for a resolved page ticket. 404 if pending or canceled. */
+    getInboxResponse(ticketId) {
+        return this.request('GET', routes.humanInboxResponse(this.ticketId(ticketId)));
+    }
+    /** Cancel a ticket (terminal response, never deletion). */
+    cancelHumanInboxTicket(ticketId, request) {
+        return this.request('POST', routes.humanInboxCancel(this.ticketId(ticketId)), request ?? {});
+    }
+    // Durable programmatic human requests
+    /** Create one durable human request. The minted `request_id` identifies the
+     *  request; inbox presentation has its own ticket id. An unresolvable
+     *  `action.name` is rejected before the page is published, leaving no inbox
+     *  row behind. */
+    createHumanRequest(request) {
+        return this.request('POST', routes.humanRequests(), request);
+    }
+    /** Product page components registered on the runtime (config + enabled plugins). */
+    listPageComponents() {
+        return this.request('GET', routes.humanComponents());
+    }
+    /** Read one request: its current state, its answer when answered, and the
+     *  delivery state of its completion action when it bound one. */
+    getHumanRequest(requestId) {
+        return this.request('GET', routes.humanRequest(this.requestPath(requestId)));
+    }
+    /** Revise a pending request's page in place. Identity, provenance, and the
+     *  frozen action binding are preserved; a settled request refuses. */
+    replaceHumanRequest(requestId, request) {
+        return this.request('POST', routes.humanRequestReplace(this.requestPath(requestId)), request);
+    }
+    /** Settle a request `answered` programmatically. Races a human answer to the
+     *  same first-writer-wins result. */
+    respondHumanRequest(requestId, request) {
+        return this.request('POST', routes.humanRequestRespond(this.requestPath(requestId)), request);
+    }
+    /** The recipient surface closing a request without answering. */
+    dismissHumanRequest(requestId, request = {}) {
+        return this.request('POST', routes.humanRequestDismiss(this.requestPath(requestId)), request);
+    }
+    /** The requester withdrawing its own request. */
+    cancelHumanRequest(requestId, request = {}) {
+        return this.request('POST', routes.humanRequestCancel(this.requestPath(requestId)), request);
+    }
+    /** Resolve one page feedback comment — the bound companion's report that it
+     *  has been dealt with. `nodeId` names the caller; the daemon refuses any
+     *  node but the ticket's companion. Terminal for the comment; appends no
+     *  chat turn. */
+    resolvePageFeedbackComment(ticketId, commentId, nodeId) {
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(commentId)) {
+            throw new TypeError(`invalid feedback comment id: ${JSON.stringify(commentId)}`);
+        }
+        return this.request('POST', routes.humanInboxFeedbackResolve(this.ticketId(ticketId), commentId), { node_id: nodeId });
+    }
+    // Canvas reads / maintenance
+    /** Composed client-side from `GET /v1/nodes` + `GET /v1/status` (spec §6.3 —
+     *  the dashboard is absorbed into those two reads; there is no single route).
+     *  `generated_at` is the client-side capture instant of the composition. */
+    async dashboard(q) {
+        const listQuery = q?.under !== undefined ? { under: q.under } : undefined;
+        const [nodes, status] = await Promise.all([this.listNodes(listQuery), this.status()]);
+        return { nodes, counts: status.node_counts, generated_at: new Date().toISOString() };
+    }
+    attention() {
+        return this.request('GET', routes.canvasAttention());
+    }
+    /** Per-node pending-ticket counts for a bounded viewer slice. */
+    attentionCounts(node_ids) {
+        const body = { node_ids };
+        return this.request('POST', routes.canvasAttentionCounts(), body);
+    }
+    /** Ranked/filtered content search over the per-cwd episodic corpus
+     *  (`crtr canvas history search`). Optional query: ranked when present,
+     *  recency browse when omitted. POST-bodied — the query carries arrays and
+     *  free text; the whole search executes server-side (spec §6.3). */
+    historySearch(q) {
+        return this.request('POST', routes.canvasHistorySearch(), q);
+    }
+    /** Required-pattern line-hit search over the per-cwd episodic corpus
+     *  (`crtr canvas history grep`). Distinct stable schema from `historySearch`
+     *  — POST-bodied for the same reasons. */
+    historyGrep(q) {
+        return this.request('POST', routes.canvasHistoryGrep(), q);
+    }
+    /** Resolve one `<node-id>:<relpath>` history ref to its full body
+     *  (`crtr canvas history read`). */
+    historyRead(q) {
+        return this.request('GET', withQuery(routes.canvasHistoryRead(), q));
+    }
+    /** Grouped-count projection over the per-cwd episodic corpus
+     *  (`crtr canvas history stats`). Same filters as search/grep, aggregate
+     *  result instead of a hit page — POST-bodied for the same reasons. */
+    historyStats(q) {
+        return this.request('POST', routes.canvasHistoryStats(), q);
+    }
+    /** The machine-readable browser canvas roster (`crtr canvas snapshot`) —
+     *  distinct from the per-node `getSnapshot`. */
+    canvasSnapshot() {
+        return this.request('GET', routes.canvasSnapshot());
+    }
+    /** The Analytics page model (`GET /v1/canvas/analytics`). The
+     *  daemon scans transcripts for the window: a cold 7d scan of ~2 GB of
+     *  transcripts measured 10 s, and with scan workers capped at 4 a queued
+     *  request waits about one scan more. 60 s is 3x that worst case; past it the
+     *  page shows the error instead of computing forever. */
+    analytics(q) {
+        return this.request('GET', withQuery(routes.canvasAnalytics(), q), undefined, { timeout: 60_000 });
+    }
+    /** Record memory reads/loads for one node (`POST /v1/nodes/:id/memory-reads`). */
+    async recordMemoryReads(nodeId, body) {
+        await this.request('POST', routes.nodeMemoryReads(this.nodePath(nodeId)), body);
+    }
+    /** The lean, set-based topology roster (`GET /v1/canvas/roster`) — exactly
+     *  two indexed queries server-side, no per-row enrichment. The recurring
+     *  poll target for attach/browser topology; use `canvasSnapshot` for the
+     *  enriched on-demand view. */
+    canvasRoster() {
+        return this.request('GET', routes.canvasRoster());
+    }
+    /** Explicitly compressed browse snapshot; the Node-only canvas source
+     * decompresses it because socketFetch does not interpret content-encoding. */
+    async canvasBrowseCompressed() {
+        const response = await this.send('GET', routes.canvasBrowse());
+        if (!response.ok)
+            await parse(response); // retain the normal structured API error
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    /** The lean attach-graph projection: display rows, topology, and focus state
+     * in one daemon-owned read rather than the full node-summary list. */
+    canvasGraph() {
+        return this.request('GET', routes.canvasGraph());
+    }
+    prune(req) {
+        return this.request('POST', routes.canvasPrune(), req);
+    }
+    // Escape hatch
+    /** Raw request for routes not yet method-wrapped. Applies the same
+     *  autostart + retry + error-mapping semantics. */
+    async request(method, path, body, opts) {
+        try {
+            // The deadline is fixed once here so the headers, the retries and the reading of the body share it.
+            const resolved = opts === undefined ? undefined : this.resolveBudget(opts);
+            const response = await this.send(method, path, body, resolved);
+            return await parse(response, resolved?.deadlineAt);
+        }
+        catch (error) {
+            throw toTransportApiError(error, opts?.signal);
+        }
+    }
+    /** Open a live response with the normal cold-socket and retry policy, without consuming its body. */
+    async rawResponse(method, path, opts) {
+        try {
+            return await this.send(method, path, undefined, opts);
+        }
+        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, callOpts = {}) {
+        const opts = this.resolveBudget(callOpts);
+        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, opts.deadlineAt);
+                        response = await this.transport(method, path, body, opts);
+                    }
+                    catch (recoveryError) {
+                        // The caller's deadline, not the last probe failure, is why the call stopped when it has passed.
+                        if (opts.deadlineAt !== undefined && Date.now() >= opts.deadlineAt && !isAbortError(recoveryError, opts.signal))
+                            throw deadlineExceeded(opts.deadlineAt);
+                        throw toTransportApiError(recoveryError, opts.signal);
+                    }
+                }
+                else if (this.isInterruptedSocketError(err) && this.localSocketTransport && (!idempotent || attempt < maxRetries)) {
+                    return await this.rideOutInterruptedRequest(method, path, body, opts);
+                }
+                else if (idempotent && attempt < maxRetries && !isAbortError(err, opts.signal) && (!this.localSocketTransport || !this.isInterruptedSocketError(err))) {
+                    await sleepWithin(retryDelayMs(attempt + 1), opts);
+                    continue;
+                }
+                else {
+                    throw toTransportApiError(err, opts.signal);
+                }
+            }
+            if (idempotent && attempt < maxRetries && isRetryableStatus(response.status)) {
+                await drainResponseBody(response, opts.deadlineAt);
+                await sleepWithin(retryDelayMs(attempt + 1), opts, retryAfterHeaderS(response));
+                continue;
+            }
+            return response;
+        }
+    }
+    // internals
+    resolveBudget(opts) {
+        const { budgetMs, deadlineAt, ...rest } = opts;
+        if (budgetMs === undefined && deadlineAt === undefined)
+            return rest;
+        if (budgetMs !== undefined && (!Number.isFinite(budgetMs) || budgetMs <= 0 || budgetMs > MAX_TIMER_MS))
+            throw new RangeError(`budgetMs must be a positive finite number of at most ${MAX_TIMER_MS}`);
+        if (deadlineAt !== undefined && (!Number.isFinite(deadlineAt) || deadlineAt - Date.now() > MAX_TIMER_MS))
+            throw new RangeError(`deadlineAt must be a finite epoch-millisecond instant at most ${MAX_TIMER_MS} ms from now`);
+        return { ...rest, deadlineAt: Math.min(deadlineAt ?? Infinity, budgetMs === undefined ? Infinity : Date.now() + budgetMs) };
+    }
+    async awaitWithinBudget(promise, deadlineAt) {
+        if (deadlineAt === undefined)
+            return promise;
+        const remainingMs = deadlineAt - Date.now();
+        if (remainingMs <= 0)
+            throw budgetExhausted(deadlineAt);
+        let timer;
+        try {
+            return await Promise.race([
+                promise,
+                new Promise((_resolve, reject) => { timer = setTimeout(() => reject(budgetExhausted(deadlineAt)), remainingMs); }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    /** One transport attempt, deliberately without retry, cold-socket, or interrupted-response recovery. */
+    async sendOnce(method, path, body, callOpts = {}) {
+        const opts = this.resolveBudget(callOpts);
+        try {
+            return await parse(await this.transport(method, path, body, opts));
+        }
+        catch (error) {
+            throw toTransportApiError(error, opts.signal);
+        }
+    }
+    nodePath(id) {
+        if (!isSafeNodeId(id)) {
+            throw new ApiError(400, 'invalid_node_id', `invalid node id: ${JSON.stringify(id)}`);
+        }
+        return id;
+    }
+    /** Validate a background job id before route construction. Job ids arrive
+     *  from the daemon's file-backed roster and must remain one path segment. */
+    jobPath(id) {
+        if (!isSafeBashJobId(id)) {
+            throw new ApiError(400, 'invalid_job_id', `invalid background job id: ${JSON.stringify(id)}`);
+        }
+        return id;
+    }
+    /** Validate a cron id before route construction — `routes.ts` interpolates
+     *  it raw, so a value carrying `/`, whitespace or `?` would corrupt the
+     *  request line rather than 404 cleanly. Mirrors `nodePath`. */
+    cronPath(id) {
+        if (!isSafeCronId(id)) {
+            throw new ApiError(400, 'invalid_cron_id', `invalid cron id: ${JSON.stringify(id)}`);
+        }
+        return id;
+    }
+    /** Validate a request id before route construction. Requests use the daemon's
+     * node-id-shaped identifiers, while inbox presentation uses a separate ticket
+     * id. A malformed request id is a server-rejectable request. */
+    requestPath(id) {
+        if (!isSafeNodeId(id)) {
+            throw new ApiError(400, 'invalid_request_id', `invalid request id: ${JSON.stringify(id)}`);
+        }
+        return id;
+    }
+    /** Validate an opaque inbox ticket id before route construction. A local
+     *  shape violation is a caller bug, not a server-rejectable request — throws
+     *  `TypeError` (matching the existing safe-segment discipline of a local
+     *  precondition, distinct from `nodePath`'s `ApiError` because that one IS a
+     *  request the server could plausibly receive and reject itself). */
+    ticketId(id) {
+        if (!/^[a-f0-9]{64}$/.test(id)) {
+            throw new TypeError(`invalid inbox ticket id: ${JSON.stringify(id)}`);
+        }
+        return id;
+    }
+    /** Validate a review id before route construction (D-A6). Reviews are minted
+     *  and addressed like node ids, but arrive from agent argv, so a malformed
+     *  one is a plausible request the server would also reject — `ApiError`,
+     *  not `TypeError`, matching `nodePath`. */
+    reviewPath(id) {
+        if (!isSafeNodeId(id)) {
+            throw new ApiError(400, 'invalid_review_id', `invalid review id: ${JSON.stringify(id)}`);
+        }
+        return id;
+    }
+    /** Validate a comment id before route construction (D-A6). Comment ids are
+     *  daemon-minted 32-char lowercase hex, but — like `reviewPath` — arrive from
+     *  agent argv, so a bad one is a plausible request the server would also
+     *  reject, not a caller-bug `TypeError` like `ticketId`. */
+    commentPath(id) {
+        if (!/^[a-f0-9]{32}$/.test(id)) {
+            throw new ApiError(400, 'invalid_comment_id', `invalid comment id: ${JSON.stringify(id)}`);
+        }
+        return id;
+    }
+    /** 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 remainingBudgetMs = opts.deadlineAt === undefined ? undefined : opts.deadlineAt - Date.now();
+        if (remainingBudgetMs !== undefined && remainingBudgetMs <= 0)
+            return Promise.reject(budgetExhausted(opts.deadlineAt));
+        const payload = body === undefined ? undefined : JSON.stringify(body);
+        const headers = { accept: 'application/json', ...this.headers, ...opts.headers };
+        if (payload !== undefined)
+            headers['content-type'] = 'application/json';
+        const baseTimeoutMs = opts.timeout ?? this.timeoutMs;
+        const timeoutMs = remainingBudgetMs === undefined
+            ? baseTimeoutMs
+            : baseTimeoutMs > 0 ? Math.min(baseTimeoutMs, remainingBudgetMs) : remainingBudgetMs;
+        const controller = new AbortController();
+        // The deadline, not the per-attempt timeout, ended this attempt when it was the nearer of the two.
+        const deadlineEnds = remainingBudgetMs !== undefined && (baseTimeoutMs <= 0 || remainingBudgetMs <= baseTimeoutMs);
+        const timer = timeoutMs > 0
+            ? setTimeout(() => controller.abort(deadlineEnds ? budgetExhausted(opts.deadlineAt) : 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 finish = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            externalSignal?.removeEventListener('abort', onExternalAbort);
+        };
+        return abortable(this.fetch(new URL(path, this.baseUrl), { method, headers, body: payload, signal: controller.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;
+        }
+        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();
+                    }
+                    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) {
+        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) {
+        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, opts = {}) {
+        try {
+            await this.awaitAvailability(undefined, opts.deadlineAt);
+        }
+        catch (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, opts);
+        }
+        catch (err) {
+            throw toTransportApiError(err, opts.signal);
+        }
+    }
+    async awaitAvailability(initialError, deadlineAt) {
+        const remainingBudgetMs = deadlineAt === undefined ? undefined : deadlineAt - Date.now();
+        if (remainingBudgetMs !== undefined && remainingBudgetMs <= 0)
+            throw budgetExhausted(deadlineAt);
+        let startupFailure;
+        try {
+            await waitForDaemonAvailability({
+                windowMs: Math.min(this.coldStartPollWindowMs, remainingBudgetMs ?? this.coldStartPollWindowMs),
+                initialError,
+                retry: (error) => error !== startupFailure,
+                probe: async (timeoutMs) => {
+                    const failure = this.coldStartFailure?.();
+                    if (failure !== undefined) {
+                        startupFailure = new ApiError(503, 'daemon_unavailable', `crtrd failed to start: ${failure}`);
+                        throw startupFailure;
+                    }
+                    const response = await this.transport('GET', routes.healthz(), undefined, { timeout: timeoutMs });
+                    if (response.status >= 200 && response.status < 300) {
+                        await drainResponseBody(response);
+                        return;
+                    }
+                    const text = await response.text();
+                    try {
+                        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}: ${text.slice(0, 500)}`);
+                },
+            });
+        }
+        catch (error) {
+            if (error === startupFailure)
+                this.startupFailureReported = true;
+            throw error;
+        }
+    }
+    /** Optionally start the daemon, then observe availability before retrying the
+     * request. Waiting is independent from permission to spawn: externally
+     * managed daemons still get the same bounded readiness window. */
+    async handleColdSocket(initialError, deadlineAt) {
+        const startedHere = this.autostart && this.onColdSocket !== undefined && !this.coldStartAttempted;
+        if (startedHere) {
+            this.coldStartAttempted = true;
+            await this.awaitWithinBudget(this.onColdSocket(), deadlineAt);
+        }
+        try {
+            await this.awaitAvailability(initialError, deadlineAt);
+        }
+        catch (error) {
+            if (startedHere && !this.startupFailureReported) {
+                const diagnostic = safeColdStartDiagnostic(this.coldStartDiagnostic);
+                if (diagnostic !== undefined) {
+                    const transportError = toTransportApiError(error);
+                    throw new ApiError(transportError.status, transportError.code, `${transportError.message}\n${diagnostic}`);
+                }
+            }
+            throw error;
+        }
+    }
+}
+/** Append defined query params to a path. Kept in the client (not `routes.ts`,
+ *  which stays logic-free). Undefined/null values are skipped. */
+function withQuery(base, query) {
+    if (query === undefined)
+        return base;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== null)
+            params.set(key, String(value));
+    }
+    const qs = params.toString();
+    return qs === '' ? base : `${base}?${qs}`;
+}
+/** 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, deadlineAt) {
+    const ok = res.status >= 200 && res.status < 300;
+    const trimmed = (await readTextWithin(res, deadlineAt)).trim();
+    let payload;
+    if (trimmed !== '') {
+        try {
+            payload = JSON.parse(trimmed);
+        }
+        catch {
+            if (ok)
+                return undefined;
+            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, res.headers, payload.error);
+    }
+    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, deadlineAt) {
+    const cancelled = (async () => {
+        try {
+            await res.body?.cancel();
+        }
+        catch {
+            // Best-effort — the response is being discarded either way.
+        }
+    })();
+    // A body whose cancel never settles must not hold the call past its deadline: stop waiting for it then.
+    if (deadlineAt === undefined)
+        return cancelled;
+    let timer;
+    try {
+        await Promise.race([cancelled, new Promise((resolve) => { timer = setTimeout(resolve, Math.max(0, deadlineAt - Date.now())); })]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** The response body as text, or `deadline_exceeded` once `deadlineAt` passes first (the body is then cancelled
+ *  without waiting for it). A transport that sends headers and then stalls cannot hold the call past its deadline. */
+async function readTextWithin(res, deadlineAt) {
+    if (deadlineAt === undefined)
+        return res.text();
+    const remaining = deadlineAt - Date.now();
+    const reading = res.text();
+    reading.catch(() => { });
+    if (remaining <= 0) {
+        void res.body?.cancel().catch(() => { });
+        throw deadlineExceeded(deadlineAt);
+    }
+    let timer;
+    try {
+        return await Promise.race([
+            reading,
+            new Promise((_resolve, reject) => { timer = setTimeout(() => { void res.body?.cancel().catch(() => { }); reject(deadlineExceeded(deadlineAt)); }, remaining); }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** 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, signal) {
+    if (signal?.aborted) {
+        return new ApiError(0, 'request_aborted', 'request aborted by caller signal');
+    }
+    if (err instanceof ApiError)
+        return err;
+    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}`);
+    }
+    if (code === 'ETIMEDOUT') {
+        // A per-request timeout against a REACHABLE daemon is not "crtrd not running"
+        // (§8 reserves daemon_unavailable for unreachable/autostart-failed).
+        return new ApiError(504, 'request_timeout', `crtrd request timed out: ${message}`);
+    }
+    return new ApiError(503, 'transport_error', message);
+}
+/** The `Retry-After` header as seconds (delta-seconds form only), else undefined. */
+function retryAfterHeaderS(response) {
+    const seconds = Number(response.headers.get('retry-after'));
+    return Number.isFinite(seconds) && seconds > 0 ? seconds : undefined;
+}
+/** One retry wait inside a call's deadline. A server-requested wait (`retryAfterS`) is honored only against a deadline:
+ *  when it would not finish before the deadline the call fails now with `deadline_exceeded` (`reason: 'retry_after'`)
+ *  instead of sleeping past it; a call without a deadline keeps the plain backoff. The sleep ends early, with the same
+ *  error, if the caller aborts. */
+export async function sleepWithin(backoffMs, opts, retryAfterS, cause) {
+    const { deadlineAt, signal } = opts;
+    if (signal?.aborted)
+        throw new ApiError(0, 'request_aborted', 'request aborted by caller signal');
+    const requestedMs = deadlineAt !== undefined && retryAfterS !== undefined ? retryAfterS * 1_000 : undefined;
+    const waitMs = Math.max(backoffMs, requestedMs ?? 0);
+    if (deadlineAt !== undefined && Date.now() + waitMs >= deadlineAt) {
+        const error = deadlineExceeded(deadlineAt, requestedMs !== undefined && requestedMs >= backoffMs ? 'retry_after' : 'elapsed', requestedMs === undefined ? undefined : retryAfterS);
+        if (cause !== undefined)
+            Object.defineProperty(error, 'cause', { value: cause, configurable: true, writable: true });
+        throw error;
+    }
+    if (signal === undefined)
+        return sleepMs(waitMs);
+    await new Promise((resolve, reject) => {
+        const onAbort = () => { clearTimeout(timer); signal.removeEventListener('abort', onAbort); reject(new ApiError(0, 'request_aborted', 'request aborted by caller signal')); };
+        const timer = setTimeout(() => { signal.removeEventListener('abort', onAbort); resolve(); }, waitMs);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/** `pending`, or its rejection with the signal's reason once the signal aborts first. A transport that ignores its
+ *  signal (a custom `fetch`) therefore still ends at the call's deadline; a response that arrives after the abort is
+ *  discarded and its body cancelled. */
+function abortable(pending, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener('abort', onAbort, { once: true });
+        pending.then((response) => {
+            signal.removeEventListener('abort', onAbort);
+            if (signal.aborted)
+                void response.body?.cancel().catch(() => { });
+            else
+                resolve(response);
+        }, (error) => { signal.removeEventListener('abort', onAbort); reject(error); });
+    });
+}
+function sleepMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function safeColdStartDiagnostic(hook) {
+    if (hook === undefined)
+        return undefined;
+    try {
+        return hook();
+    }
+    catch {
+        return undefined;
+    }
+}