@runuai/host 0.9.12 → 0.9.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.12",
+  "version": "0.9.13",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",

package/src/event-outbox.ts

@@ -0,0 +1,104 @@
+/**
+ * ADR-103: the host-side event outbox.
+ *
+ * Every HostEvent gets a monotonic seq and its serialized wire frame is held
+ * here until the cloud acks it. The bridge connection drains the outbox in
+ * order — live traffic and reconnect replay are the same code path, so a
+ * WSS blip (a cloud deploy) can no longer drop events on the floor.
+ *
+ * Bounded, in-memory. A host PROCESS restart still loses unsent events —
+ * that path is ADR-061's (the restarted host reattaches to the container
+ * and resumes streaming); this outbox closes the disconnect gap only.
+ */
+
+import type { HostEvent } from "./protocol";
+
+export interface OutboxEntry {
+  seq: number;
+  /** The full serialized `{kind:"event", seq, event}` frame, ready to send. */
+  raw: string;
+}
+
+/** Overflow bounds. Generous: a disconnect longer than this many events is a
+ *  real outage, not a deploy blip, and dropping OLDEST keeps the tail — the
+ *  most recent turn — intact for replay. */
+const MAX_ENTRIES = 10_000;
+const MAX_BYTES = 32 * 1024 * 1024;
+
+export class EventOutbox {
+  private entries: OutboxEntry[] = [];
+  private totalBytes = 0;
+  private nextSeq = 1;
+  /** Highest seq ever transmitted on any connection. */
+  private sentUpTo = 0;
+  /** Entries dropped by overflow since the last drain — for one loud log. */
+  private droppedSinceDrain = 0;
+
+  /** Serialize + append. Returns the entry's seq. */
+  enqueue(event: HostEvent): number {
+    const seq = this.nextSeq++;
+    const raw = JSON.stringify({ kind: "event", seq, event });
+    this.entries.push({ seq, raw });
+    this.totalBytes += raw.length;
+    while (
+      this.entries.length > MAX_ENTRIES ||
+      (this.totalBytes > MAX_BYTES && this.entries.length > 1)
+    ) {
+      const dropped = this.entries.shift();
+      if (!dropped) break;
+      this.totalBytes -= dropped.raw.length;
+      // Only a NEVER-SENT entry is a real loss; an unacked-but-sent one most
+      // likely landed and just lost its ack.
+      if (dropped.seq > this.sentUpTo) this.droppedSinceDrain += 1;
+    }
+    return seq;
+  }
+
+  /** Cumulative ack: forget everything up to and including `seq`. */
+  ack(seq: number): void {
+    let i = 0;
+    for (const entry of this.entries) {
+      if (entry.seq > seq) break;
+      this.totalBytes -= entry.raw.length;
+      i += 1;
+    }
+    if (i > 0) this.entries.splice(0, i);
+    if (seq > this.sentUpTo) this.sentUpTo = seq;
+  }
+
+  /**
+   * Rewind the transmit cursor for a reconnect (ADR-103 resume handshake).
+   * `afterSeq` is the cloud's watermark: everything newer re-sends on the
+   * next drain. `null` = the cloud has no state for this boot — replay
+   * nothing; only never-transmitted entries go out.
+   */
+  resume(afterSeq: number | null): void {
+    if (afterSeq !== null && afterSeq < this.sentUpTo) this.sentUpTo = afterSeq;
+  }
+
+  /**
+   * Entries due for transmission, in order. The caller sends them and the
+   * cursor advances — drain is idempotent per entry until `resume` rewinds.
+   */
+  drain(): OutboxEntry[] {
+    const due = this.entries.filter((e) => e.seq > this.sentUpTo);
+    const last = due[due.length - 1];
+    if (last) this.sentUpTo = last.seq;
+    return due;
+  }
+
+  /** Never-sent entries lost to overflow since the last call; resets. */
+  takeDroppedCount(): number {
+    const n = this.droppedSinceDrain;
+    this.droppedSinceDrain = 0;
+    return n;
+  }
+
+  get size(): number {
+    return this.entries.length;
+  }
+
+  get bytes(): number {
+    return this.totalBytes;
+  }
+}

package/src/main.ts

@@ -82,8 +82,10 @@ import { canAdvertiseTypedSecretaryDispatch } from "../lib/agents/mode";
 import "../lib/agents/factory";
 import { ensureStandardImage, standardRuntimes } from "../lib/standard-image";
 import { hostCommands, hostEvents } from "./index";
