@gtc6244/immediacy-daemon 0.2.1 → 0.2.3

package/dist/src/telemetry.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Transport telemetry (docs/WEBRTC_MIGRATION.md §5). Starts in Phase 4 because
+ * the numbers here drive two decisions: the DO free-tier budget, and whether
+ * Phase 6 (WebRTC) is worth building at all.
+ *
+ * A tiny in-memory recorder with a typed API + optional event sink. It records:
+ *   - which transport each session used, and failover events;
+ *   - time-to-connect per transport;
+ *   - relay message count + byte volume (the DO billing driver);
+ *   - handshake failures by cause;
+ *   - reconnects, split by cause (mobile-backgrounding vs network change).
+ * No payloads, no identities — counts and durations only.
+ */
+export type TransportKind = "loopback" | "lan" | "relay" | "webrtc";
+export type HandshakeFailureCause = "unknown_device" | "bad_signature" | "expired_code" | "bad_message" | "timeout";
+export type ReconnectCause = "mobile_background" | "network_change" | "daemon_restart" | "other";
+interface ConnectStat {
+    count: number;
+    totalMs: number;
+    maxMs: number;
+}
+export interface TelemetrySnapshot {
+    sessionsByTransport: Record<string, number>;
+    failovers: number;
+    timeToConnectMs: Record<string, ConnectStat>;
+    relay: {
+        messages: number;
+        bytes: number;
+    };
+    handshakeFailures: Record<string, number>;
+    reconnects: Record<string, number>;
+}
+export type TelemetryEvent = {
+    kind: "session";
+    transport: TransportKind;
+    connectMs: number;
+} | {
+    kind: "failover";
+    from: TransportKind;
+    to: TransportKind;
+} | {
+    kind: "relay_message";
+    bytes: number;
+} | {
+    kind: "handshake_failure";
+    cause: HandshakeFailureCause;
+} | {
+    kind: "reconnect";
+    cause: ReconnectCause;
+};
+export declare class Telemetry {
+    private sessionsByTransport;
+    private failovers;
+    private timeToConnect;
+    private relayMessages;
+    private relayBytes;
+    private handshakeFailures;
+    private reconnects;
+    /** Optional sink for live streaming (e.g. to a metrics endpoint). */
+    onEvent?: (event: TelemetryEvent) => void;
+    private emit;
+    sessionEstablished(transport: TransportKind, connectMs: number): void;
+    failover(from: TransportKind, to: TransportKind): void;
+    relayMessage(bytes: number): void;
+    handshakeFailure(cause: HandshakeFailureCause): void;
+    reconnect(cause: ReconnectCause): void;
+    snapshot(): TelemetrySnapshot;
+}
+export {};

package/dist/src/telemetry.js

