@runuai/host 0.9.11 → 0.9.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.11",
+  "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

@@ -25,12 +25,17 @@ import {
 import { getHostTask } from "../lib/runtime-state";
 import { getOrchestrator, recoveryComplete } from "../lib/orchestrator";
 import {
+  claimGithubCredentialGeneration,
   connectedUserIds,
+  GitHubRepositoryAccessError,
   isTransientGithubError,
+  listUserInstallationIds,
+  listUserInstallationRepositoryIds,
   onConnectClear,
   onConnectSet,
   onGithubChange,
   reconcileTaskGitAuth,
+  rollbackClaimedGitHubCredentialSet,
   runGithubConnectionTransition,
   setAuthExpiredHandler,
 } from "../lib/github-tokens";
@@ -77,8 +82,13 @@ 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,
   SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE,
   TRANSCRIPT_TARGETS_PROTOCOL_FEATURE,
   type CloudToHost,
@@ -90,6 +100,7 @@ import {
   type HostCommands,
   type HostToCloud,
   type PermissionDecision,
+  parseGitHubCredentialGeneration,
   parseChannelMode,
   parseTranscriptTargets,
   type TaskAgent,
@@ -140,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;
@@ -178,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.
@@ -225,6 +270,10 @@ 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,
       // The echo adapter cannot execute the in-task CLI. Advertising typed
       // dispatch in mock mode would let the composer create a Secretary that
       // has no way to wake crew.
@@ -263,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
@@ -291,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) {
@@ -327,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;
@@ -353,24 +423,67 @@ function connect(): void {
       case "gh.connect.set": {
         // Account switches fence every host-side Git operation using the old
         // credential before the replacement grant is stored or reinjected.
-        void runGithubConnectionTransition(frame.userId, () =>
-          onConnectSet(frame, {
+        void runGithubConnectionTransition(frame.userId, async () => {
+          const claim = claimGithubCredentialGeneration(
+            frame.userId,
+            frame.generation,
+            "set",
+          );
+          if (!claim) {
+            return {
+              ok: false as const,
+              code: "stale_generation" as const,
+              error: "stale GitHub credential generation",
+            };
+          }
+          const transitionDeps = {
             invalidateCredentials: invalidateTaskGithubGitCredentials,
-            reconcile: (taskId, userId) =>
+            reconcile: (taskId: string, userId: string) =>
               getOrchestrator().runTaskLifecycle(taskId, () =>
                 reconcileTaskGitAuth(taskId, userId),
               ),
-          }),
-        ).then(
+          };
+          let result: Awaited<ReturnType<typeof onConnectSet>>;
+          try {
+            result = await onConnectSet(
+              { ...frame, generation: claim.generation },
+              transitionDeps,
+            );
+          } catch (err) {
+            result = {
+              ok: false,
+              error: err instanceof Error ? err.message : String(err),
+            };
+          }
+          if (!result.ok) {
+            // Storage can succeed before live-task reconciliation fails. Never
+            // emit a negative set ack while that untrusted credential remains
+            // active: persist the same-generation clear tombstone first, then
+            // best-effort scrub/revoke under the same serialized transition.
+            await rollbackClaimedGitHubCredentialSet(
+              frame.userId,
+              claim.generation,
+              transitionDeps,
+            );
+          }
+          return result;
+        }).then(
           (result) =>
             send(
               socket,
               result.ok
-                ? { kind: "gh.connect.ack", userId: frame.userId, ok: true }
+                ? {
+                    kind: "gh.connect.ack",
+                    opId: frame.opId,
+                    userId: frame.userId,
+                    ok: true,
+                  }
                 : {
                     kind: "gh.connect.ack",
+                    opId: frame.opId,
                     userId: frame.userId,
                     ok: false,
+                    code: "code" in result ? result.code : undefined,
                     error: result.error ?? "store failed",
                   },
             ),
@@ -379,6 +492,7 @@ function connect(): void {
             console.warn(`[github] connect.set failed: ${error}`);
             send(socket, {
               kind: "gh.connect.ack",
+              opId: frame.opId,
               userId: frame.userId,
               ok: false,
               error,
@@ -387,31 +501,130 @@ function connect(): void {
         );
         break;
       }
+      case "gh.installations.list": {
+        // Read-only: no token leaves the host, only the installation ids
+        // GitHub attests to for this user. A failure acks ok:false rather
+        // than an empty list — the cloud prunes bindings absent from the
+        // result, and "couldn't ask" must never be read as "installed
+        // nowhere".
+        void listUserInstallationIds(
+          frame.userId,
+          {},
+          frame.generation ?? 0,
+        ).then(
+          (installationIds) =>
+            send(socket, {
+              kind: "gh.installations.ack",
+              opId: frame.opId,
+              ok: true,
+              installationIds,
+            }),
+          (err) => {
+            const error = err instanceof Error ? err.message : String(err);
+            const code =
+              err instanceof GitHubRepositoryAccessError
+                ? err.code
+                : "github_unavailable";
+            console.warn(
+              `[github] installation list failed for ${frame.userId}: ${error}`,
+            );
+            send(socket, {
+              kind: "gh.installations.ack",
+              opId: frame.opId,
+              ok: false,
+              code,
+              error,
+            });
+          },
+        );
+        break;
+      }
+      case "gh.repositories.list": {
+        void listUserInstallationRepositoryIds(
+          frame.userId,
+          frame.installationId,
+          {},
+          frame.generation ?? 0,
+        ).then(
+          ({ repositoryIds, truncated }) =>
+            send(socket, {
+              kind: "gh.repositories.ack",
+              opId: frame.opId,
+              ok: true,
+              repositoryIds,
+              truncated,
+            }),
+          (err) => {
+            const error = err instanceof Error ? err.message : String(err);
+            const code =
+              err instanceof GitHubRepositoryAccessError
+                ? err.code
+                : "github_unavailable";
+            console.warn(
+              `[github] repository list failed for ${frame.userId}/${frame.installationId}: ${error}`,
+            );
+            send(socket, {
+              kind: "gh.repositories.ack",
+              opId: frame.opId,
+              ok: false,
+              code,
+              error,
+            });
+          },
+        );
+        break;
+      }
       case "gh.connect.clear": {
-        // Local deletion happens synchronously inside onConnectClear and the
-        // remote revoke starts immediately in the background. Delay the ack
-        // only for live-container logout + transport transition, so the UI
-        // cannot report Disconnected while a task can still use the old token.
-        void runGithubConnectionTransition(frame.userId, () =>
-          onConnectClear(frame.userId, {
+        // The serialized transition removes the local credential, waits for
+        // best-effort remote revocation, and scrubs live containers before it
+        // acknowledges. That keeps a delayed revoke from racing a later set.
+        void runGithubConnectionTransition(frame.userId, async () => {
+          const claim = claimGithubCredentialGeneration(
+            frame.userId,
+            frame.generation,
+            "clear",
+          );
+          if (!claim) {
+            return {
+              ok: false as const,
+              code: "stale_generation" as const,
+              error: "stale GitHub credential generation",
+            };
+          }
+          await onConnectClear(frame.userId, {
             invalidateCredentials: invalidateTaskGithubGitCredentials,
             reconcile: (taskId, userId) =>
               getOrchestrator().runTaskLifecycle(taskId, () =>
                 reconcileTaskGitAuth(taskId, userId),
               ),
-          }),
-        ).then(
-          () =>
-            send(socket, {
-              kind: "gh.connect.ack",
-              userId: frame.userId,
-              ok: true,
-            }),
+          });
+          return { ok: true as const };
+        }).then(
+          (result) =>
+            send(
+              socket,
+              result.ok
+                ? {
+                    kind: "gh.connect.ack",
+                    opId: frame.opId,
+                    userId: frame.userId,
+                    ok: true,
+                  }
+                : {
+                    kind: "gh.connect.ack",
+                    opId: frame.opId,
+                    userId: frame.userId,
+                    ok: false,
+                    code: result.code,
+                    error: result.error,
+                  },
+            ),
           (err) => {
             const error = err instanceof Error ? err.message : String(err);
             console.warn(`[github] connect.clear failed: ${error}`);
             send(socket, {
               kind: "gh.connect.ack",
+              opId: frame.opId,
               userId: frame.userId,
               ok: false,
               error,
@@ -1072,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" &&
@@ -1127,12 +1349,17 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
     typeof frame.installationId === "number" &&
     typeof frame.githubLogin === "string" &&
     (frame.targetType === "User" || frame.targetType === "Organization") &&
+    (frame.opId === undefined || typeof frame.opId === "string") &&
+    parseGitHubCredentialGeneration(frame.generation) !== null &&
     // Exactly one token kind: accessToken (ADR-033) or refreshToken (ADR-027).
     (typeof frame.accessToken === "string" ||
       typeof frame.refreshToken === "string")
   ) {
     return {
       kind: "gh.connect.set",
+      opId: typeof frame.opId === "string" ? frame.opId : undefined,
+      generation:
+        parseGitHubCredentialGeneration(frame.generation) ?? undefined,
       userId: frame.userId,
       installationId: frame.installationId,
       githubLogin: frame.githubLogin,
@@ -1147,8 +1374,51 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
           : undefined,
     };
   }
-  if (frame.kind === "gh.connect.clear" && typeof frame.userId === "string") {
-    return { kind: "gh.connect.clear", userId: frame.userId };
+  if (
+    frame.kind === "gh.connect.clear" &&
+    typeof frame.userId === "string" &&
+    (frame.opId === undefined || typeof frame.opId === "string") &&
+    parseGitHubCredentialGeneration(frame.generation) !== null
+  ) {
+    return {
+      kind: "gh.connect.clear",
+      opId: typeof frame.opId === "string" ? frame.opId : undefined,
+      generation:
+        parseGitHubCredentialGeneration(frame.generation) ?? undefined,
+      userId: frame.userId,
+    };
+  }
+  if (
+    frame.kind === "gh.installations.list" &&
+    typeof frame.opId === "string" &&
+    typeof frame.userId === "string" &&
+    parseGitHubCredentialGeneration(frame.generation) !== null
+  ) {
+    return {
+      kind: "gh.installations.list",
+      opId: frame.opId,
+      generation:
+        parseGitHubCredentialGeneration(frame.generation) ?? undefined,
+      userId: frame.userId,
+    };
+  }
+  if (
+    frame.kind === "gh.repositories.list" &&
+    typeof frame.opId === "string" &&
+    typeof frame.userId === "string" &&
+    typeof frame.installationId === "number" &&
+    Number.isSafeInteger(frame.installationId) &&
+    frame.installationId > 0 &&
+    parseGitHubCredentialGeneration(frame.generation) !== null
+  ) {
+    return {
+      kind: "gh.repositories.list",
+      opId: frame.opId,
+      generation:
+        parseGitHubCredentialGeneration(frame.generation) ?? undefined,
+      userId: frame.userId,
+      installationId: frame.installationId,
+    };
   }
   if (
     (frame.kind === "ssh.key.get" ||