@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/hearth/control-plane/types.d.ts

@@ -0,0 +1,66 @@
+import type { GuestNodeId, MachineId, TenantId } from '../../core/hearth/types.js';
+export type HearthProvider = 'blaxel';
+export type HomeId = string;
+export type UserId = string;
+export type ProviderSandboxId = MachineId;
+export type ProviderVolumeId = string;
+export type PreviewEndpoint = string;
+export type RelayAuthRef = string;
+export type HomeStatus = 'provisioning' | 'running' | 'suspended' | 'restoring' | 'terminating' | 'terminated' | 'unknown';
+export type HomeHealthVerdict = 'healthy' | 'degraded' | 'unknown';
+export interface Home {
+    home_id: HomeId;
+    tenant_id: TenantId;
+    user_id: UserId;
+    provider: HearthProvider;
+    provider_sandbox_id: ProviderSandboxId | null;
+    provider_volume_id: ProviderVolumeId | null;
+    preview_endpoint: PreviewEndpoint | null;
+    home_agent_target: GuestNodeId | null;
+    relay_auth_ref: RelayAuthRef | null;
+    status: HomeStatus;
+    template_version: string | null;
+    last_ready_at: string | null;
+    last_wake_at: string | null;
+    last_suspend_at: string | null;
+    last_wake_latency_ms: number | null;
+    health_verdict: HomeHealthVerdict;
+    created_at: string;
+    updated_at: string;
+}
+export type ResolvedHome = Home;
+export interface CreateHomeInput {
+    home_id: HomeId;
+    tenant_id: TenantId;
+    user_id: UserId;
+    provider?: HearthProvider;
+    provider_sandbox_id?: ProviderSandboxId | null;
+    provider_volume_id?: ProviderVolumeId | null;
+    preview_endpoint?: PreviewEndpoint | null;
+    home_agent_target?: GuestNodeId | null;
+    relay_auth_ref?: RelayAuthRef | null;
+    status?: HomeStatus;
+    template_version?: string | null;
+    last_ready_at?: string | null;
+    last_wake_at?: string | null;
+    last_suspend_at?: string | null;
+    last_wake_latency_ms?: number | null;
+    health_verdict?: HomeHealthVerdict;
+    created_at?: string;
+    updated_at?: string;
+}
+export interface RefreshProviderPointersInput {
+    provider_sandbox_id: ProviderSandboxId | null;
+    preview_endpoint: PreviewEndpoint | null;
+    status?: HomeStatus;
+    template_version?: string | null;
+}
+export interface TouchWakeInput {
+    at?: string;
+    latency_ms?: number | null;
+}
+export type HomePatch = Partial<Pick<Home, 'provider_sandbox_id' | 'provider_volume_id' | 'preview_endpoint' | 'relay_auth_ref' | 'status' | 'template_version' | 'last_ready_at' | 'last_wake_at' | 'last_suspend_at' | 'last_wake_latency_ms' | 'health_verdict'>>;
+export interface TenantSession {
+    tenant_id: TenantId;
+    user_id: UserId;
+}

package/dist/hearth/control-plane/types.js

@@ -0,0 +1 @@
+export {};

package/dist/hearth/control-plane/wake.d.ts

