@wenrwa/marketplace-cli 0.4.4 → 0.4.6

package/dist/bridge/browserFrames.d.ts

@@ -0,0 +1,182 @@
+/**
+ * cbs-01 — Cloud Browser Session frame protocol, v1.
+ *
+ * (docs/prd/cloud-browser-session.md, ADR TBD) A headless Chromium runs
+ * inside the user's per-user container, driven over CDP by the bridge, and
+ * streamed to the arena Browser pane over the SAME terminal relay socket as
+ * PTY frames (no parallel transport) — new non-PTY frame types, modeled on
+ * the existing `install-bundle` / `context-manifest` precedent in
+ * relayClient.ts (see PROTOCOL.md). This module defines ONLY the wire
+ * shapes + runtime type guards; it is deliberately NOT wired into
+ * relayClient.ts in this slice (no relay/backend code is touched by cbs-01).
+ *
+ * ── Envelope discipline (matches ClientFrame in relayClient.ts) ──────────
+ *   - Protocol version: v1 (BROWSER_FRAME_PROTOCOL_VERSION below). Frames
+ *     do not carry a per-frame `v` — like the existing terminal frames, the
+ *     version is asserted once at connection handshake time, not per frame.
+ *   - Text-only JSON envelope. Every frame is `{ t, sessionId, ...fields }`.
+ *     Binary payloads (the JPEG screencast frame) ride as base64 `data`
+ *     inside the JSON, exactly like PTY `data` frames already do.
+ *   - Session identity: `browser:<containerId>` (mirrors the `login:` prefix
+ *     precedent) — out of scope for this slice, but every frame here already
+ *     carries `sessionId` so routing needs no protocol change to adopt it.
+ *
+ * ── Frame directions ──────────────────────────────────────────────────────
+ *   pane -> container:
+ *     `browser-open`  { t, sessionId, url }
+ *     `browser-input` { t, sessionId, event }  — event is a discriminated
+ *                        union (mouse | key | insertText | wheel)
+ *   container -> pane:
+ *     `browser-frame` { t, sessionId, seq, data, w, h } — data is base64 JPEG
+ *     `browser-state` { t, sessionId, state, url?, title?, reason? }
+ *
+ * ── Drop rule (the whole point of framePacer.ts) ──────────────────────────
+ *   FRAMES are droppable — `browser-frame` is a keep-newest video stream; a
+ *   slow consumer sees the newest frame, never an unbounded backlog.
+ *   INPUTS are never dropped — `browser-input` is small and ORDER-SENSITIVE
+ *   (a mouse-down must reach the page before its mouse-up); it bypasses the
+ *   frame pacer entirely and is expected to ride the relay's existing
+ *   ordered-delivery guarantee, same as PTY `input` frames today.
+ *
+ * ── cbs-06 additions (ack + sleep) ─────────────────────────────────────────
+ *   Arena's Browser pane (cbs-05, landed on arena master) needed two shapes
+ *   this file left undefined. This CLI file is the hand-maintained mirror
+ *   (see the MIRROR NOTICE at the top of this block) — cbs-06 lands the
+ *   matching addition here so the two repos' shape-pinning tests stay in
+ *   sync:
+ *     `browser-frame-ack` { t, sessionId, seq } — pane -> container. The
+ *        other half of the keep-newest pacing contract: cbs-06 wires this
+ *        into the bridge's CDP screencast ack gate (framePacer.ts via
+ *        browserDriver.ackFrame()), replacing the interim cbs-02 policy of
+ *        self-acking on send. The pane must ack every `browser-frame` it
+ *        actually PAINTED (never batched, never sent for a frame that was
+ *        superseded before it rendered).
+ *     `browser-sleep` { t, sessionId } — pane -> container. The pane's
+ *        explicit 💤 control (mirrors the terminal pane's manual-sleep
+ *        affordance) — minimal, no payload beyond identity, same effect as
+ *        the bridge's 15-minute idle auto-close (browserIdle.ts) but
+ *        user-triggered.
+ */
+/** Protocol version for the cloud browser session frame set. */
+export declare const BROWSER_FRAME_PROTOCOL_VERSION = 1;
+/** Keyboard/mouse modifier flags — abstracted from CDP's bitmask so callers
+ *  don't need to know CDP's encoding; the bridge's CDP driver (a later
+ *  slice) maps these to `Input.dispatchMouseEvent`/`dispatchKeyEvent`'s
+ *  `modifiers` bitfield. */
+export interface BrowserInputModifiers {
+    shift?: boolean;
+    ctrl?: boolean;
+    alt?: boolean;
+    meta?: boolean;
+}
+export type BrowserMouseButton = 'left' | 'middle' | 'right';
+export interface BrowserMouseInputEvent {
+    kind: 'mouse';
+    type: 'down' | 'up' | 'move';
+    x: number;
+    y: number;
+    /** Omitted on `move` (no button implicated). */
+    button?: BrowserMouseButton;
+    modifiers?: BrowserInputModifiers;
+}
+export interface BrowserKeyInputEvent {
+    kind: 'key';
+    type: 'down' | 'up';
+    /** DOM KeyboardEvent.key, e.g. 'a', 'Enter', 'Backspace'. */
+    key: string;
+    /** DOM KeyboardEvent.code, e.g. 'KeyA', 'Enter'. */
+    code: string;
+    modifiers?: BrowserInputModifiers;
+}
+/** IME composition / paste text — maps 1:1 to CDP's `Input.insertText`,
+ *  which is how passwords from a password manager and non-Latin IME input
+ *  reach the page without synthesizing a keystroke per character. */
+export interface BrowserInsertTextInputEvent {
+    kind: 'insertText';
+    text: string;
+}
+export interface BrowserWheelInputEvent {
+    kind: 'wheel';
+    x: number;
+    y: number;
+    deltaX: number;
+    deltaY: number;
+}
+export type BrowserInputEvent = BrowserMouseInputEvent | BrowserKeyInputEvent | BrowserInsertTextInputEvent | BrowserWheelInputEvent;
+/** pane -> container: open (or re-navigate) the user's private headless
+ *  Chromium tab to `url`. */
+export interface BrowserOpenFrame {
+    t: 'browser-open';
+    sessionId: string;
+    url: string;
+}
+/** pane -> container: one input event. NEVER paced/dropped (see the module
+ *  doc block's drop rule) — every `browser-input` frame must reach the
+ *  container in the order it was sent. */
+export interface BrowserInputFrame {
+    t: 'browser-input';
+    sessionId: string;
+    event: BrowserInputEvent;
+}
+/** container -> pane: one JPEG screencast frame from CDP's
+ *  `Page.startScreencast`. `data` is base64-encoded JPEG bytes; `seq` is a
+ *  monotonically increasing per-session counter the pane acks by number
+ *  (ack semantics live in the pane's consumer, not this type). This is the
+ *  frame kind the keep-newest pacer (framePacer.ts) governs. */
+export interface BrowserScreenFrame {
+    t: 'browser-frame';
+    sessionId: string;
+    seq: number;
+    /** base64 JPEG. */
+    data: string;
+    w: number;
+    h: number;
+}
+/** pane -> container: acknowledges a displayed `browser-frame` by `seq` —
+ *  cbs-06 mirror of arena's cbs-05 addition, see the module doc block's
+ *  "cbs-06 additions" section. NEVER sent for a frame that was superseded
+ *  before it painted (keep-newest: the pane only ever holds the LATEST
+ *  frame, so only the latest gets acked). */
+export interface BrowserFrameAckFrame {
+    t: 'browser-frame-ack';
+    sessionId: string;
+    seq: number;
+}
+/** pane -> container: explicit manual sleep (the pane's 💤 control) —
+ *  cbs-06 mirror of arena's cbs-05 addition, see the module doc block's
+ *  "cbs-06 additions" section. Minimal: no payload beyond session identity. */
+export interface BrowserSleepFrame {
+    t: 'browser-sleep';
+    sessionId: string;
+}
+export type BrowserSessionState = 'opening' | 'open' | 'asleep' | 'closed';
+/** container -> pane: session lifecycle / navigation state. `reason` is a
+ *  short machine string (e.g. 'idle-timeout', 'awake-cap') for `asleep`/
+ *  `closed`, surfaced by the pane as an explanatory message. */
+export interface BrowserStateFrame {
+    t: 'browser-state';
+    sessionId: string;
+    state: BrowserSessionState;
+    url?: string;
+    title?: string;
+    reason?: string;
+}
+/** pane -> container frames. */
+export type BrowserPaneToContainerFrame = BrowserOpenFrame | BrowserInputFrame | BrowserFrameAckFrame | BrowserSleepFrame;
+/** container -> pane frames. */
+export type BrowserContainerToPaneFrame = BrowserScreenFrame | BrowserStateFrame;
+/** The full v1 cloud browser session frame set, either direction. */
+export type BrowserFrame = BrowserPaneToContainerFrame | BrowserContainerToPaneFrame;
+export declare function isBrowserOpenFrame(v: unknown): v is BrowserOpenFrame;
+export declare function isBrowserInputEvent(v: unknown): v is BrowserInputEvent;
+export declare function isBrowserInputFrame(v: unknown): v is BrowserInputFrame;
+/** cbs-06 mirror of arena's cbs-05 addition — see the module doc block's
+ *  "cbs-06 additions" section. */
+export declare function isBrowserFrameAckFrame(v: unknown): v is BrowserFrameAckFrame;
+/** cbs-06 mirror of arena's cbs-05 addition — see the module doc block's
+ *  "cbs-06 additions" section. */
+export declare function isBrowserSleepFrame(v: unknown): v is BrowserSleepFrame;
+export declare function isBrowserScreenFrame(v: unknown): v is BrowserScreenFrame;
+export declare function isBrowserStateFrame(v: unknown): v is BrowserStateFrame;
+/** True for any v1 cloud browser session frame, either direction. */
+export declare function isBrowserFrame(v: unknown): v is BrowserFrame;

