@runuai/host 0.9.11 → 0.9.13

package/src/protocol.ts

@@ -35,11 +35,28 @@ export type HostCommandResult<T> =
 export const TRANSCRIPT_TARGETS_PROTOCOL_FEATURE = "transcript-targets-v1";
 export const SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE =
   "secretary-typed-dispatch-v1";
+export const GITHUB_INSTALLATION_VERIFICATION_PROTOCOL_FEATURE =
+  "github-installation-verification-v1";
+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;
 export const MAX_SECRETARY_DISPATCH_INSTRUCTION_CHARS = 8_000;
 export const MAX_SECRETARY_DISPATCH_ID_CHARS = 256;
+// Wire and GitHub-call bounds for the host-assisted authorization snapshot.
+// Exceeding either bound fails the whole verification; a partial installation
+// list could cause destructive pruning, while a partial repository list is an
+// explicit false-negative allowlist and therefore carries `truncated: true`.
+export const MAX_GITHUB_INSTALLATIONS = 100;
+export const MAX_GITHUB_REPOSITORIES_PER_INSTALLATION = 1_000;
 
 export interface CommandContext {
   commandId: string;
@@ -133,6 +150,19 @@ export function parseChannelMode(
   throw new Error("invalid command args: expected channel mode");
 }
 
+/** Optional during rolling upgrades; `null` is the explicit invalid sentinel
+ * so generation zero remains a valid migrated credential generation. */
+export function parseGitHubCredentialGeneration(
+  value: unknown,
+): number | undefined | null {
+  if (value === undefined) return undefined;
+  return typeof value === "number" &&
+    Number.isSafeInteger(value) &&
+    value >= 0
+    ? value
+    : null;
+}
+
 /** Parse the appendTranscript wire argument. `undefined` alone is the legacy
  * three-argument command and maps to chat.md during a rolling deploy. */
 export function parseTranscriptTargets(value: unknown): TranscriptTarget[] {
@@ -468,6 +498,13 @@ export interface TunnelReqLine {
 
 export type TunnelTarget = "editor" | "preview";
 
+export type GitHubRepositoryAccessErrorCode =
+  | "token_missing"
+  | "reauth_required"
+  | "installation_inaccessible"
+  | "github_unavailable"
+  | "invalid_response";
+
 export type CloudToHost =
   | {
       kind: "command";
@@ -506,6 +543,12 @@ export type CloudToHost =
   //                      for short-lived access tokens (host→cloud HTTP POST).
   | {
       kind: "gh.connect.set";
+      /** Correlates the stored credential with the exact host acknowledgement.
+       * Optional only for rolling compatibility with pre-correlation clouds. */
+      opId?: string;
+      /** Monotonic cloud-issued mutation fence. Optional only for rolling
+       * compatibility; generation-aware clouds require the matching feature. */
+      generation?: number;
       userId: string;
       installationId: number;
       githubLogin: string;
@@ -516,7 +559,31 @@ export type CloudToHost =
     }
   // Delete the user's token on the host. ADR-033: the host first POSTs the
   // token to the cloud's /api/github/revoke (kill it at GitHub) before deleting.
-  | { kind: "gh.connect.clear"; userId: string }
+  | {
+      kind: "gh.connect.clear";
+      opId?: string;
+      generation?: number;
+      userId: string;
+    }
+  // Ask the host which installations GitHub currently lists for a user, using
+  // the token the host already holds. Used to prune historical owner
+  // misbindings before any legacy row is trusted.
+  | {
+      kind: "gh.installations.list";
+      opId: string;
+      generation?: number;
+      userId: string;
+    }
+  // Renew one installation's App ∩ user repository allowlist without sending
+  // the user's token to the cloud. Kept separate from installation listing so
+  // ordinary one-row lease renewal is bounded and independently retryable.
+  | {
+      kind: "gh.repositories.list";
+      opId: string;
+      generation?: number;
+      userId: string;
+      installationId: number;
+    }
   // Per-user SSH key lifecycle (ADR-029). Keys are generated + stored on the
   // host; only the public key crosses the bridge (ssh.key.ack). `get` fetches
   // without creating, `ensure` creates-if-absent, `delete` removes.
@@ -541,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 =
@@ -570,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 }
@@ -594,8 +674,45 @@ export type HostToCloud =
   | { kind: "tunnel.data"; tunnelId: string }
   | { kind: "tunnel.close"; tunnelId: string; reason?: string }
   // Ack for gh.connect.set / gh.connect.clear (ADR-027).
-  | { kind: "gh.connect.ack"; userId: string; ok: true }
-  | { kind: "gh.connect.ack"; userId: string; ok: false; error: string }
+  | { kind: "gh.connect.ack"; opId?: string; userId: string; ok: true }
+  | {
+      kind: "gh.connect.ack";
+      opId?: string;
+      userId: string;
+      ok: false;
+      code?: "stale_generation";
+      error: string;
+    }
+  // Ack for gh.installations.list. `installationIds` is GitHub's current
+  // verdict and is authoritative ONLY on ok:true. An error must never be read
+  // as "installed nowhere", which would delete every binding the user has.
+  | {
+      kind: "gh.installations.ack";
+      opId: string;
+      ok: true;
+      installationIds: number[];
+    }
+  | {
+      kind: "gh.installations.ack";
+      opId: string;
+      ok: false;
+      code: GitHubRepositoryAccessErrorCode;
+      error: string;
+    }
+  | {
+      kind: "gh.repositories.ack";
+      opId: string;
+      ok: true;
+      repositoryIds: number[];
+      truncated: boolean;
+    }
+  | {
+      kind: "gh.repositories.ack";
+      opId: string;
+      ok: false;
+      code: GitHubRepositoryAccessErrorCode;
+      error: string;
+    }
   // Ack for ssh.key.get / ssh.key.ensure / ssh.key.delete (ADR-029). publicKey
   // is null when the user has no key (after delete, or a get-miss).
   | { kind: "ssh.key.ack"; userId: string; ok: true; publicKey: string | null }