@@ -0,0 +1,80 @@
+import { type HomeBackend } from '../../core/hearth/provider.js';
+import type { M0Config } from '../../core/hearth/types.js';
+import { type ControlPlaneConfig } from './config.js';
+import { getHomeById, refreshProviderPointers, setHomeStatus, touchReady, touchWake } from './registry.js';
+import { resolveSecret } from './secrets.js';
+import type { HomeId, HomeStatus } from './types.js';
+export interface WakeResult {
+    preview_endpoint: string;
+    relayToken: string;
+}
+/** Normalize a provider-observed runtime status into the CP `HomeStatus`
+ *  vocabulary before it is ever persisted (Q3 / P3.4 review Minor finding):
+ *  the provider's `MachineState` is broad (and may include future
+ *  pause/suspend/standby spellings the SDK doesn't expose yet); CP's
+ *  `HomeStatus` enum does not have a `'paused'` member. Anything
+ *  pause/suspend/standby-shaped collapses to `'suspended'`; an exact
+ *  `'running'` passes through; everything else (provisioning, terminating,
+ *  terminated, restoring, unrecognized) becomes `'unknown'` rather than
+ *  guessing a more specific CP status from a provider-specific string. */
+export declare function normalizeProviderStatus(providerStatus: string | null | undefined): HomeStatus;
+/** One bounded attempt: open a WebSocket to `/node/<target>` carrying the
+ *  relay token and require the upgrade to both succeed AND survive a short
+ *  settle window (or yield a first frame) within `attemptTimeoutMs` — proof
+ *  the in-guest web server answered AND relayed to a live broker `view.sock`
+ *  (R-WAKE-2), not just that the SPA shell route is up. Every branch
+ *  (success, handshake rejection, error, premature close, attempt timeout)
+ *  closes the socket and resolves exactly once — a success closes gracefully
+ *  (code 1000) so the guest relay does not record a false fault, anything
+ *  else terminates it. */
+declare function probeNodeOnce(previewEndpoint: string, target: string, relayToken: string, attemptTimeoutMs: number): Promise<boolean>;
+/** Retry the single-shot probe until it confirms `/node/<target>` is serving
+ *  or `windowMs` elapses. Always runs at least one attempt (R-WAKE-1: "a
+ *  single failed probe does not abort"). Every timer this loop starts
+ *  (the per-attempt abort timeout, the inter-attempt backoff) is cleared/
+ *  resolved before the loop returns — nothing is left armed. */
+declare function probeNodeReady(previewEndpoint: string, target: string, relayToken: string, windowMs: number): Promise<boolean>;
+/** Indirection seam so a smoke/test script can swap any step (the provider
+ *  backend, the registry setters, the secret resolver, the probe itself, the
+ *  clock) without touching a real DB/provider/filesystem. Production code
+ *  never reassigns these; only ad hoc verification scripts do. */
+export declare const wakeInternals: {
+    getHomeById: typeof getHomeById;
+    refreshProviderPointers: typeof refreshProviderPointers;
+    setHomeStatus: typeof setHomeStatus;
+    touchWake: typeof touchWake;
+    touchReady: typeof touchReady;
+    resolveSecret: typeof resolveSecret;
+    getHomeBackend: (config: M0Config) => HomeBackend;
+    loadM0Config: () => M0Config;
+    loadControlPlaneConfig: () => ControlPlaneConfig;
+    probeNodeOnce: typeof probeNodeOnce;
+    probeNodeReady: typeof probeNodeReady;
+    now: () => number;
+};
+/** Cheap, non-probing fast path: return a still-fresh warm-verdict cache hit
+ *  for `home_id`, or `null` if there is none (expired or never confirmed).
+ *  Never reads the registry and never calls the provider — callers fall back
+ *  to `ensureAwake` on a `null` (Q1: "no call to provider"). */
+export declare function resolveRunning(home_id: HomeId): WakeResult | null;
+/** Drop the cached warm verdict for a home (e.g. an upstream relay forward
+ *  failed) so the next `ensureAwake`/`resolveRunning` re-checks instead of
+ *  trusting a stale "ready" answer. */
+export declare function invalidateWarmVerdict(home_id: HomeId): void;
+/** Clear all warm verdicts and in-flight wake coalescing. Test/smoke-script
+ *  hygiene only — production never needs this (one CP process, S2). */
+export declare function resetWakeCacheForTests(): void;
+/** Bring a home up and ready, returning the route to relay to once it is.
+ *  Reads the registry, resolves the relay token, calls the provider
+ *  wake/resume seam, ready-probes `/node/<home_agent_target>`, refreshes
+ *  provider pointers on a recreate, records wake/ready timing, and returns
+ *  `{ preview_endpoint, relayToken }`. Throws on a ready-probe timeout
+ *  (wake-failure UX is deferred — gap note 2 — a throw is the accepted
+ *  cutover behavior).
+ *
+ *  A fresh warm-verdict cache hit short-circuits without re-entering this
+ *  pipeline at all. Otherwise concurrent callers for the SAME `home_id`
+ *  coalesce onto one in-flight wake (Q1) instead of each driving their own
+ *  provider call. */
+export declare function ensureAwake(home_id: HomeId): Promise<WakeResult>;
+export {};