package/dist/bridge/browserFrames.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * cbs-01 — Cloud Browser Session frame protocol, v1.
+ *
+ * (docs/prd/cloud-browser-session.md, ADR TBD) A headless Chromium runs
+ * inside the user's per-user container, driven over CDP by the bridge, and
+ * streamed to the arena Browser pane over the SAME terminal relay socket as
+ * PTY frames (no parallel transport) — new non-PTY frame types, modeled on
+ * the existing `install-bundle` / `context-manifest` precedent in
+ * relayClient.ts (see PROTOCOL.md). This module defines ONLY the wire
+ * shapes + runtime type guards; it is deliberately NOT wired into
+ * relayClient.ts in this slice (no relay/backend code is touched by cbs-01).
+ *
+ * ── Envelope discipline (matches ClientFrame in relayClient.ts) ──────────
+ *   - Protocol version: v1 (BROWSER_FRAME_PROTOCOL_VERSION below). Frames
+ *     do not carry a per-frame `v` — like the existing terminal frames, the
+ *     version is asserted once at connection handshake time, not per frame.
+ *   - Text-only JSON envelope. Every frame is `{ t, sessionId, ...fields }`.
+ *     Binary payloads (the JPEG screencast frame) ride as base64 `data`
+ *     inside the JSON, exactly like PTY `data` frames already do.
+ *   - Session identity: `browser:<containerId>` (mirrors the `login:` prefix
+ *     precedent) — out of scope for this slice, but every frame here already
+ *     carries `sessionId` so routing needs no protocol change to adopt it.
+ *
+ * ── Frame directions ──────────────────────────────────────────────────────
+ *   pane -> container:
+ *     `browser-open`  { t, sessionId, url }
+ *     `browser-input` { t, sessionId, event }  — event is a discriminated
+ *                        union (mouse | key | insertText | wheel)
+ *   container -> pane:
+ *     `browser-frame` { t, sessionId, seq, data, w, h } — data is base64 JPEG
+ *     `browser-state` { t, sessionId, state, url?, title?, reason? }
+ *
+ * ── Drop rule (the whole point of framePacer.ts) ──────────────────────────
+ *   FRAMES are droppable — `browser-frame` is a keep-newest video stream; a
+ *   slow consumer sees the newest frame, never an unbounded backlog.
+ *   INPUTS are never dropped — `browser-input` is small and ORDER-SENSITIVE
+ *   (a mouse-down must reach the page before its mouse-up); it bypasses the
+ *   frame pacer entirely and is expected to ride the relay's existing
+ *   ordered-delivery guarantee, same as PTY `input` frames today.
+ *
+ * ── cbs-06 additions (ack + sleep) ─────────────────────────────────────────
+ *   Arena's Browser pane (cbs-05, landed on arena master) needed two shapes
+ *   this file left undefined. This CLI file is the hand-maintained mirror
+ *   (see the MIRROR NOTICE at the top of this block) — cbs-06 lands the
+ *   matching addition here so the two repos' shape-pinning tests stay in
+ *   sync:
+ *     `browser-frame-ack` { t, sessionId, seq } — pane -> container. The
+ *        other half of the keep-newest pacing contract: cbs-06 wires this
+ *        into the bridge's CDP screencast ack gate (framePacer.ts via
+ *        browserDriver.ackFrame()), replacing the interim cbs-02 policy of
+ *        self-acking on send. The pane must ack every `browser-frame` it
+ *        actually PAINTED (never batched, never sent for a frame that was
+ *        superseded before it rendered).
+ *     `browser-sleep` { t, sessionId } — pane -> container. The pane's
+ *        explicit 💤 control (mirrors the terminal pane's manual-sleep
+ *        affordance) — minimal, no payload beyond identity, same effect as
+ *        the bridge's 15-minute idle auto-close (browserIdle.ts) but
+ *        user-triggered.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BROWSER_FRAME_PROTOCOL_VERSION = void 0;
+exports.isBrowserOpenFrame = isBrowserOpenFrame;
+exports.isBrowserInputEvent = isBrowserInputEvent;
+exports.isBrowserInputFrame = isBrowserInputFrame;
+exports.isBrowserFrameAckFrame = isBrowserFrameAckFrame;
+exports.isBrowserSleepFrame = isBrowserSleepFrame;
+exports.isBrowserScreenFrame = isBrowserScreenFrame;
+exports.isBrowserStateFrame = isBrowserStateFrame;
+exports.isBrowserFrame = isBrowserFrame;
+/** Protocol version for the cloud browser session frame set. */
+exports.BROWSER_FRAME_PROTOCOL_VERSION = 1;
+// ── Type guards ─────────────────────────────────────────────────────────
+function isRecord(v) {
+    return typeof v === 'object' && v !== null;
+}
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.length > 0;
+}
+function isModifiers(v) {
+    if (v === undefined)
+        return true;
+    if (!isRecord(v))
+        return false;
+    for (const key of ['shift', 'ctrl', 'alt', 'meta']) {
+        const val = v[key];
+        if (val !== undefined && typeof val !== 'boolean')
+            return false;
+    }
+    return true;
+}
+function isBrowserOpenFrame(v) {
+    if (!isRecord(v))
+        return false;
+    return v.t === 'browser-open' && isNonEmptyString(v.sessionId) && typeof v.url === 'string';
+}
+function isBrowserInputEvent(v) {
+    if (!isRecord(v))
+        return false;
+    switch (v.kind) {
+        case 'mouse':
+            return ((v.type === 'down' || v.type === 'up' || v.type === 'move') &&
+                typeof v.x === 'number' &&
+                typeof v.y === 'number' &&
+                (v.button === undefined || v.button === 'left' || v.button === 'middle' || v.button === 'right') &&
+                isModifiers(v.modifiers));
+        case 'key':
+            return ((v.type === 'down' || v.type === 'up') &&
+                typeof v.key === 'string' &&
+                typeof v.code === 'string' &&
+                isModifiers(v.modifiers));
+        case 'insertText':
+            return typeof v.text === 'string';
+        case 'wheel':
+            return (typeof v.x === 'number' &&
+                typeof v.y === 'number' &&
+                typeof v.deltaX === 'number' &&
+                typeof v.deltaY === 'number');
+        default:
+            return false;
+    }
+}
+function isBrowserInputFrame(v) {
+    if (!isRecord(v))
+        return false;
+    return v.t === 'browser-input' && isNonEmptyString(v.sessionId) && isBrowserInputEvent(v.event);
+}
+/** cbs-06 mirror of arena's cbs-05 addition — see the module doc block's
+ *  "cbs-06 additions" section. */
+function isBrowserFrameAckFrame(v) {
+    if (!isRecord(v))
+        return false;
+    return v.t === 'browser-frame-ack' && isNonEmptyString(v.sessionId) && typeof v.seq === 'number' && v.seq >= 0;
+}
+/** cbs-06 mirror of arena's cbs-05 addition — see the module doc block's
+ *  "cbs-06 additions" section. */
+function isBrowserSleepFrame(v) {
+    if (!isRecord(v))
+        return false;
+    return v.t === 'browser-sleep' && isNonEmptyString(v.sessionId);
+}
+function isBrowserScreenFrame(v) {
+    if (!isRecord(v))
+        return false;
+    return (v.t === 'browser-frame' &&
+        isNonEmptyString(v.sessionId) &&
+        typeof v.seq === 'number' &&
+        v.seq >= 0 &&
+        typeof v.data === 'string' &&
+        typeof v.w === 'number' &&
+        v.w > 0 &&
+        typeof v.h === 'number' &&
+        v.h > 0);
+}
+const BROWSER_SESSION_STATES = ['opening', 'open', 'asleep', 'closed'];
+function isBrowserStateFrame(v) {
+    if (!isRecord(v))
+        return false;
+    if (v.t !== 'browser-state' || !isNonEmptyString(v.sessionId))
+        return false;
+    if (typeof v.state !== 'string' || !BROWSER_SESSION_STATES.includes(v.state))
+        return false;
+    if (v.url !== undefined && typeof v.url !== 'string')
+        return false;
+    if (v.title !== undefined && typeof v.title !== 'string')
+        return false;
+    if (v.reason !== undefined && typeof v.reason !== 'string')
+        return false;
+    return true;
+}
+/** True for any v1 cloud browser session frame, either direction. */
+function isBrowserFrame(v) {
+    return (isBrowserOpenFrame(v) ||
+        isBrowserInputFrame(v) ||
+        isBrowserFrameAckFrame(v) ||
+        isBrowserSleepFrame(v) ||
+        isBrowserScreenFrame(v) ||
+        isBrowserStateFrame(v));
+}

