@runuai/host 0.9.169 → 0.9.171

package/src/protocol.ts

@@ -4140,6 +4140,99 @@ export interface HostCapabilities {
   // the per-host gh-connected state shown on the host detail page. Re-advertised
   // whenever a token is added/removed. Optional: older hosts omit it.
   githubUsers?: string[];
+  /** ADR-154 §13: where this runner's switch to cloud credentials stands, and
+   *  what stops it. Optional: hosts before 0.9.171 omit it, and the cloud
+   *  then says only that the runner has not switched. */
+  credentialsSwitch?: CredentialsSwitchCapability;
+}
+
+/**
+ * ADR-154 §13: the runner's switch to cloud credentials, as its capability
+ * frame reports it. `state` is the runner's credentials mode. `stuck` is the
+ * latest substantive refusal or blocker while the switch has not finished:
+ * `by: "cloud"` the cloud's answer, `by: "runner"` something on the machine.
+ * A transient one (the container runtime still preparing after a reconnect,
+ * the bridge down) never replaces a substantive one; it shows only when
+ * there is nothing else to say. Bounded and secret-free: the runner's own log
+ * words (task ids, Compose project names, folder paths with the home
+ * directory as `~`), never a credential.
+ */
+export interface CredentialsSwitchCapability {
+  state: "legacy" | "pending" | "active";
+  stuck?: CredentialsSwitchStuck;
+}
+
+export interface CredentialsSwitchStuck {
+  by: "cloud" | "runner";
+  /** The refusal or blocker in one line. */
+  detail: string;
+  /** Each blocker on its own, when the runner found several. */
+  blockers?: string[];
+  /** The `task-*` Compose projects nothing proves Uai's, which the operator
+   *  removes (`docker compose -p <name> down`) or renames: the first
+   *  `MAX_CREDENTIALS_SWITCH_PROJECTS` names, and how many there are. */
+  composeProjects?: { names: string[]; total: number };
+  /** Nothing is wrong yet: the runner could not look (see above). */
+  transient?: boolean;
+  /** Epoch ms this refusal or blocker was first seen, unchanged since. */
+  since: number;
+}
+
+export const MAX_CREDENTIALS_SWITCH_DETAIL_CHARS = 600;
+export const MAX_CREDENTIALS_SWITCH_BLOCKERS = 20;
+export const MAX_CREDENTIALS_SWITCH_BLOCKER_CHARS = 300;
+export const MAX_CREDENTIALS_SWITCH_PROJECTS = 100;
+
+/** The capability, exact and bounded; undefined when it is not one. The
+ *  cloud drops a malformed one alone, never the frame around it. */
+export function parseCredentialsSwitchCapability(value: unknown): CredentialsSwitchCapability | undefined {
+  if (!isPlainRecord(value)) return undefined;
+  const { state, stuck } = value;
+  if (state !== "legacy" && state !== "pending" && state !== "active") return undefined;
+  if (Object.keys(value).some((key) => key !== "state" && key !== "stuck")) return undefined;
+  if (stuck === undefined) return { state };
+  if (!isPlainRecord(stuck)) return undefined;
+  const allowed = new Set(["by", "detail", "blockers", "composeProjects", "transient", "since"]);
+  if (Object.keys(stuck).some((key) => !allowed.has(key))) return undefined;
+  const boundedText = (text: unknown, max: number): text is string =>
+    typeof text === "string" && text.length >= 1 && text.length <= max;
+  if (stuck.by !== "cloud" && stuck.by !== "runner") return undefined;
+  if (!boundedText(stuck.detail, MAX_CREDENTIALS_SWITCH_DETAIL_CHARS)) return undefined;
+  if (typeof stuck.since !== "number" || !Number.isSafeInteger(stuck.since) || stuck.since < 0) return undefined;
+  if (stuck.transient !== undefined && typeof stuck.transient !== "boolean") return undefined;
+  const out: CredentialsSwitchStuck = { by: stuck.by, detail: stuck.detail, since: stuck.since };
+  if (stuck.blockers !== undefined) {
+    if (
+      !Array.isArray(stuck.blockers) ||
+      stuck.blockers.length > MAX_CREDENTIALS_SWITCH_BLOCKERS ||
+      !stuck.blockers.every((blocker) => boundedText(blocker, MAX_CREDENTIALS_SWITCH_BLOCKER_CHARS))
+    ) {
+      return undefined;
+    }
+    out.blockers = [...stuck.blockers];
+  }
+  if (stuck.composeProjects !== undefined) {
+    const projects = stuck.composeProjects;
+    if (!isPlainRecord(projects) || Object.keys(projects).some((key) => key !== "names" && key !== "total")) return undefined;
+    const { names, total } = projects;
+    if (
+      !Array.isArray(names) ||
+      names.length > MAX_CREDENTIALS_SWITCH_PROJECTS ||
+      !names.every((name) => typeof name === "string" && /^task-[a-z0-9][a-z0-9_-]{0,127}$/.test(name)) ||
+      typeof total !== "number" ||
+      !Number.isSafeInteger(total) ||
+      total < names.length
+    ) {
+      return undefined;
+    }
+    out.composeProjects = { names: [...names] as string[], total };
+  }
+  if (stuck.transient === true) out.transient = true;
+  return { state, stuck: out };
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
 /** One transcript projection the cloud asks the host to append to (ADR-083). */