@north-light/crouter-api 0.3.232 → 0.3.234

package/dist/api/client.js

@@ -9,6 +9,7 @@
 //
 // TRANSPORT (spec O-1): `node:http`/`node:https` `request()` — NO `undici`.
 // unix socket via `{ socketPath }`; TCP/remote via a parsed `baseUrl`.
+import { envHomeOverride } from '../shared/env.js';
 import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { homedir } from 'node:os';
@@ -27,7 +28,7 @@ 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 override = envHomeOverride();
     const home = override !== undefined && override !== ''
         ? override
         : join(homedir(), CRTR_DIR_NAME, 'canvas');
@@ -74,7 +75,7 @@ export class CrtrClient {
     static forLocalSocket(opts) {
         return new CrtrClient({ socketPath: defaultSocketPath(), autostart: true, ...opts });
     }
-    // ---- Health / status ---------------------------------------------------
+    // Health / status
     healthz() {
         return this.request('GET', routes.healthz());
     }
@@ -88,7 +89,7 @@ export class CrtrClient {
     restartDaemon() {
         return this.request('POST', routes.daemonRestart());
     }
-    // ---- Nodes -------------------------------------------------------------
+    // Nodes
     createNode(req) {
         return this.request('POST', routes.nodes(), req);
     }
@@ -178,7 +179,7 @@ export class CrtrClient {
     subscribe(id, req) {
         return this.request('POST', routes.nodeSubscriptions(this.nodePath(id)), req);
     }
-    // ---- Focuses (viewer registry) ----------------------------------------
+    // 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
@@ -245,7 +246,7 @@ export class CrtrClient {
     ensureAttach(id, req) {
         return this.request('POST', routes.nodeAttach(this.nodePath(id)), req ?? {});
     }
-    // ---- Reads / feed ------------------------------------------------------
+    // Reads / feed
     getReports(id, q) {
         return this.request('GET', withQuery(routes.nodeReports(this.nodePath(id)), q));
     }
@@ -283,20 +284,20 @@ export class CrtrClient {
     getContext(id) {
         return this.request('GET', routes.nodeContext(this.nodePath(id)));
     }
-    // ---- Host file read ----------------------------------------------------
+    // 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 }));
     }
-    // ---- Memory documents --------------------------------------------------
+    // Memory documents
     /** Resolve an exact canonical `[[name]]` memory-document link to the winning
      *  document's physical origin for the given node — the node's own precedence
      *  chain, not this process's. Pair with `peekFile` to render the document. */
     resolveMemoryDoc(name, nodeId) {
         return this.request('GET', withQuery(routes.memoryResolve(), { name, node: nodeId }));
     }
-    // ---- Profiles ----------------------------------------------------------
+    // 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. */
@@ -317,7 +318,7 @@ export class CrtrClient {
     deleteProfile(name, req) {
         return this.request('DELETE', routes.profile(name), req);
     }
-    // ---- Model auth --------------------------------------------------------
+    // Model auth
     listModelAuth() {
         return this.request('GET', routes.modelAuths());
     }
@@ -327,7 +328,7 @@ export class CrtrClient {
     removeCredential(provider) {
         return this.request('DELETE', routes.modelAuth(provider));
     }
-    // ---- Human bridge + completion-handler forwarding (spec §6.5) ----------
+    // 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. */
@@ -344,7 +345,7 @@ export class CrtrClient {
     cancelHumanTicket(ticketId, body) {
         return this.request('POST', routes.humanTicketCancel(this.interactionPath(ticketId)), body);
     }
-    // ---- Daemon-owned document reviews and comments -----------------------
+    // Daemon-owned document reviews and comments
     createReview(req) {
         return this.request('POST', routes.humanReviews(), req);
     }
@@ -433,7 +434,7 @@ export class CrtrClient {
     cancelHumanInboxTicket(ticketId, request) {
         return this.request('POST', routes.humanInboxCancel(this.ticketId(ticketId)), request ?? {});
     }
-    // ---- Durable programmatic human requests -------------------------------
+    // Durable programmatic human requests
     /** Create one durable human request. Its `request_id` is the same opaque id
      *  the inbox routes address, so the request and the inbox ticket are one
      *  record. An unresolvable `action.name` is rejected before the page is
@@ -474,7 +475,7 @@ export class CrtrClient {
         }
         return this.request('POST', routes.humanInboxFeedbackResolve(this.ticketId(ticketId), commentId), { node_id: nodeId });
     }
-    // ---- Canvas reads / maintenance ---------------------------------------
+    // 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. */
@@ -527,7 +528,7 @@ export class CrtrClient {
     rebuildIndex() {
         return this.request('POST', routes.canvasRebuildIndex(), {});
     }
-    // ---- Escape hatch ------------------------------------------------------
+    // Escape hatch
     /** Raw request for routes not yet method-wrapped. Applies the same
      *  autostart + error-mapping semantics. */
     async request(method, path, body) {
@@ -549,7 +550,7 @@ export class CrtrClient {
             throw toTransportApiError(err);
         }
     }
-    // ---- internals ---------------------------------------------------------
+    // internals
     nodePath(id) {
         if (!isSafeNodeId(id)) {
             throw new ApiError(400, 'invalid_node_id', `invalid node id: ${JSON.stringify(id)}`);

package/dist/shared/env.d.ts

@@ -0,0 +1,68 @@
+/** The current node's id (`CRTR_NODE_ID`), or undefined outside a node. */
+export declare function envNodeId(): string | undefined;
+/** The current node's target profile id (`CRTR_PROFILE_ID`), or undefined. */
+export declare function envProfileId(): string | undefined;
+/** The current node's working directory (`CRTR_NODE_CWD`), or undefined. */
+export declare function envNodeCwd(): string | undefined;
+/** An explicit model-routing override for this turn (`CRTR_MODEL_INTENT`), or
+ *  undefined. Cleared (not read) via `delete process.env['CRTR_MODEL_INTENT']`
+ *  in `runtime/broker.ts` — a mutation, not a read, so it stays there. */
+export declare function envModelIntent(): string | undefined;
+/** The raw `CRTR_HOME` override, unresolved. Use `crtrHome()`
+ *  (`core/canvas/paths.ts`) to get the resolved canvas-home path; use this
+ *  only when a caller needs the override itself — to check whether one is
+ *  set, or to propagate it verbatim into a child process's env. */
+export declare function envHomeOverride(): string | undefined;
+/** Dead-provider watchdog timeout (`CRTR_STREAM_WATCHDOG_MS`), 5 minutes by
+ *  default. See `runtime/stream-watchdog.ts` for what it guards. */
+export declare function envStreamWatchdogMs(): number;
+/** The canvas inbox watcher's poll tick (`CRTR_WATCHER_TICK_MS`). */
+export declare function envWatcherTickMs(): number;
+/** The canvas inbox watcher's debounce window (`CRTR_WATCHER_DEBOUNCE_MS`). */
+export declare function envWatcherDebounceMs(): number;
+/** No-new-message window before a recap is shown (`CRTR_RECAP_IDLE_MS`), 60s
+ *  by default. */
+export declare function envRecapIdleMs(): number;
+/** Explicit recap-model override (`CRTR_RECAP_MODEL`), trimmed; undefined if
+ *  unset or blank. */
+export declare function envRecapModelOverride(): string | undefined;
+/** The bash safety-valve deadline (`CRTR_BASH_VALVE_MS`), 5 minutes by
+ *  default; undocumented test-only override so the E2E valve check doesn't
+ *  sleep 5 minutes. */
+export declare function envBashValveMs(): number;
+/** Explicit pidfile path override (`CRTR_PIDFILE`, tests only); undefined if
+ *  unset or blank. */
+export declare function envPidfileOverride(): string | undefined;
+/** The broker engine module spec (`CRTR_BROKER_ENGINE`, the T11 test seam),
+ *  defaulting to the real SDK. `runtime/host.ts` layers `inv.env` ahead of
+ *  this (a launch-time override mirrored into the child's env, since
+ *  spawn-env.ts's default-deny allowlist strips `CRTR_*` from ambient env). */
+export declare function envBrokerEngine(): string;
+/** Test-only pi-binary substitution (`CRTR_PI_BINARY`) so the integration
+ *  harness can point a real `crtr node new` at a deterministic fake-pi
+ *  vehicle. Undefined in production. */
+export declare function envPiBinaryOverride(): string | undefined;
+/** Whether implicit daemon autostart is suppressed for this invocation
+ *  (`CRTR_NO_DAEMON_AUTOSTART=1`). */
+export declare function envNoDaemonAutostart(): boolean;
+/** The `--tcp` fallback for crtrd's opt-in TCP listener (`CRTRD_TCP`), raw
+ *  (`host:port` or undefined — absent means unix socket only). */
+export declare function envCrtrdTcp(): string | undefined;
+/** Kill switch for the host-exports writer/pruner (`CRTR_NO_EXPORTS=1`). */
+export declare function envNoExports(): boolean;
+/** Verbose-diagnostics gate for otherwise-silent best-effort catches
+ *  (`CRTR_DEBUG=1`). Distinct from `CRTR_DEBUG_PID_LIVENESS`
+ *  (`core/canvas/pid.ts`), a different, unrelated var. */
+export declare function envDebug(): boolean;
+/** Live-broker automatic-revive cap override (`CRTR_MAX_LIVE_BROKERS`); wins
+ *  over `readConfig('user').brokerThresholds.automaticReviveCap` when set. */
+export declare function envMaxLiveBrokers(): number | undefined;
+/** Live-broker warning threshold override (`CRTR_WARN_LIVE_BROKERS`); wins
+ *  over `readConfig('user').brokerThresholds.warning` when set. */
+export declare function envWarnLiveBrokers(): number | undefined;
+/** Test-only unattended-park interval override (`CRTR_TEST_UNATTENDED_PARK_MS`),
+ *  gated by `envNoDaemonAutostart()` at the call site; no production default. */
+export declare function envTestUnattendedParkMs(): number | undefined;
+/** Test-only park-summary grace-period override
+ *  (`CRTR_TEST_PARK_SUMMARY_GRACE_MS`); no production default. */
+export declare function envTestParkSummaryGraceMs(): number | undefined;

package/dist/shared/env.js

@@ -0,0 +1,171 @@
+// The reader-side surface for every environment variable crouter reads back
+// out of `process.env`, outside `core/runtime/spawn-env.ts`'s writer
+// allowlist. That module documents what a broker child is ADMITTED to see;
+// this one documents what crouter itself reads. Two families:
+//
+//   - Identity: raw passthrough (`string | undefined`, exactly what
+//     `process.env[name]` returns). Every existing call site keeps its own
+//     established fallback (`?? ''`, `|| null`, `?? cfg.cwd`, a presence
+//     check, ...) — the fallback has always been call-site-owned, not
+//     var-owned, so centralizing it here would be a behavior change, not a
+//     dedup. `CRTR_HOME` also has a resolved-path accessor, `crtrHome()` in
+//     `core/canvas/paths.ts`; that stays the canonical way to get the
+//     resolved canvas home; `envHomeOverride()` here is for the handful of
+//     sites that want the raw override value itself (to check presence or
+//     propagate it verbatim to a child env).
+//
+//   - Tuning: parsed, with the default baked into the accessor. Each of
+//     these had exactly one parse site before this module existed; the
+//     parse logic moved here unchanged so a second site, if one appears,
+//     reads the single implementation instead of re-deriving it.
+//
+// `CRTR_DIR_NAME` is NOT here — it is a plain exported string constant
+// (`types.ts`), never read off `process.env`.
+// Identity
+/** The current node's id (`CRTR_NODE_ID`), or undefined outside a node. */
+export function envNodeId() {
+    return process.env['CRTR_NODE_ID'];
+}
+/** The current node's target profile id (`CRTR_PROFILE_ID`), or undefined. */
+export function envProfileId() {
+    return process.env['CRTR_PROFILE_ID'];
+}
+/** The current node's working directory (`CRTR_NODE_CWD`), or undefined. */
+export function envNodeCwd() {
+    return process.env['CRTR_NODE_CWD'];
+}
+/** An explicit model-routing override for this turn (`CRTR_MODEL_INTENT`), or
+ *  undefined. Cleared (not read) via `delete process.env['CRTR_MODEL_INTENT']`
+ *  in `runtime/broker.ts` — a mutation, not a read, so it stays there. */
+export function envModelIntent() {
+    return process.env['CRTR_MODEL_INTENT'];
+}
+/** The raw `CRTR_HOME` override, unresolved. Use `crtrHome()`
+ *  (`core/canvas/paths.ts`) to get the resolved canvas-home path; use this
+ *  only when a caller needs the override itself — to check whether one is
+ *  set, or to propagate it verbatim into a child process's env. */
+export function envHomeOverride() {
+    return process.env['CRTR_HOME'];
+}
+// Tuning
+/** Generic `Number(raw)` parse with a positive-finite guard, shared by every
+ *  millisecond tuning var below (each previously reimplemented this locally,
+ *  identically). */
+function parsePositiveMs(raw, fallback) {
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+const DEFAULT_STREAM_WATCHDOG_MS = 5 * 60_000; // 5 minutes.
+/** Dead-provider watchdog timeout (`CRTR_STREAM_WATCHDOG_MS`), 5 minutes by
+ *  default. See `runtime/stream-watchdog.ts` for what it guards. */
+export function envStreamWatchdogMs() {
+    return parsePositiveMs(process.env['CRTR_STREAM_WATCHDOG_MS'], DEFAULT_STREAM_WATCHDOG_MS);
+}
+const DEFAULT_WATCHER_TICK_MS = 800;
+/** The canvas inbox watcher's poll tick (`CRTR_WATCHER_TICK_MS`). */
+export function envWatcherTickMs() {
+    return parsePositiveMs(process.env['CRTR_WATCHER_TICK_MS'], DEFAULT_WATCHER_TICK_MS);
+}
+const DEFAULT_WATCHER_DEBOUNCE_MS = 1000;
+/** The canvas inbox watcher's debounce window (`CRTR_WATCHER_DEBOUNCE_MS`). */
+export function envWatcherDebounceMs() {
+    return parsePositiveMs(process.env['CRTR_WATCHER_DEBOUNCE_MS'], DEFAULT_WATCHER_DEBOUNCE_MS);
+}
+const DEFAULT_RECAP_IDLE_MS = 60_000;
+/** No-new-message window before a recap is shown (`CRTR_RECAP_IDLE_MS`), 60s
+ *  by default. */
+export function envRecapIdleMs() {
+    return parsePositiveMs(process.env['CRTR_RECAP_IDLE_MS'], DEFAULT_RECAP_IDLE_MS);
+}
+/** Explicit recap-model override (`CRTR_RECAP_MODEL`), trimmed; undefined if
+ *  unset or blank. */
+export function envRecapModelOverride() {
+    const raw = process.env['CRTR_RECAP_MODEL'];
+    return raw !== undefined && raw.trim() !== '' ? raw.trim() : undefined;
+}
+const DEFAULT_BASH_VALVE_MS = 5 * 60 * 1000;
+/** The bash safety-valve deadline (`CRTR_BASH_VALVE_MS`), 5 minutes by
+ *  default; undocumented test-only override so the E2E valve check doesn't
+ *  sleep 5 minutes. */
+export function envBashValveMs() {
+    return parsePositiveMs(process.env['CRTR_BASH_VALVE_MS'], DEFAULT_BASH_VALVE_MS);
+}
+/** Explicit pidfile path override (`CRTR_PIDFILE`, tests only); undefined if
+ *  unset or blank. */
+export function envPidfileOverride() {
+    const raw = process.env['CRTR_PIDFILE'];
+    return raw !== undefined && raw !== '' ? raw : undefined;
+}
+const DEFAULT_BROKER_ENGINE = '@earendil-works/pi-coding-agent';
+/** The broker engine module spec (`CRTR_BROKER_ENGINE`, the T11 test seam),
+ *  defaulting to the real SDK. `runtime/host.ts` layers `inv.env` ahead of
+ *  this (a launch-time override mirrored into the child's env, since
+ *  spawn-env.ts's default-deny allowlist strips `CRTR_*` from ambient env). */
+export function envBrokerEngine() {
+    return process.env['CRTR_BROKER_ENGINE'] ?? DEFAULT_BROKER_ENGINE;
+}
+/** Test-only pi-binary substitution (`CRTR_PI_BINARY`) so the integration
+ *  harness can point a real `crtr node new` at a deterministic fake-pi
+ *  vehicle. Undefined in production. */
+export function envPiBinaryOverride() {
+    return process.env['CRTR_PI_BINARY'];
+}
+/** Whether implicit daemon autostart is suppressed for this invocation
+ *  (`CRTR_NO_DAEMON_AUTOSTART=1`). */
+export function envNoDaemonAutostart() {
+    return process.env['CRTR_NO_DAEMON_AUTOSTART'] === '1';
+}
+/** The `--tcp` fallback for crtrd's opt-in TCP listener (`CRTRD_TCP`), raw
+ *  (`host:port` or undefined — absent means unix socket only). */
+export function envCrtrdTcp() {
+    return process.env['CRTRD_TCP'];
+}
+/** Kill switch for the host-exports writer/pruner (`CRTR_NO_EXPORTS=1`). */
+export function envNoExports() {
+    return process.env['CRTR_NO_EXPORTS'] === '1';
+}
+/** Verbose-diagnostics gate for otherwise-silent best-effort catches
+ *  (`CRTR_DEBUG=1`). Distinct from `CRTR_DEBUG_PID_LIVENESS`
+ *  (`core/canvas/pid.ts`), a different, unrelated var. */
+export function envDebug() {
+    return process.env['CRTR_DEBUG'] === '1';
+}
+// Precedence — broker-supervision.ts's threshold/interval overrides. Each
+// returns the raw parsed value with NO default: the caller (config for the
+// thresholds, a hardcoded production constant for the intervals) supplies
+// the default, and env wins over it when set. Undefined, unparseable, or
+// non-positive all mean "no override" — the caller's own default applies.
+function parsePositiveInteger(raw) {
+    if (raw === undefined || raw === '')
+        return undefined;
+    const n = Number(raw);
+    return Number.isSafeInteger(n) && n >= 1 ? n : undefined;
+}
+/** Live-broker automatic-revive cap override (`CRTR_MAX_LIVE_BROKERS`); wins
+ *  over `readConfig('user').brokerThresholds.automaticReviveCap` when set. */
+export function envMaxLiveBrokers() {
+    return parsePositiveInteger(process.env['CRTR_MAX_LIVE_BROKERS']);
+}
+/** Live-broker warning threshold override (`CRTR_WARN_LIVE_BROKERS`); wins
+ *  over `readConfig('user').brokerThresholds.warning` when set. */
+export function envWarnLiveBrokers() {
+    return parsePositiveInteger(process.env['CRTR_WARN_LIVE_BROKERS']);
+}
+function parsePositiveMsNoDefault(raw) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+/** Test-only unattended-park interval override (`CRTR_TEST_UNATTENDED_PARK_MS`),
+ *  gated by `envNoDaemonAutostart()` at the call site; no production default. */
+export function envTestUnattendedParkMs() {
+    return parsePositiveMsNoDefault(process.env['CRTR_TEST_UNATTENDED_PARK_MS']);
+}
+/** Test-only park-summary grace-period override
+ *  (`CRTR_TEST_PARK_SUMMARY_GRACE_MS`); no production default. */
+export function envTestParkSummaryGraceMs() {
+    return parsePositiveMsNoDefault(process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS']);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter-api",
-  "version": "0.3.232",
+  "version": "0.3.234",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, and the CrtrClient. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",