package/dist/hearth/control-plane/wake.js

@@ -0,0 +1,312 @@
+// control-plane/wake.ts — CP wake orchestration (P4.2 / part-plan T3.1).
+//
+// Generalizes M0 `wake-proxy/home.ts` (`ensureAwake`/`resolveRunningHome`/
+// `probeRelayServing`) onto the CP `home` registry, with one deliberate
+// behavior drop: NO idle-pause machinery (S3 — the provider owns
+// idle->suspend; M0's `scheduleIdlePause`/`pauseNow` timer chain is not
+// reproduced here, by design, not oversight).
+//
+// Pipeline (R-WAKE-1): read the `home` row -> resolve the relay token handle
+// -> call the provider wake/resume seam (`HomeBackend.wake`, owned by the
+// home/provider slice, IP-1) -> ready-probe the in-guest web server on
+// `/node/<home_agent_target>` over a short retried window, carrying the
+// relay token -> if the provider returned a new sandbox/preview (a
+// recreate), persist the refreshed pointers; `home_agent_target` is NEVER
+// part of that patch (R-WAKE-6 — `refreshProviderPointers` doesn't accept it)
+// -> record wake/ready timing -> return the route. Readiness here means the
+// guest web server answers `/node/<target>` AND relays to a live broker
+// `view.sock` (R-WAKE-2 — not "the SPA shell renders"). `src/clients/web/
+// server.ts` only proves that second half on a WS upgrade: `bridgeConnection`
+// opens `view.sock` AFTER the 101 response and closes the socket with 1011
+// the instant that fails (ECONNREFUSED/ENOENT — "no running broker"), so an
+// HTTP GET 200 on `/node/<target>` (the SPA static/fallback route) proves
+// only that the guest web server is up, not that the broker is. The probe
+// therefore opens a real WebSocket to `/node/<target>` and requires a
+// successful upgrade that SURVIVES a short settle window (or yields a first
+// frame) before declaring readiness.
+//
+// All timers used during a probe retry window are cleared before the
+// function that started them returns — there is no `setTimeout`/`setInterval`
+// left armed once `ensureAwake`/`resolveRunning` resolve (S3 regression bar).
+import { setTimeout as delay } from 'node:timers/promises';
+import { WebSocket } from 'ws';
+import { general } from '../../core/errors.js';
+import { loadM0Config } from '../../core/hearth/config.js';
+import { getHomeBackend } from '../../core/hearth/provider.js';
+import { loadControlPlaneConfig } from './config.js';
+import { getHomeById, refreshProviderPointers, setHomeStatus, touchReady, touchWake } from './registry.js';
+import { resolveSecret } from './secrets.js';
+// Individual probe attempt timeout — bounded short so a dead route fails
+// fast and the retry loop gets multiple attempts inside the overall window,
+// rather than one attempt eating the whole window (mirrors M0's
+// `READY_PROBE_TIMEOUT_MS`).
+const READY_PROBE_ATTEMPT_TIMEOUT_MS = 1_500;
+// Backoff between probe attempts (Q1: "500ms backoff between attempts").
+const READY_PROBE_BACKOFF_MS = 500;
+// How long a confirmed-ready verdict is trusted before `resolveRunning`/
+// `ensureAwake` re-checks instead of trusting a stale answer (Q1: "10s TTL,
+// in-process"). Single CP process, no distributed cache (S2).
+const WARM_VERDICT_TTL_MS = 10_000;
+/** Normalize a provider-observed runtime status into the CP `HomeStatus`
+ *  vocabulary before it is ever persisted (Q3 / P3.4 review Minor finding):
+ *  the provider's `MachineState` is broad (and may include future
+ *  pause/suspend/standby spellings the SDK doesn't expose yet); CP's
+ *  `HomeStatus` enum does not have a `'paused'` member. Anything
+ *  pause/suspend/standby-shaped collapses to `'suspended'`; an exact
+ *  `'running'` passes through; everything else (provisioning, terminating,
+ *  terminated, restoring, unrecognized) becomes `'unknown'` rather than
+ *  guessing a more specific CP status from a provider-specific string. */
+export function normalizeProviderStatus(providerStatus) {
+    if (providerStatus === null || providerStatus === undefined)
+        return 'unknown';
+    const normalized = providerStatus.trim().toLowerCase();
+    if (normalized === 'paused' || normalized === 'suspended' || normalized === 'standby')
+        return 'suspended';
+    if (normalized === 'running')
+        return 'running';
+    return 'unknown';
+}
+function requireHomeField(value, field, home_id) {
+    if (value === null || value === undefined || (typeof value === 'string' && value.trim() === '')) {
+        throw general(`home ${home_id} is missing ${field} — cannot wake`, { home_id, field });
+    }
+    return value;
+}
+function buildDescriptor(home, relayToken) {
+    return {
+        homeId: home.home_id,
+        tenantId: home.tenant_id,
+        userId: home.user_id,
+        providerName: home.provider,
+        providerSandboxId: requireHomeField(home.provider_sandbox_id, 'provider_sandbox_id', home.home_id),
+        providerVolumeId: requireHomeField(home.provider_volume_id, 'provider_volume_id', home.home_id),
+        previewEndpoint: home.preview_endpoint,
+        homeAgentTarget: requireHomeField(home.home_agent_target, 'home_agent_target', home.home_id),
+        relayAuthRef: home.relay_auth_ref,
+        relayToken,
+        status: home.status,
+        templateVersion: home.template_version,
+    };
+}
+// After a successful 101 upgrade, `bridgeConnection` (server.ts) still has to
+// dial the broker's `view.sock` and can close the socket (1011, "no running
+// broker") the instant that dial fails. That happens fast on a local unix
+// socket (ECONNREFUSED/ENOENT are immediate), so a settle window this short
+// is enough to let a dead-broker close win the race against a false-positive
+// `open` before the probe declares readiness.
+const READY_PROBE_WS_SETTLE_MS = 300;
+function wsUrlForNode(previewEndpoint, target) {
+    const url = new URL(`/node/${encodeURIComponent(target)}`, previewEndpoint);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    return url;
+}
+/** One bounded attempt: open a WebSocket to `/node/<target>` carrying the
+ *  relay token and require the upgrade to both succeed AND survive a short
+ *  settle window (or yield a first frame) within `attemptTimeoutMs` — proof
+ *  the in-guest web server answered AND relayed to a live broker `view.sock`
+ *  (R-WAKE-2), not just that the SPA shell route is up. Every branch
+ *  (success, handshake rejection, error, premature close, attempt timeout)
+ *  closes the socket and resolves exactly once — a success closes gracefully
+ *  (code 1000) so the guest relay does not record a false fault, anything
+ *  else terminates it. */
+async function probeNodeOnce(previewEndpoint, target, relayToken, attemptTimeoutMs) {
+    return new Promise((resolveProbe) => {
+        let settled = false;
+        let settleTimer = null;
+        let ws;
+        try {
+            ws = new WebSocket(wsUrlForNode(previewEndpoint, target), {
+                headers: { authorization: `Bearer ${relayToken}` },
+                perMessageDeflate: false,
+            });
+        }
+        catch {
+            resolveProbe(false);
+            return;
+        }
+        const finish = (ready) => {
+            if (settled)
+                return;
+            settled = true;
+            if (settleTimer !== null)
+                clearTimeout(settleTimer);
+            clearTimeout(attemptTimer);
+            try {
+                // A confirmed-ready probe closes gracefully (code 1000) so the guest
+                // relay's `bridgeConnection` sees a normal browser close and does NOT
+                // record a false browser<->relay fault (P4.2 re-review Major). `close()`
+                // sends the close frame synchronously off the OPEN socket, so resolving
+                // right after calling it still delivers a normal close to the guest —
+                // the probe does not need to wait for the closing handshake to finish.
+                // Failure/timeout/error paths still abort hard via `terminate()`: there
+                // is nothing graceful to negotiate when the socket never proved ready.
+                if (ready) {
+                    ws.close(1000, 'readiness probe complete');
+                }
+                else {
+                    ws.terminate();
+                }
+            }
+            catch {
+                /* ignore */
+            }
+            resolveProbe(ready);
+        };
+        const attemptTimer = setTimeout(() => finish(false), attemptTimeoutMs);
+        ws.once('open', () => {
+            // The attempt timer (above) still bounds the total wait, so it is safe
+            // to always arm the full settle window here — whichever timer fires
+            // first wins via `finish`'s once-only guard.
+            settleTimer = setTimeout(() => finish(true), Math.min(READY_PROBE_WS_SETTLE_MS, attemptTimeoutMs));
+        });
+        ws.once('message', () => finish(true));
+        ws.once('unexpected-response', () => finish(false));
+        ws.once('error', () => finish(false));
+        ws.once('close', () => finish(false));
+    });
+}
+/** Retry the single-shot probe until it confirms `/node/<target>` is serving
+ *  or `windowMs` elapses. Always runs at least one attempt (R-WAKE-1: "a
+ *  single failed probe does not abort"). Every timer this loop starts
+ *  (the per-attempt abort timeout, the inter-attempt backoff) is cleared/
+ *  resolved before the loop returns — nothing is left armed. */
+async function probeNodeReady(previewEndpoint, target, relayToken, windowMs) {
+    const deadline = Date.now() + Math.max(0, windowMs);
+    let firstAttempt = true;
+    for (;;) {
+        const remaining = deadline - Date.now();
+        // Past the first attempt, an already-expired budget ends the loop here
+        // instead of spending one more full attempt timeout (P4.2 re-review
+        // Minor) — only the very first attempt is unconditional (R-WAKE-1: "a
+        // single failed probe does not abort"/at-least-one-attempt).
+        if (!firstAttempt && remaining <= 0)
+            return false;
+        const attemptTimeoutMs = firstAttempt
+            ? Math.max(250, Math.min(READY_PROBE_ATTEMPT_TIMEOUT_MS, windowMs))
+            : Math.min(READY_PROBE_ATTEMPT_TIMEOUT_MS, remaining);
+        firstAttempt = false;
+        if (await wakeInternals.probeNodeOnce(previewEndpoint, target, relayToken, attemptTimeoutMs))
+            return true;
+        const remainingAfter = deadline - Date.now();
+        if (remainingAfter <= 0)
+            return false;
+        await delay(Math.min(READY_PROBE_BACKOFF_MS, remainingAfter));
+    }
+}
+/** Indirection seam so a smoke/test script can swap any step (the provider
+ *  backend, the registry setters, the secret resolver, the probe itself, the
+ *  clock) without touching a real DB/provider/filesystem. Production code
+ *  never reassigns these; only ad hoc verification scripts do. */
+export const wakeInternals = {
+    getHomeById,
+    refreshProviderPointers,
+    setHomeStatus,
+    touchWake,
+    touchReady,
+    resolveSecret,
+    getHomeBackend: (config) => getHomeBackend(config),
+    loadM0Config: () => loadM0Config(),
+    loadControlPlaneConfig: () => loadControlPlaneConfig(),
+    probeNodeOnce,
+    probeNodeReady,
+    now: () => Date.now(),
+};
+const warmVerdicts = new Map();
+const inflightWakes = new Map();
+/** Cheap, non-probing fast path: return a still-fresh warm-verdict cache hit
+ *  for `home_id`, or `null` if there is none (expired or never confirmed).
+ *  Never reads the registry and never calls the provider — callers fall back
+ *  to `ensureAwake` on a `null` (Q1: "no call to provider"). */
+export function resolveRunning(home_id) {
+    const warm = warmVerdicts.get(home_id);
+    if (warm === undefined)
+        return null;
+    if (wakeInternals.now() - warm.confirmedAt >= WARM_VERDICT_TTL_MS)
+        return null;
+    return warm.result;
+}
+/** Drop the cached warm verdict for a home (e.g. an upstream relay forward
+ *  failed) so the next `ensureAwake`/`resolveRunning` re-checks instead of
+ *  trusting a stale "ready" answer. */
+export function invalidateWarmVerdict(home_id) {
+    warmVerdicts.delete(home_id);
+}
+/** Clear all warm verdicts and in-flight wake coalescing. Test/smoke-script
+ *  hygiene only — production never needs this (one CP process, S2). */
+export function resetWakeCacheForTests() {
+    warmVerdicts.clear();
+    inflightWakes.clear();
+}
+async function runEnsureAwake(home_id) {
+    const home = wakeInternals.getHomeById(home_id);
+    if (home === null)
+        throw general(`home not found: ${home_id}`, { home_id });
+    const relayAuthRef = requireHomeField(home.relay_auth_ref, 'relay_auth_ref', home_id);
+    const relayToken = wakeInternals.resolveSecret(relayAuthRef);
+    const target = requireHomeField(home.home_agent_target, 'home_agent_target', home_id);
+    const descriptor = buildDescriptor(home, relayToken);
+    const startedAt = wakeInternals.now();
+    const m0 = wakeInternals.loadM0Config();
+    const refresh = await wakeInternals.getHomeBackend(m0).wake(descriptor);
+    const normalizedStatus = normalizeProviderStatus(refresh.status);
+    const recreated = refresh.providerSandboxId !== home.provider_sandbox_id || (refresh.previewEndpoint ?? null) !== home.preview_endpoint;
+    let previewEndpoint;
+    if (recreated) {
+        // R-WAKE-6, non-negotiable: persist the new sandbox/preview pointers but
+        // never the home node target — `refreshProviderPointers`'s input shape
+        // has no `home_agent_target` field, so there is no way for this call to
+        // touch it even by accident.
+        const updated = wakeInternals.refreshProviderPointers(home_id, {
+            provider_sandbox_id: refresh.providerSandboxId,
+            preview_endpoint: refresh.previewEndpoint ?? null,
+            status: normalizedStatus,
+            template_version: refresh.templateVersion ?? home.template_version,
+        });
+        previewEndpoint = updated.preview_endpoint;
+    }
+    else {
+        wakeInternals.setHomeStatus(home_id, normalizedStatus);
+        previewEndpoint = home.preview_endpoint;
+    }
+    const resolvedPreviewEndpoint = requireHomeField(previewEndpoint, 'preview_endpoint', home_id);
+    const controlPlaneConfig = wakeInternals.loadControlPlaneConfig();
+    const ready = await wakeInternals.probeNodeReady(resolvedPreviewEndpoint, target, relayToken, controlPlaneConfig.readyTimeoutMs);
+    if (!ready) {
+        throw general(`guest web relay did not become ready before timeout: ${home_id}`, { home_id, previewEndpoint: resolvedPreviewEndpoint });
+    }
+    const readyAt = new Date().toISOString();
+    wakeInternals.touchWake(home_id, { at: new Date(startedAt).toISOString(), latency_ms: wakeInternals.now() - startedAt });
+    wakeInternals.touchReady(home_id, readyAt);
+    return { preview_endpoint: resolvedPreviewEndpoint, relayToken };
+}
+/** Bring a home up and ready, returning the route to relay to once it is.
+ *  Reads the registry, resolves the relay token, calls the provider
+ *  wake/resume seam, ready-probes `/node/<home_agent_target>`, refreshes
+ *  provider pointers on a recreate, records wake/ready timing, and returns
+ *  `{ preview_endpoint, relayToken }`. Throws on a ready-probe timeout
+ *  (wake-failure UX is deferred — gap note 2 — a throw is the accepted
+ *  cutover behavior).
+ *
+ *  A fresh warm-verdict cache hit short-circuits without re-entering this
+ *  pipeline at all. Otherwise concurrent callers for the SAME `home_id`
+ *  coalesce onto one in-flight wake (Q1) instead of each driving their own
+ *  provider call. */
+export async function ensureAwake(home_id) {
+    const warm = resolveRunning(home_id);
+    if (warm !== null)
+        return warm;
+    const inflight = inflightWakes.get(home_id);
+    if (inflight !== undefined)
+        return inflight;
+    const promise = runEnsureAwake(home_id)
+        .then((result) => {
+        warmVerdicts.set(home_id, { result, confirmedAt: wakeInternals.now() });
+        return result;
+    })
+        .finally(() => {
+        if (inflightWakes.get(home_id) === promise)
+            inflightWakes.delete(home_id);
+    });
+    inflightWakes.set(home_id, promise);
+    return promise;
+}

package/dist/hearth/wake-proxy/__tests__/anthropic-oauth.test.d.ts

@@ -0,0 +1 @@
+export {};