@north-light/crouter-api 0.3.156

package/dist/client.js

@@ -0,0 +1,611 @@
+// CrtrClient — the typed HTTP+WS client over crtrd's API (spec §3.4).
+//
+// 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). Absent the hook,
+// a cold socket throws `daemon_unavailable` immediately.
+//
+// TRANSPORT (spec O-1): `node:http`/`node:https` `request()` — NO `undici`.
+// unix socket via `{ socketPath }`; TCP/remote via a parsed `baseUrl`.
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ApiError, isErrorBody } from './errors.js';
+import { routes } from './routes.js';
+import { isSafeNodeId } from './dto/common.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 = process.env['CRTR_HOME'];
+    const home = override !== undefined && override !== ''
+        ? override
+        : join(homedir(), CRTR_DIR_NAME, 'canvas');
+    return join(home, SOCKET_BASENAME);
+}
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** 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;
+export class CrtrClient {
+    socketPath;
+    baseUrl;
+    headers;
+    autostart;
+    timeoutMs;
+    onColdSocket;
+    coldStartDiagnostic;
+    coldStartPollWindowMs;
+    /** Guards against re-entering the autostart path 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);
+        this.headers = { ...opts.headers };
+        this.autostart = opts.autostart ?? hasSocket;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        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());
+    }
+    status() {
+        return this.request('GET', routes.status());
+    }
+    /** 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());
+    }
+    // ---- Nodes -------------------------------------------------------------
+    createNode(req) {
+        return this.request('POST', routes.nodes(), req);
+    }
+    listNodes(q) {
+        return this.request('GET', withQuery(routes.nodes(), q));
+    }
+    getNode(id) {
+        return this.request('GET', routes.node(this.nodePath(id)));
+    }
+    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);
+    }
+    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)), {});
+    }
+    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);
+    }
+    patchConfig(id, patch) {
+        return this.request('PATCH', routes.nodeConfig(this.nodePath(id)), patch);
+    }
+    /** 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)), {});
+    }
+    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));
+    }
+    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)));
+    }
+    getArtifacts(id, q) {
+        return this.request('GET', withQuery(routes.nodeArtifacts(this.nodePath(id)), q));
+    }
+    getContext(id) {
+        return this.request('GET', routes.nodeContext(this.nodePath(id)));
+    }
+    // ---- Host file read ----------------------------------------------------
+    /** Read an absolute host path as UTF-8 (capped, `truncated` when clipped) for
+     *  the browser file-peek panel. */
+    peekFile(path) {
+        return this.request('GET', withQuery(routes.filePeek(), { path }));
+    }
+    // ---- Profiles ----------------------------------------------------------
+    ensureProfile(name, req) {
+        return this.request('PUT', routes.profile(name), req ?? {});
+    }
+    listProfiles() {
+        return this.request('GET', routes.profiles());
+    }
+    getProfile(name) {
+        return this.request('GET', routes.profile(name));
+    }
+    /** Delete one profile by exact id or unique name (`DELETE /v1/profiles/:name`,
+     *  idempotent — a miss is success). */
+    async deleteProfile(name) {
+        await this.request('DELETE', routes.profile(name));
+    }
+    // ---- Model auth --------------------------------------------------------
+    installCredential(provider, req) {
+        return this.request('PUT', routes.modelAuth(provider), req);
+    }
+    // ---- Human bridge + completion-handler forwarding (spec §6.5) ----------
+    /** Create a terminal `kind:'human'` bridge node with NO broker engine
+     *  (`spawnNode` server-side). Distinct from `createNode` (which launches a
+     *  broker) precisely because a human bridge must never have one. */
+    createHumanBridge(req) {
+        return this.request('POST', routes.humanBridge(), req);
+    }
+    /** Run the registered humanloop completion handler server-side for one
+     *  `humanloop.completion/v1` event. crtrd re-verifies the full trust binding
+     *  before performing any canvas mutation. */
+    deliverHuman(event) {
+        return this.request('POST', routes.humanDeliver(), event);
+    }
+    /** Run the registered follow-up handler server-side for one
+     *  `humanloop.followup-request/v1` event. */
+    consultHuman(event) {
+        return this.request('POST', routes.humanConsult(), event);
+    }
+    /** Run the registered visual handler server-side for one
+     *  `humanloop.visual-request-event/v1` event. */
+    visualHuman(event) {
+        return this.request('POST', routes.humanVisual(), event);
+    }
+    // ---- Humanloop inbox (Northlight crouter-inbox v1, inbox-contract.md §A) --
+    /** Pending deck/review tickets across every available crouter-owned
+     *  humanloop root. */
+    listHumanInbox() {
+        return this.request('GET', routes.humanInbox());
+    }
+    /** Read one pending deck by its opaque ticket id, with Markdown bodies
+     *  resolved inline. */
+    getHumanInboxDeck(ticketId) {
+        return this.request('GET', routes.humanInboxTicket(this.ticketId(ticketId)));
+    }
+    /** Submit ordered interaction responses for a pending deck. Single-assignment
+     *  server-side: a competing resolution races to `ticket_already_resolved`. */
+    respondHumanInboxDeck(ticketId, request) {
+        return this.request('POST', routes.humanInboxRespond(this.ticketId(ticketId)), request);
+    }
+    /** Cancel a pending deck (terminal response, never deletion). */
+    cancelHumanInboxTicket(ticketId, request) {
+        return this.request('POST', routes.humanInboxCancel(this.ticketId(ticketId)), request ?? {});
+    }
+    // ---- 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));
+    }
+    /** The machine-readable browser canvas roster (`crtr canvas snapshot`) —
+     *  distinct from the per-node `getSnapshot`. */
+    canvasSnapshot() {
+        return this.request('GET', routes.canvasSnapshot());
+    }
+    /** 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());
+    }
+    prune(req) {
+        return this.request('POST', routes.canvasPrune(), req);
+    }
+    rebuildIndex() {
+        return this.request('POST', routes.canvasRebuildIndex(), {});
+    }
+    // ---- Escape hatch ------------------------------------------------------
+    /** Raw request for routes not yet method-wrapped. Applies the same
+     *  autostart + error-mapping semantics. */
+    async request(method, path, body) {
+        let res;
+        try {
+            res = await this.transport(method, path, body);
+        }
+        catch (err) {
+            if (this.isColdSocketError(err)) {
+                await this.handleColdSocket();
+                res = await this.transport(method, path, body);
+            }
+            else if (this.isHandoverHangup(err)) {
+                res = await this.rideOutHandover(method, path, body);
+            }
+            else {
+                throw toTransportApiError(err);
+            }
+        }
+        return parse(res);
+    }
+    // ---- internals ---------------------------------------------------------
+    nodePath(id) {
+        if (!isSafeNodeId(id)) {
+            throw new ApiError(400, 'invalid_node_id', `invalid node 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 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;
+    }
+    transport(method, path, body) {
+        const usingHttps = this.baseUrl?.protocol === 'https:';
+        const doRequest = usingHttps ? httpsRequest : httpRequest;
+        const payload = body === undefined ? undefined : JSON.stringify(body);
+        const headers = { accept: 'application/json', ...this.headers };
+        if (payload !== undefined) {
+            headers['content-type'] = 'application/json';
+            headers['content-length'] = String(Buffer.byteLength(payload));
+        }
+        const options = {
+            method,
+            path,
+            headers,
+            timeout: this.timeoutMs,
+        };
+        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 new Promise((resolve, reject) => {
+            const req = doRequest(options, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    resolve({ status: res.statusCode ?? 0, text: Buffer.concat(chunks).toString('utf8') });
+                });
+                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();
+        });
+    }
+    isColdSocketError(err) {
+        if (this.socketPath === undefined)
+            return false;
+        const code = err?.code;
+        return code === 'ECONNREFUSED' || code === 'ENOENT';
+    }
+    /** A connection torn down MID-request (Node's "socket hang up" / a broken
+     *  pipe) — as distinct from a refused connect, which means nothing is
+     *  listening. On the local socket that is `crtr sys daemon restart` doing its
+     *  generation handover: the daemon acks, then tears itself down and hands
+     *  over to a successor it spawned. The daemon IS coming back. */
+    isHandoverHangup(err) {
+        if (this.socketPath === undefined)
+            return false;
+        const code = err?.code;
+        return code === 'ECONNRESET' || code === 'EPIPE';
+    }
+    /** Wait for the successor to answer `/healthz`, then replay the request when
+     *  replaying is safe. GET/HEAD are idempotent, so they retry transparently —
+     *  the handover stays invisible, which is the whole point of a restart that
+     *  resumes every node. A mutation may already have been applied server-side
+     *  before the socket dropped, so it fails with `daemon_restarting` (retry),
+     *  never `daemon_unavailable` ("start the daemon" is the wrong advice for a
+     *  daemon that is mid-handover). */
+    async rideOutHandover(method, path, body) {
+        if (!(await this.awaitHandover())) {
+            throw new ApiError(503, 'daemon_unavailable', `crtrd went away mid-request and did not come back within ${this.coldStartPollWindowMs}ms.`);
+        }
+        if (method !== 'GET' && method !== 'HEAD') {
+            throw new ApiError(503, 'daemon_restarting', `crtrd handed over to a new runtime generation mid-request; this ${method} may or may not have been applied.`);
+        }
+        try {
+            return await this.transport(method, path, body);
+        }
+        catch (err) {
+            throw toTransportApiError(err);
+        }
+    }
+    /** Poll `/healthz` until the successor daemon answers, bounded by the
+     *  cold-start window. Tolerates both the pre-listen gap (cold socket) and a
+     *  second hang-up from a server still tearing down. */
+    async awaitHandover() {
+        const deadline = Date.now() + this.coldStartPollWindowMs;
+        for (;;) {
+            try {
+                const res = await this.transport('GET', routes.healthz());
+                if (res.status >= 200 && res.status < 300)
+                    return true;
+            }
+            catch (err) {
+                if (!this.isColdSocketError(err) && !this.isHandoverHangup(err))
+                    throw toTransportApiError(err);
+            }
+            if (Date.now() >= deadline)
+                return false;
+            await sleep(HEALTHZ_POLL_INTERVAL_MS);
+        }
+    }
+    /** Trigger the injected daemon-start hook, poll `/healthz`, then let the caller
+     *  retry once. Fail loud with `daemon_unavailable` when autostart is off, no
+     *  hook is wired, or the daemon never becomes reachable. */
+    async handleColdSocket() {
+        if (!this.autostart || this.onColdSocket === undefined) {
+            throw new ApiError(503, 'daemon_unavailable', 'crtrd is not running and autostart is disabled; run `crtr sys daemon start`.');
+        }
+        if (this.coldStartAttempted) {
+            throw new ApiError(503, 'daemon_unavailable', 'crtrd did not become reachable after autostart.');
+        }
+        this.coldStartAttempted = true;
+        await this.onColdSocket();
+        const deadline = Date.now() + this.coldStartPollWindowMs;
+        for (;;) {
+            try {
+                const res = await this.transport('GET', routes.healthz());
+                if (res.status >= 200 && res.status < 300)
+                    return;
+            }
+            catch (err) {
+                if (!this.isColdSocketError(err))
+                    throw toTransportApiError(err);
+            }
+            if (Date.now() >= deadline) {
+                const diagnostic = safeColdStartDiagnostic(this.coldStartDiagnostic);
+                throw new ApiError(503, 'daemon_unavailable', coldStartTimeoutMessage(diagnostic));
+            }
+            await sleep(HEALTHZ_POLL_INTERVAL_MS);
+        }
+    }
+}
+/** 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 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) {
+    const ok = res.status >= 200 && res.status < 300;
+    const trimmed = res.text.trim();
+    let payload;
+    if (trimmed !== '') {
+        try {
+            payload = JSON.parse(trimmed);
+        }
+        catch {
+            if (ok)
+                return undefined;
+            throw new ApiError(res.status, 'invalid_response', res.text.slice(0, 500));
+        }
+    }
+    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, 'internal', `request failed with status ${res.status}`);
+}
+/** 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) {
+    if (err instanceof ApiError)
+        return err;
+    const code = err?.code;
+    const message = err instanceof Error ? err.message : String(err);
+    if (code === 'ECONNREFUSED' || code === 'ENOENT') {
+        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);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Compose the cold-start `/healthz`-timeout `daemon_unavailable` message,
+ *  appending the injected diagnostic (issue #516) when one is present instead
+ *  of discarding the real startup failure behind a bare message. Exported (not
+ *  from the package's public `index.ts` surface, which is dependency-light by
+ *  design) purely so the regression test can assert the composition without
+ *  waiting out the real poll window. */
+export function coldStartTimeoutMessage(diagnostic) {
+    const base = 'crtrd did not start; run `crtr sys daemon start` and check crtrd.err.';
+    return diagnostic !== undefined && diagnostic !== '' ? `${base}\n${diagnostic}` : base;
+}
+/** Invoke the injected `coldStartDiagnostic` hook, treating a THROW the same
+ *  as an absent/undefined result — the contract `CrtrClientOptions` documents
+ *  ("a thrown/undefined result is treated as 'no diagnostic'"). Without this,
+ *  a broken hook would propagate and replace the typed `daemon_unavailable`
+ *  error the caller is entitled to. Exported alongside `coldStartTimeoutMessage`
+ *  for the same direct-unit-test reason. */
+export function safeColdStartDiagnostic(hook) {
+    if (hook === undefined)
+        return undefined;
+    try {
+        return hook();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/dto/attach.d.ts

@@ -0,0 +1,16 @@
+import type { NodeIdDTO } from './common.js';
+/** `POST /v1/nodes/{id}/attach` body (local ensure). */
+export interface AttachEnsureRequest {
+    /** Resume saved history on revive (default true). */
+    resume?: boolean;
+    /** Revive if dormant (default true); false returns a possibly-dead socket. */
+    revive?: boolean;
+}
+/** Result of a local attach-ensure. */
+export interface AttachEnsureResultDTO {
+    node_id: NodeIdDTO;
+    /** Host-local path to the node's broker `view.sock`. */
+    socket_path: string;
+    revived: boolean;
+    resumed: boolean;
+}

package/dist/dto/attach.js

@@ -0,0 +1,13 @@
+// Attach DTOs (spec §5). Two shapes, one concept:
+//
+//  - `POST /v1/nodes/{id}/attach` (LOCAL) — crtrd revives (unless opted out) and
+//    returns `socket_path`; the local viewer then connects to `view.sock`
+//    directly with the existing `ViewSocketClient`. Meaningful only over the
+//    unix socket (the path is host-local). This is `ensureAttach()` on the client.
+//
+//  - `GET /v1/nodes/{id}/attach` with `Upgrade: websocket` (REMOTE) — crtrd
+//    bridges the WS ⇄ the node's `view.sock` byte-for-byte, one WS per node.
+//    Opened DIRECTLY against the URL, NOT via a `CrtrClient` method. Opt out of
+//    the implicit revive with `?revive=0` or header `X-Crtr-Attach-Revive: 0`;
+//    a dormant node with revive opted out refuses the upgrade with 409.
+export {};