+import { EventOutbox } from "./event-outbox";
 import {
   HostErrorCode,
+  EVENT_REPLAY_PROTOCOL_FEATURE,
   GITHUB_CREDENTIAL_GENERATION_PROTOCOL_FEATURE,
   GITHUB_INSTALLATION_VERIFICATION_PROTOCOL_FEATURE,
   GITHUB_REPOSITORY_ACCESS_PROTOCOL_FEATURE,
@@ -149,6 +151,33 @@ let shutdownRequested = false;
 let pendingBinaryTunnelId: string | null = null;
 const tunnels = new TunnelRegistry();
 
+// ADR-103: event outbox. BOOT_ID scopes seqs to this process lifetime; the
+// cloud's replay watermark only applies within a matching boot. Events are
+// enqueued by a PROCESS-level subscription (below, before connect()) so a
+// dropped WSS no longer drops events — they drain on reconnect, after the
+// cloud names its watermark via event.resume.
+const BOOT_ID = newId();
+const eventOutbox = new EventOutbox();
+// Transmission is held per-connection until the cloud's event.resume sets the
+// replay cursor (or the fallback timer concedes the cloud predates ADR-103).
+let eventFlushEnabled = false;
+let resumeFallbackTimer: NodeJS.Timeout | null = null;
+const RESUME_FALLBACK_MS = 3_000;
+
+function flushEvents(): void {
+  const socket = ws;
+  if (!eventFlushEnabled || !socket || socket.readyState !== WebSocket.OPEN) {
+    return;
+  }
+  const dropped = eventOutbox.takeDroppedCount();
+  if (dropped > 0) {
+    console.warn(
+      `[host-agent] event outbox overflowed: ${dropped} unsent event(s) lost`,
+    );
+  }
+  for (const entry of eventOutbox.drain()) socket.send(entry.raw);
+}
+
 interface PausableSource {
   pause(): unknown;
   resume(): unknown;
@@ -187,6 +216,13 @@ void ensureStandardImage();
 // self-heals such containers: it re-copies and chowns every running task.
 void recoveryComplete().then(() => reinjectCodexRunningTasks());
 watchCodexAuth();
+// ADR-103: subscribe ONCE, for the process — not per connection. Every event
+// lands in the outbox regardless of socket state; flushEvents is a no-op
+// while disconnected and the backlog drains after the resume handshake.
+hostEvents.subscribe((event) => {
+  eventOutbox.enqueue(event);
+  flushEvents();
+});
 connect();
 // Local browser UI (ADR-028) — same single process, alongside the WSS client.
 // Best-effort: a UI bind failure must not take the host service down.
@@ -234,6 +270,7 @@ function buildCapabilities(): HostCapabilities {
     version: packageVersion(),
     protocolFeatures: [
       TRANSCRIPT_TARGETS_PROTOCOL_FEATURE,
+      EVENT_REPLAY_PROTOCOL_FEATURE,
       GITHUB_CREDENTIAL_GENERATION_PROTOCOL_FEATURE,
       GITHUB_INSTALLATION_VERIFICATION_PROTOCOL_FEATURE,
       GITHUB_REPOSITORY_ACCESS_PROTOCOL_FEATURE,
@@ -275,19 +312,22 @@ function connect(): void {
 
   let lastTraffic = Date.now();
   let ready = false;
-  let unsubscribe: (() => void) | null = null;
   let pingTimer: NodeJS.Timeout | null = null;
   let deadTimer: NodeJS.Timeout | null = null;
 
   const cleanup = (): void => {
     if (pingTimer) clearInterval(pingTimer);
     if (deadTimer) clearInterval(deadTimer);
-    if (unsubscribe) unsubscribe();
+    eventFlushEnabled = false;
+    if (resumeFallbackTimer) {
+      clearTimeout(resumeFallbackTimer);
+      resumeFallbackTimer = null;
+    }
     if (ws === socket) ws = null;
   };
 
   socket.on("open", () => {
-    send(socket, { kind: "auth", token, hostId });
+    send(socket, { kind: "auth", token, hostId, bootId: BOOT_ID });
     // Advertise capabilities immediately after auth (ADR-021). The bridge
     // rejects with close-code 4001 if auth fails, so sending here is harmless
     // on a bad token and saves a round-trip on a good one. Re-sent on every
@@ -303,10 +343,14 @@ function connect(): void {
     setHostObsTag(hostId);
     addHostBreadcrumb("bridge", "connected");
 
-    unsubscribe = hostEvents.subscribe((event) => {
-      if (socket.readyState !== WebSocket.OPEN) return;
-      send(socket, { kind: "event", event });
-    });
+    // ADR-103: hold event transmission until the cloud names its replay
+    // watermark (event.resume). A pre-103 cloud never will — after the
+    // fallback, drain never-transmitted entries only (no replay, no dupes).
+    resumeFallbackTimer = setTimeout(() => {
+      resumeFallbackTimer = null;
+      eventFlushEnabled = true;
+      flushEvents();
+    }, RESUME_FALLBACK_MS);
 
     pingTimer = setInterval(() => {
       if (socket.readyState === WebSocket.OPEN) {
@@ -339,6 +383,20 @@ function connect(): void {
     switch (frame.kind) {
       case "pong":
         break;
+      case "event.resume":
+        // ADR-103: the cloud named its watermark — rewind the transmit
+        // cursor to it (null = no state, replay nothing) and start draining.
+        if (resumeFallbackTimer) {
+          clearTimeout(resumeFallbackTimer);
+          resumeFallbackTimer = null;
+        }
+        eventOutbox.resume(frame.afterSeq);
+        eventFlushEnabled = true;
+        flushEvents();
+        break;
+      case "event.ack":
+        eventOutbox.ack(frame.seq);
+        break;
       case "command":
         void handleCommand(socket, frame);
         break;
@@ -1227,6 +1285,15 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
   if (frame.kind === "pong" && typeof frame.ts === "number") {
     return { kind: "pong", ts: frame.ts };
   }
+  if (
+    frame.kind === "event.resume" &&
+    (frame.afterSeq === null || typeof frame.afterSeq === "number")
+  ) {
+    return { kind: "event.resume", afterSeq: frame.afterSeq };
+  }
+  if (frame.kind === "event.ack" && typeof frame.seq === "number") {
+    return { kind: "event.ack", seq: frame.seq };
+  }
   if (
     frame.kind === "command" &&
     typeof frame.commandId === "string" &&

package/src/protocol.ts

@@ -41,6 +41,11 @@ export const GITHUB_REPOSITORY_ACCESS_PROTOCOL_FEATURE =
   "github-repository-access-v1";
 export const GITHUB_CREDENTIAL_GENERATION_PROTOCOL_FEATURE =
   "github-credential-generation-v1";
+// ADR-103: the host runs an event outbox — seq'd event frames, resume
+// handshake on reconnect, cumulative acks. A cloud seeing this feature knows
+// a disconnect no longer loses events (they replay), so it keeps its
+// in-flight turn buffers across the gap.
+export const EVENT_REPLAY_PROTOCOL_FEATURE = "event-replay-v1";
 export const COMMUNICATOR_EXECUTION_PROFILE = "communicator";
 export const MAX_AGENT_ID_CHARS = 128;
 export const MAX_SECRETARY_DISPATCH_RECIPIENTS = 16;
@@ -603,7 +608,15 @@ export type CloudToHost =
   // discovery, DCR, PKCE, token exchange, encrypted storage. Secrets in a
   // probe (headerValue, clientSecret) are write-only; nothing secret ever
   // rides an ack. `opId` correlates request↔ack.
-  | { kind: "mcp.op"; opId: string; op: McpOp };
+  | { kind: "mcp.op"; opId: string; op: McpOp }
+  // ADR-103: sent once right after auth to a host that supplied a bootId.
+  // `afterSeq` is the cloud's replay watermark for this boot: the host
+  // replays every outbox entry with seq > afterSeq. `null` means the cloud
+  // has no watermark for this boot (fresh boot, or lost KV) — the host sends
+  // only entries it never transmitted, replaying nothing.
+  | { kind: "event.resume"; afterSeq: number | null }
+  // ADR-103: cumulative — the host trims outbox entries with seq <= seq.
+  | { kind: "event.ack"; seq: number };
 
 /** One MCP-connection operation (ADR-057), executed by the host. */
 export type McpOp =
@@ -632,14 +645,19 @@ export type McpOp =
   | { kind: "disconnect"; connectionId: string };
 
 export type HostToCloud =
-  | { kind: "auth"; token: string; hostId: string }
+  // ADR-103: `bootId` scopes event seqs to one host process lifetime — the
+  // cloud's replay watermark only applies within a matching boot. Optional
+  // for pre-103 hosts (which also never send seq'd events).
+  | { kind: "auth"; token: string; hostId: string; bootId?: string }
   | { kind: "host.capabilities"; capabilities: HostCapabilities }
   | {
       kind: "result";
       commandId: string;
       result: HostCommandResult<unknown>;
     }
-  | { kind: "event"; event: HostEvent }
+  // ADR-103: `seq` is the outbox sequence number (monotonic within a bootId).
+  // Absent from pre-103 hosts; the cloud dedups replay overlap by it.
+  | { kind: "event"; event: HostEvent; seq?: number }
   // Host-pushed task lifecycle (ADR-028 local-UI Stop): the host operator paused
   // a task's containers, so the cloud mirrors the status (currently "stopped").
   | { kind: "task.status"; taskId: string; status: string }