package/dist/bridge/browserIdle.d.ts

@@ -0,0 +1,75 @@
+/**
+ * cbs-06 — cloud browser session idle timer.
+ *
+ * (docs/prd/cloud-browser-session.md, issues/cbs-06-idle-lifecycle.md)
+ * Lifecycle parity with agents, bridge-side: a browser session with no
+ * input AND no viewer for `thresholdMs` (default 15 minutes) auto-closes.
+ * Two liveness signals, tracked independently — INPUT (`browser-input`
+ * frames) and ACK (`browser-frame-ack` frames, a proxy for "someone is
+ * actually looking at the stream", since a displayed frame implies a live
+ * viewer) — mirroring the container-level idle convention exactly
+ * (container-lifecycle.service.ts: "Idle is (a) AND (b) both true; either
+ * signal alone is enough to stay awake"). This module owns no Chromium/CDP
+ * knowledge; it only decides WHEN to call `onIdle()` — the caller
+ * (relayClient.ts) owns what that means (driver.stop() + browser-state
+ * asleep).
+ *
+ * ── Suspend-safety (the crux) ─────────────────────────────────────────────
+ * The container is RAM-suspended when idle (twr-13/ADR-0034); suspend and
+ * resume must be transparent, but a naive wall-clock idle check is NOT
+ * transparent — `Date.now() - lastInputAt` after a multi-hour suspend
+ * reflects the FULL suspend duration (wall clock keeps ticking / gets
+ * corrected on resume) even though nothing "idle" actually happened; the
+ * browser itself was frozen, not neglected. A false fire here would close a
+ * session the instant it woke up.
+ *
+ * The fix: every periodic check compares the WALL-clock delta since the
+ * last check (`nowFn`) against the MONOTONIC delta since the last check
+ * (`monotonicNowFn`, defaults to `process.hrtime`). A RAM-snapshot suspend
+ * freezes the guest's monotonic clock (no CPU cycles execute) but the wall
+ * clock jumps forward on resume — so `wallDelta` far exceeding `monoDelta`
+ * (beyond `suspendGapToleranceMs`, a generous allowance for ordinary
+ * event-loop/GC scheduling jitter) is the suspend's signature. When
+ * detected, the tick is NOT evaluated for idleness at all — both baselines
+ * reset to "now", exactly as if the user had just interacted, giving the
+ * resumed session a full fresh window rather than firing immediately.
+ *
+ * Pure-ish: no CDP/process access, only injectable clocks + an injectable
+ * interval scheduler (same injection pattern as relayClient's login poll /
+ * activity throttle) so tests never wait on a real clock.
+ */
+/** PRD: "15-minute no-input/no-viewer timer". */
+export declare const DEFAULT_BROWSER_IDLE_THRESHOLD_MS: number;
+export interface BrowserIdleOpts {
+    /** Called once both lastInputAt and lastAckAt are stale past the
+     *  threshold. Fires at most once per tracker (latched). */
+    onIdle: () => void;
+    /** Idle threshold in ms, applied to BOTH signals. Default 15 minutes
+     *  (DEFAULT_BROWSER_IDLE_THRESHOLD_MS). */
+    thresholdMs?: number;
+    /** How often to re-evaluate. Default 30_000ms. */
+    checkIntervalMs?: number;
+    /** Suspend-gap detection tolerance — see the module doc block. Default
+     *  5_000ms. */
+    suspendGapToleranceMs?: number;
+    /** Injectable wall clock. Default Date.now. */
+    nowFn?: () => number;
+    /** Injectable monotonic clock (ms). Default process.hrtime-based. */
+    monotonicNowFn?: () => number;
+    /** Injectable interval timer so tests are deterministic. Defaults to
+     *  setInterval. */
+    setIntervalFn?: (cb: () => void, ms: number) => unknown;
+    clearIntervalFn?: (handle: unknown) => void;
+}
+export interface BrowserIdleTracker {
+    /** Bump the input liveness signal to "now". */
+    recordInput(): void;
+    /** Bump the ack (viewer proxy) liveness signal to "now". */
+    recordAck(): void;
+    /** Begin periodic evaluation. Idempotent — a second call is a no-op. */
+    start(): void;
+    /** Stop periodic evaluation (cancels the interval). Safe to call more
+     *  than once and safe to call before start(). */
+    stop(): void;
+}
+export declare function createBrowserIdleTracker(opts: BrowserIdleOpts): BrowserIdleTracker;