@@ -0,0 +1,64 @@
+/**
+ * Transport telemetry (docs/WEBRTC_MIGRATION.md §5). Starts in Phase 4 because
+ * the numbers here drive two decisions: the DO free-tier budget, and whether
+ * Phase 6 (WebRTC) is worth building at all.
+ *
+ * A tiny in-memory recorder with a typed API + optional event sink. It records:
+ *   - which transport each session used, and failover events;
+ *   - time-to-connect per transport;
+ *   - relay message count + byte volume (the DO billing driver);
+ *   - handshake failures by cause;
+ *   - reconnects, split by cause (mobile-backgrounding vs network change).
+ * No payloads, no identities — counts and durations only.
+ */
+export class Telemetry {
+    sessionsByTransport = {};
+    failovers = 0;
+    timeToConnect = {};
+    relayMessages = 0;
+    relayBytes = 0;
+    handshakeFailures = {};
+    reconnects = {};
+    /** Optional sink for live streaming (e.g. to a metrics endpoint). */
+    onEvent;
+    emit(event) {
+        this.onEvent?.(event);
+    }
+    sessionEstablished(transport, connectMs) {
+        this.sessionsByTransport[transport] = (this.sessionsByTransport[transport] ?? 0) + 1;
+        const s = this.timeToConnect[transport] ?? { count: 0, totalMs: 0, maxMs: 0 };
+        s.count++;
+        s.totalMs += connectMs;
+        s.maxMs = Math.max(s.maxMs, connectMs);
+        this.timeToConnect[transport] = s;
+        this.emit({ kind: "session", transport, connectMs });
+    }
+    failover(from, to) {
+        this.failovers++;
+        this.emit({ kind: "failover", from, to });
+    }
+    relayMessage(bytes) {
+        this.relayMessages++;
+        this.relayBytes += bytes;
+        this.emit({ kind: "relay_message", bytes });
+    }
+    handshakeFailure(cause) {
+        this.handshakeFailures[cause] = (this.handshakeFailures[cause] ?? 0) + 1;
+        this.emit({ kind: "handshake_failure", cause });
+    }
+    reconnect(cause) {
+        this.reconnects[cause] = (this.reconnects[cause] ?? 0) + 1;
+        this.emit({ kind: "reconnect", cause });
+    }
+    snapshot() {
+        return {
+            sessionsByTransport: { ...this.sessionsByTransport },
+            failovers: this.failovers,
+            timeToConnectMs: Object.fromEntries(Object.entries(this.timeToConnect).map(([k, v]) => [k, { ...v }])),
+            relay: { messages: this.relayMessages, bytes: this.relayBytes },
+            handshakeFailures: { ...this.handshakeFailures },
+            reconnects: { ...this.reconnects },
+        };
+    }
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/src/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/src/transport.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Transport abstraction + channel mux (docs/WEBRTC_MIGRATION.md §3.7, Phase 2).
+ *
+ * `Transport` is the thin byte-pipe every path implements — loopback (this
+ * file), LAN TCP (Phase 3), the DO relay (Phase 4), and WebRTC (Phase 6). It
+ * moves opaque frame bytes and exposes a `bufferedAmount` so the sender can
+ * apply backpressure. `Mux` layers the frame codec (framing.ts) on top: it
+ * chunks large messages, multiplexes the control/rpc/terminal/events channels
+ * over the one pipe, reassembles on receipt, and pauses the sender above a
+ * high-water mark so a terminal firehose can't queue multi-second lag.
+ */
+export interface Transport {
+    /** Send one already-encoded frame. */
+    send(bytes: Buffer): void;
+    /** Bytes handed to the transport but not yet flushed to the peer. */
+    bufferedAmount(): number;
+    /** Register the inbound-frame handler (one per transport). */
+    onFrame(cb: (bytes: Buffer) => void): void;
+    /** Register a close handler. */
+    onClose(cb: () => void): void;
+    /**
+     * Resolve once `bufferedAmount() < highWaterMark`. The sender awaits this
+     * between chunks to bound queue depth. Resolves immediately if already below.
+     */
+    whenWritable(highWaterMark: number): Promise<void>;
+    close(): void;
+}
+/** Default backpressure high-water mark (1 MiB queued). */
+export declare const DEFAULT_HIGH_WATER: number;
+/**
+ * An in-process, ordered, reliable transport pair for tests and same-process
+ * wiring. `pair()` returns two endpoints; a frame sent on one is delivered to
+ * the other on a later microtask (so `bufferedAmount` is observable and drains
+ * asynchronously, exercising the backpressure path).
+ */
+export declare class LoopbackTransport implements Transport {
+    private peer;
+    private frameCb;
+    private closeCb;
+    private buffered;
+    private closed;
+    private drainWaiters;
+    static pair(): [LoopbackTransport, LoopbackTransport];
+    send(bytes: Buffer): void;
+    bufferedAmount(): number;
+    onFrame(cb: (bytes: Buffer) => void): void;
+    onClose(cb: () => void): void;
+    whenWritable(highWaterMark: number): Promise<void>;
+    private wakeDrainWaiters;
+    close(): void;
+}
+/**
+ * Channel multiplexer over a `Transport`. Chunks + reassembles messages, keeps a
+ * per-channel outgoing sequence, and applies backpressure between chunks.
+ */
+export declare class Mux {
+    private readonly transport;
+    private readonly highWaterMark;
+    private readonly reassembler;
+    private readonly seqs;
+    private onMsg;
+    constructor(transport: Transport, opts?: {
+        highWaterMark?: number;
+    });
+    /** Register the reassembled-message handler. */
+    onMessage(cb: (channelId: number, message: Buffer) => void): void;
+    /** True while the transport buffer is below the high-water mark. */
+    writable(): boolean;
+    /**
+     * Send a logical message on `channelId`, chunked as needed. Resolves once all
+     * chunks are handed to the transport; awaits drain between chunks so a large
+     * message (or a terminal firehose) can't grow the queue without bound.
+     */
+    send(channelId: number, message: Buffer): Promise<void>;
+}

package/dist/src/transport.js

@@ -0,0 +1,136 @@
+/**
+ * Transport abstraction + channel mux (docs/WEBRTC_MIGRATION.md §3.7, Phase 2).
+ *
+ * `Transport` is the thin byte-pipe every path implements — loopback (this
+ * file), LAN TCP (Phase 3), the DO relay (Phase 4), and WebRTC (Phase 6). It
+ * moves opaque frame bytes and exposes a `bufferedAmount` so the sender can
+ * apply backpressure. `Mux` layers the frame codec (framing.ts) on top: it
+ * chunks large messages, multiplexes the control/rpc/terminal/events channels
+ * over the one pipe, reassembles on receipt, and pauses the sender above a
+ * high-water mark so a terminal firehose can't queue multi-second lag.
+ */
+import { decodeFrame, encodeFrame, splitMessage, Reassembler, } from "./framing.js";
+/** Default backpressure high-water mark (1 MiB queued). */
+export const DEFAULT_HIGH_WATER = 1024 * 1024;
+/**
+ * An in-process, ordered, reliable transport pair for tests and same-process
+ * wiring. `pair()` returns two endpoints; a frame sent on one is delivered to
+ * the other on a later microtask (so `bufferedAmount` is observable and drains
+ * asynchronously, exercising the backpressure path).
+ */
+export class LoopbackTransport {
+    peer;
+    frameCb = null;
+    closeCb = null;
+    buffered = 0;
+    closed = false;
+    drainWaiters = [];
+    static pair() {
+        const a = new LoopbackTransport();
+        const b = new LoopbackTransport();
+        a.peer = b;
+        b.peer = a;
+        return [a, b];
+    }
+    send(bytes) {
+        if (this.closed)
+            return;
+        const copy = Buffer.from(bytes);
+        this.buffered += copy.length;
+        // Deliver asynchronously, then decrement our buffer and wake drain waiters.
+        queueMicrotask(() => {
+            this.peer.frameCb?.(copy);
+            this.buffered -= copy.length;
+            this.wakeDrainWaiters();
+        });
+    }
+    bufferedAmount() {
+        return this.buffered;
+    }
+    onFrame(cb) {
+        this.frameCb = cb;
+    }
+    onClose(cb) {
+        this.closeCb = cb;
+    }
+    whenWritable(highWaterMark) {
+        if (this.buffered < highWaterMark)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.drainWaiters.push({ hw: highWaterMark, resolve });
+        });
+    }
+    wakeDrainWaiters() {
+        if (this.drainWaiters.length === 0)
+            return;
+        const still = [];
+        for (const w of this.drainWaiters) {
+            if (this.buffered < w.hw)
+                w.resolve();
+            else
+                still.push(w);
+        }
+        this.drainWaiters = still;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const w of this.drainWaiters)
+            w.resolve();
+        this.drainWaiters = [];
+        queueMicrotask(() => this.peer.closeCb?.());
+    }
+}
+/**
+ * Channel multiplexer over a `Transport`. Chunks + reassembles messages, keeps a
+ * per-channel outgoing sequence, and applies backpressure between chunks.
+ */
+export class Mux {
+    transport;
+    highWaterMark;
+    reassembler = new Reassembler();
+    seqs = new Map();
+    onMsg = null;
+    constructor(transport, opts) {
+        this.transport = transport;
+        this.highWaterMark = opts?.highWaterMark ?? DEFAULT_HIGH_WATER;
+        this.transport.onFrame((bytes) => {
+            let out;
+            try {
+                out = this.reassembler.push(decodeFrame(bytes));
+            }
+            catch {
+                return; // malformed/oversized frame — drop, keep the transport
+            }
+            if (out)
+                this.onMsg?.(out.channelId, out.message);
+        });
+    }
+    /** Register the reassembled-message handler. */
+    onMessage(cb) {
+        this.onMsg = cb;
+    }
+    /** True while the transport buffer is below the high-water mark. */
+    writable() {
+        return this.transport.bufferedAmount() < this.highWaterMark;
+    }
+    /**
+     * Send a logical message on `channelId`, chunked as needed. Resolves once all
+     * chunks are handed to the transport; awaits drain between chunks so a large
+     * message (or a terminal firehose) can't grow the queue without bound.
+     */
+    async send(channelId, message) {
+        let seq = this.seqs.get(channelId) ?? 0;
+        const frames = splitMessage(channelId, seq, message);
+        for (const frame of frames) {
+            this.transport.send(encodeFrame(frame));
+            seq = (frame.seq + 1) >>> 0;
+            if (this.transport.bufferedAmount() >= this.highWaterMark) {
+                await this.transport.whenWritable(this.highWaterMark);
+            }
+        }
+        this.seqs.set(channelId, seq);
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/src/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/transport.ts"],"names":[],"mappings":"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"}

package/dist/src/workspace.d.ts

@@ -3,7 +3,7 @@
  * worktree, agent, and terminal. Translates agent events into broadcast wire
  * messages and persists metadata so sessions survive a daemon restart (resume).
  */
-import type { WebSocket } from "ws";
+import type { SocketLike } from "./hub.js";
 import type { ChatEntry, DeleteBatchResultPayload, PromptAttachment, QuestionAnswers, WorkspaceActionKind, WorkspaceSummary } from "./protocol.js";
 import type { ProjectRecord, WorkspaceRecord } from "./types.js";
 import type { Hub } from "./hub.js";
@@ -14,6 +14,7 @@ import { ProjectStore } from "./projects.js";
 import { AppConfigStore } from "./config.js";
 import { CredentialsStore } from "./credentials.js";
 import { AllowlistStore } from "./allowlist.js";
+import type { PushNotifier } from "./push.js";
 import type { PermissionResponse } from "./agent/agent.js";
 export declare class WorkspaceManager {
     private hub;
@@ -47,6 +48,13 @@ export declare class WorkspaceManager {
      * a permission request with `allow_all`. Defaulted for existing callers/tests.
      */
     private allowlist;
+    /**
+     * FCM remote-wake. Optional so existing callers/tests need no change; when
+     * present, the manager wakes phones on a permission request / agent-done /
+     * usage limit — but only when no client socket is live (the notifier gates
+     * on that), so a foregrounded app is never double-notified. See push.ts.
+     */
+    private push?;
     private workspaces;
     /**
      * The last workspace list we fanned out, JSON-encoded — so
@@ -83,7 +91,14 @@ export declare class WorkspaceManager {
      * grant auto-approves matching calls, and appended to when a client answers
      * a permission request with `allow_all`. Defaulted for existing callers/tests.
      */
-    allowlist?: AllowlistStore);
+    allowlist?: AllowlistStore, 
+    /**
+     * FCM remote-wake. Optional so existing callers/tests need no change; when
+     * present, the manager wakes phones on a permission request / agent-done /
+     * usage limit — but only when no client socket is live (the notifier gates
+     * on that), so a foregrounded app is never double-notified. See push.ts.
+     */
+    push?: PushNotifier | undefined);
     /** The daemon-global allowlist (for server-side admin: list/revoke/clear). */
     allowlistStore(): AllowlistStore;
     /** Is there a live workspace with this id? (used by the job scheduler). */
@@ -327,10 +342,10 @@ export declare class WorkspaceManager {
      * are intentionally left intact so their scrollback survives a reconnect.
      */
     reapDevice(deviceId: string): void;
-    terminalInput(id: string, deviceId: string, data: string, socket: WebSocket): void;
-    terminalResize(id: string, deviceId: string, cols: number, rows: number, socket: WebSocket): void;
+    terminalInput(id: string, deviceId: string, data: string, socket: SocketLike): void;
+    terminalResize(id: string, deviceId: string, cols: number, rows: number, socket: SocketLike): void;
     /** This device's retained PTY scrollback ("" until it has started one). */
-    terminalSnapshot(id: string, deviceId: string, socket: WebSocket): string | null;
+    terminalSnapshot(id: string, deviceId: string, socket: SocketLike): string | null;
     gitStatus(id: string, sync?: boolean): Promise<import("./protocol.js").GitStatusResultPayload | null>;
     gitCommit(id: string, message: string): Promise<import("./protocol.js").GitResultPayload | null>;
     gitPush(id: string): Promise<import("./protocol.js").GitResultPayload | null>;

package/dist/src/workspace.js

@@ -83,6 +83,7 @@ export class WorkspaceManager {
     credentials;
     appConfig;
     allowlist;
+    push;
     workspaces = new Map();
     /**
      * The last workspace list we fanned out, JSON-encoded — so
@@ -119,7 +120,14 @@ export class WorkspaceManager {
      * grant auto-approves matching calls, and appended to when a client answers
      * a permission request with `allow_all`. Defaulted for existing callers/tests.
      */
-    allowlist = new AllowlistStore()) {
+    allowlist = new AllowlistStore(), 
+    /**
+     * FCM remote-wake. Optional so existing callers/tests need no change; when
+     * present, the manager wakes phones on a permission request / agent-done /
+     * usage limit — but only when no client socket is live (the notifier gates
+     * on that), so a foregrounded app is never double-notified. See push.ts.
+     */
+    push) {
         this.hub = hub;
         this.chatlog = chatlog;
         this.media = media;
@@ -128,6 +136,7 @@ export class WorkspaceManager {
         this.credentials = credentials;
         this.appConfig = appConfig;
         this.allowlist = allowlist;
+        this.push = push;
     }
     /** The daemon-global allowlist (for server-side admin: list/revoke/clear). */
     allowlistStore() {
@@ -1263,6 +1272,9 @@ export class WorkspaceManager {
                     inputSummary: e.inputSummary,
                     seq: permEntry.seq,
                 });
+                // Remote-wake a backgrounded phone so the deferred call doesn't sit
+                // unseen (no-op when a client socket is live — see PushNotifier).
+                this.push?.notifyPermission(id, live.record.name, e.tool, e.inputSummary, permEntry.seq);
                 break;
             }
             case "permission_resolved":
@@ -1327,6 +1339,9 @@ export class WorkspaceManager {
                     usageText,
                     seq: doneEntry.seq,
                 });
+                // Remote-wake so a turn that finished while the app was closed still
+                // notifies (no-op when a client socket is live — see PushNotifier).
+                this.push?.notifyDone(id, live.record.name, e.summary, doneEntry.seq);
                 // The turn almost certainly touched files, so the sidebar diff-stat is
                 // now stale — recompute and fan the fresh counts out (no-ops if the turn
                 // changed nothing). This keeps a background workspace's counter live
@@ -1349,6 +1364,9 @@ export class WorkspaceManager {
                     message: e.message,
                     resetAt: e.resetAt,
                 });
+                // Remote-wake so the user learns the run stalled on a limit even with the
+                // app closed (no-op when a client socket is live — see PushNotifier).
+                this.push?.notifyLimit(id, live.record.name, e.message);
                 // Persist as a `limit` entry (not a plain system line) so a reconnecting
                 // client replays the actionable restart card, not just static text.
                 void this.chatlog.append(id, {