package/dist/bridge/browserIdle.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * cbs-06 — cloud browser session idle timer.
+ *
+ * (docs/prd/cloud-browser-session.md, issues/cbs-06-idle-lifecycle.md)
+ * Lifecycle parity with agents, bridge-side: a browser session with no
+ * input AND no viewer for `thresholdMs` (default 15 minutes) auto-closes.
+ * Two liveness signals, tracked independently — INPUT (`browser-input`
+ * frames) and ACK (`browser-frame-ack` frames, a proxy for "someone is
+ * actually looking at the stream", since a displayed frame implies a live
+ * viewer) — mirroring the container-level idle convention exactly
+ * (container-lifecycle.service.ts: "Idle is (a) AND (b) both true; either
+ * signal alone is enough to stay awake"). This module owns no Chromium/CDP
+ * knowledge; it only decides WHEN to call `onIdle()` — the caller
+ * (relayClient.ts) owns what that means (driver.stop() + browser-state
+ * asleep).
+ *
+ * ── Suspend-safety (the crux) ─────────────────────────────────────────────
+ * The container is RAM-suspended when idle (twr-13/ADR-0034); suspend and
+ * resume must be transparent, but a naive wall-clock idle check is NOT
+ * transparent — `Date.now() - lastInputAt` after a multi-hour suspend
+ * reflects the FULL suspend duration (wall clock keeps ticking / gets
+ * corrected on resume) even though nothing "idle" actually happened; the
+ * browser itself was frozen, not neglected. A false fire here would close a
+ * session the instant it woke up.
+ *
+ * The fix: every periodic check compares the WALL-clock delta since the
+ * last check (`nowFn`) against the MONOTONIC delta since the last check
+ * (`monotonicNowFn`, defaults to `process.hrtime`). A RAM-snapshot suspend
+ * freezes the guest's monotonic clock (no CPU cycles execute) but the wall
+ * clock jumps forward on resume — so `wallDelta` far exceeding `monoDelta`
+ * (beyond `suspendGapToleranceMs`, a generous allowance for ordinary
+ * event-loop/GC scheduling jitter) is the suspend's signature. When
+ * detected, the tick is NOT evaluated for idleness at all — both baselines
+ * reset to "now", exactly as if the user had just interacted, giving the
+ * resumed session a full fresh window rather than firing immediately.
+ *
+ * Pure-ish: no CDP/process access, only injectable clocks + an injectable
+ * interval scheduler (same injection pattern as relayClient's login poll /
+ * activity throttle) so tests never wait on a real clock.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BROWSER_IDLE_THRESHOLD_MS = void 0;
+exports.createBrowserIdleTracker = createBrowserIdleTracker;
+/** PRD: "15-minute no-input/no-viewer timer". */
+exports.DEFAULT_BROWSER_IDLE_THRESHOLD_MS = 15 * 60_000;
+/** How often the idle condition is (re-)evaluated. Cheap pure comparisons —
+ *  30s gives quick-enough response without meaningful overhead. */
+const DEFAULT_CHECK_INTERVAL_MS = 30_000;
+/** Generous allowance for ordinary scheduling jitter (GC pauses, event-loop
+ *  backlog) between the wall and monotonic deltas of a single check
+ *  interval — far below any real suspend gap (minutes to hours), so it
+ *  never masks a genuine one while never false-triggering on jitter. */
+const DEFAULT_SUSPEND_GAP_TOLERANCE_MS = 5_000;
+function defaultMonotonicNowMs() {
+    return Number(process.hrtime.bigint() / 1000000n);
+}
+function createBrowserIdleTracker(opts) {
+    const thresholdMs = opts.thresholdMs ?? exports.DEFAULT_BROWSER_IDLE_THRESHOLD_MS;
+    const checkIntervalMs = opts.checkIntervalMs ?? DEFAULT_CHECK_INTERVAL_MS;
+    const suspendGapToleranceMs = opts.suspendGapToleranceMs ?? DEFAULT_SUSPEND_GAP_TOLERANCE_MS;
+    const now = opts.nowFn ?? Date.now;
+    const monotonicNow = opts.monotonicNowFn ?? defaultMonotonicNowMs;
+    const scheduleInterval = opts.setIntervalFn ?? ((cb, ms) => setInterval(cb, ms));
+    const cancelInterval = opts.clearIntervalFn ?? ((h) => clearInterval(h));
+    let lastInputAt = now();
+    let lastAckAt = now();
+    let lastCheckWall = now();
+    let lastCheckMono = monotonicNow();
+    let handle = null;
+    let fired = false;
+    function resetBaseline(atWall) {
+        lastInputAt = atWall;
+        lastAckAt = atWall;
+    }
+    function check() {
+        if (fired)
+            return;
+        const wallNow = now();
+        const monoNow = monotonicNow();
+        const wallDelta = wallNow - lastCheckWall;
+        const monoDelta = monoNow - lastCheckMono;
+        lastCheckWall = wallNow;
+        lastCheckMono = monoNow;
+        if (wallDelta - monoDelta > suspendGapToleranceMs) {
+            // Suspend gap: the wall clock advanced far more than real (monotonic)
+            // time did. Not idle time — reset the baseline instead of evaluating.
+            resetBaseline(wallNow);
+            return;
+        }
+        const inputIdleMs = wallNow - lastInputAt;
+        const ackIdleMs = wallNow - lastAckAt;
+        if (inputIdleMs >= thresholdMs && ackIdleMs >= thresholdMs) {
+            fired = true;
+            opts.onIdle();
+        }
+    }
+    return {
+        recordInput() {
+            lastInputAt = now();
+        },
+        recordAck() {
+            lastAckAt = now();
+        },
+        start() {
+            if (handle !== null)
+                return;
+            lastCheckWall = now();
+            lastCheckMono = monotonicNow();
+            handle = scheduleInterval(check, checkIntervalMs);
+            handle?.unref?.();
+        },
+        stop() {
+            if (handle === null)
+                return;
+            cancelInterval(handle);
+            handle = null;
+        },
+    };
+}

package/dist/bridge/bundleInstaller.d.ts

@@ -0,0 +1,31 @@
+export type FileMap = Record<string, string>;
+export interface BundleInstallerDeps {
+    /** Root holding every workspace's checkout, e.g. `/data/repos`. */
+    reposBaseDir: string;
+    /** Create a directory (recursively). */
+    mkdirp: (dir: string) => void;
+    /** Write (overwrite) a file. */
+    writeFile: (filePath: string, content: string) => void;
+}
+export type SkipReason = 'unsafe' | 'unmanaged';
+export interface InstallBundleResult {
+    /** The absolute workspace checkout root, or null if the workspaceId itself was unsafe. */
+    workspaceRoot: string | null;
+    /** Managed paths (relative) that were written. */
+    written: string[];
+    /** Entries refused, with why. */
+    skipped: Array<{
+        path: string;
+        reason: SkipReason;
+    }>;
+}
+/**
+ * A workspaceId is the sole dir segment under reposBaseDir — it must be a plain
+ * id, never a path fragment. Reject anything that could climb out of / redirect
+ * the base dir before we ever join it.
+ */
+export declare function isSafeWorkspaceId(workspaceId: string): boolean;
+export declare function installBundle(bundle: {
+    workspaceId: string;
+    files: FileMap;
+}, deps: BundleInstallerDeps): InstallBundleResult;