@runuai/host 0.9.49 → 0.9.50

package/lib/engine-connect.ts

@@ -0,0 +1,221 @@
+/**
+ * ADR-117: one-shot engine connect over the bridge.
+ *
+ * Much simpler than engine-login: nothing is spawned in a container. With a
+ * `secret` this runs the SAME paste paths the local UI's connect uses
+ * (`connectEngine` with pastedToken/apiKey, or the ADR-116 labeled-account
+ * sink); without one it runs OpenCode's re-detect. The secret arrives in the
+ * start frame, goes straight into `connectEngine`/`addEngineAccount`, and is
+ * never logged or echoed into any event.
+ */
+
+import {
+  isEngineAccountLabel,
+  isHostOpId,
+  MAX_ENGINE_CONNECT_LINE_CHARS,
+  MAX_ENGINE_CONNECT_SECRET_CHARS,
+  type EngineConnectEventFrame,
+  type EngineConnectKind,
+} from "../src/protocol";
+import { addEngineAccount } from "./engine-accounts";
+import { connectEngine, type EngineKind } from "./engines";
+
+const CONNECT_TIMEOUT_MS = 2 * 60_000;
+const MAX_CONCURRENT_CONNECTS = 1;
+
+export type EmitEngineConnectEvent = (frame: EngineConnectEventFrame) => void;
+
+export interface EngineConnectManagerOptions {
+  /** Re-advertise capabilities after a successful mutation (main.ts). */
+  readvertise(): void;
+  /** Refresh running agents of a kind after a DEFAULT credential change. */
+  refreshEngineAccountAgents(kind: string): Promise<void>;
+  /** Best-effort post-connect image maintenance (optional engines bake in). */
+  ensureStandardImage(): Promise<unknown>;
+  timers?: {
+    setTimeout(handler: () => void, ms: number): NodeJS.Timeout;
+    clearTimeout(timer: NodeJS.Timeout): void;
+  };
+}
+
+interface ConnectOperation {
+  opId: string;
+  engine: EngineConnectKind;
+  emit: EmitEngineConnectEvent;
+  done: boolean;
+  timer: NodeJS.Timeout | null;
+}
+
+export class EngineConnectManager {
+  private readonly operations = new Map<string, ConnectOperation>();
+
+  constructor(private readonly options: EngineConnectManagerOptions) {}
+
+  start(
+    opId: string,
+    engine: EngineConnectKind,
+    secret: string | undefined,
+    label: string | undefined,
+    emit: EmitEngineConnectEvent,
+  ): boolean {
+    if (!isHostOpId(opId) || this.operations.has(opId)) return false;
+    if (
+      secret !== undefined &&
+      (secret.length < 1 || secret.length > MAX_ENGINE_CONNECT_SECRET_CHARS)
+    ) {
+      return false;
+    }
+    if (label !== undefined && !isEngineAccountLabel(label)) return false;
+    if (this.operations.size >= MAX_CONCURRENT_CONNECTS) {
+      safeEmit(emit, {
+        kind: "engine.connect.event",
+        opId,
+        engine,
+        phase: "done",
+        ok: false,
+        message: "Another engine connect is already in progress.",
+      });
+      return true;
+    }
+    const operation: ConnectOperation = {
+      opId,
+      engine,
+      emit,
+      done: false,
+      timer: null,
+    };
+    this.operations.set(opId, operation);
+    const timers = this.options.timers ?? {
+      setTimeout: (handler: () => void, ms: number) => setTimeout(handler, ms),
+      clearTimeout: (timer: NodeJS.Timeout) => clearTimeout(timer),
+    };
+    operation.timer = timers.setTimeout(() => {
+      this.finish(operation, false, "Engine connect timed out.");
+    }, CONNECT_TIMEOUT_MS);
+    operation.timer.unref?.();
+    void this.run(operation, secret, label).catch((error: unknown) => {
+      this.finish(
+        operation,
+        false,
+        error instanceof Error ? error.message : "Engine connect failed.",
+      );
+    });
+    return true;
+  }
+
+  stop(opId: string): void {
+    const operation = this.operations.get(opId);
+    if (operation) this.finish(operation, false, "Cancelled.");
+  }
+
+  stopAll(): void {
+    for (const operation of [...this.operations.values()]) {
+      this.finish(operation, false, "The connection was replaced.");
+    }
+  }
+
+  private async run(
+    operation: ConnectOperation,
+    secret: string | undefined,
+    label: string | undefined,
+  ): Promise<void> {
+    const { engine } = operation;
+    const emitLine = (line: string): void => {
+      const bounded = line.trim().slice(0, MAX_ENGINE_CONNECT_LINE_CHARS);
+      if (!bounded || operation.done) return;
+      safeEmit(operation.emit, {
+        kind: "engine.connect.event",
+        opId: operation.opId,
+        engine,
+        phase: "line",
+        line: bounded,
+      });
+    };
+
+    if (secret === undefined && engine !== "opencode") {
+      this.finish(
+        operation,
+        false,
+        "This engine needs a credential here, or its sign-in run on the host.",
+      );
+      return;
+    }
+    if (secret !== undefined && engine === "opencode") {
+      // saveApiKey has no opencode branch and would claim success without
+      // storing anything — OpenCode connects on the host, we only re-detect.
+      this.finish(
+        operation,
+        false,
+        "OpenCode signs in on the host (`opencode auth login`); use Check connection here.",
+      );
+      return;
+    }
+
+    // ADR-116 labeled extra account — the sink validates kind support.
+    if (label !== undefined && secret !== undefined) {
+      const added = addEngineAccount(engine, label, { token: secret });
+      if (added.ok) this.afterMutation(engine, false);
+      this.finish(operation, added.ok, added.message);
+      return;
+    }
+
+    const result = await connectEngine(
+      engine as EngineKind,
+      secret === undefined
+        ? {}
+        : engine === "claude"
+          ? { pastedToken: secret }
+          : { apiKey: secret },
+      emitLine,
+    );
+    if (result.ok) this.afterMutation(engine, true);
+    this.finish(operation, result.ok, result.message);
+  }
+
+  /** Mirror the local UI's post-connect behavior (ui/server.ts). */
+  private afterMutation(engine: EngineConnectKind, defaultSlot: boolean): void {
+    this.options.readvertise();
+    void this.options.ensureStandardImage().catch(() => {});
+    if (defaultSlot) {
+      void this.options.refreshEngineAccountAgents(engine).catch(() => {});
+    }
+  }
+
+  private finish(
+    operation: ConnectOperation,
+    ok: boolean,
+    message: string,
+  ): void {
+    if (operation.done) return;
+    operation.done = true;
+    if (operation.timer) {
+      (this.options.timers ?? { clearTimeout }).clearTimeout(operation.timer);
+    }
+    this.operations.delete(operation.opId);
+    safeEmit(operation.emit, {
+      kind: "engine.connect.event",
+      opId: operation.opId,
+      engine: operation.engine,
+      phase: "done",
+      ok,
+      message,
+    });
+  }
+}
+
+function safeEmit(
+  emit: EmitEngineConnectEvent,
+  frame: EngineConnectEventFrame,
+): void {
+  try {
+    emit(frame);
+  } catch {
+    // The bridge socket owns delivery failures.
+  }
+}
+
+export function createEngineConnectManager(
+  options: EngineConnectManagerOptions,
+): EngineConnectManager {
+  return new EngineConnectManager(options);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.49",
+  "version": "0.9.50",
   "description": "Uai host — runs ephemeral AI tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Uai Tech <team@runuai.com>",

package/src/main.ts

@@ -144,7 +144,13 @@ import {
   type HostConfigResult,
 } from "../lib/host-config";
 import { listEngineAccounts } from "../lib/engine-accounts";
+import { createEngineConnectManager } from "../lib/engine-connect";
 import { createEngineLoginManager } from "../lib/engine-login";
+import {
+  engineCatalog,
+  engineCliStatuses,
+  engineStatuses,
+} from "../lib/engines";
 // Importing the real factory triggers the built-in adapters' register()
 // calls (claude, codex), so the registry is populated before we advertise.
 import "../lib/agents/factory";
@@ -166,12 +172,17 @@ import {
   HOST_MAINTENANCE_READINESS_PROTOCOL_FEATURE,
   HOST_CONFIG_PROTOCOL_FEATURE,
   HOST_ENGINE_ACCOUNTS_PROTOCOL_FEATURE,
+  HOST_ENGINE_CONNECT_PROTOCOL_FEATURE,
   HOST_ENGINE_LOGIN_PROTOCOL_FEATURE,
   HOST_LOGS_PROTOCOL_FEATURE,
   HOST_TASK_INVENTORY_PROTOCOL_FEATURE,
   MAX_ENGINE_ACCOUNT_LABEL_CHARS,
   MAX_ENGINE_ACCOUNTS_ADVERTISED,
+  MAX_ENGINE_CATALOG_ENTRIES,
+  isEngineConnectStartFrame,
+  isEngineConnectStopFrame,
   type EngineAccountSummary,
+  type EngineCatalogCapability,
   MAX_HOST_TASK_INVENTORY_PAGE_SIZE,
   MCP_GATEWAY_HEALTH_PROTOCOL_FEATURE,
   SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE,
@@ -268,6 +279,7 @@ function trackRemoteOperationCleanup(cleanup: Promise<void>): Promise<void> {
 
 function stopRemoteOperationManagers(): Promise<void> {
   hostLogManager.stopAll();
+  engineConnectManager.stopAll();
   return trackRemoteOperationCleanup(
     Promise.all([
       engineLoginManager.stopAll(),
@@ -427,6 +439,13 @@ const engineLoginManager = createEngineLoginManager({
   tempRoot: join(env.uaiHome, "engine-login-bind"),
   reconcileOnCreate: false,
 });
+// ADR-117: one-shot connect (pasted key / OpenCode re-detect) over the bridge.
+const engineConnectManager = createEngineConnectManager({
+  readvertise: () => sendCapabilities(),
+  refreshEngineAccountAgents: (engine) =>
+    getOrchestrator().refreshEngineAccountAgents(engine),
+  ensureStandardImage: () => ensureStandardImage(),
+});
 if (initialRuntime.status === "ready") {
   console.log(
     `[host-agent] container runtime ready (${initialRuntime.provider}, ${initialRuntime.preference})`,
@@ -549,6 +568,7 @@ function buildCapabilities(): HostCapabilities {
       HOST_ENGINE_LOGIN_PROTOCOL_FEATURE,
       HOST_CONFIG_PROTOCOL_FEATURE,
       HOST_ENGINE_ACCOUNTS_PROTOCOL_FEATURE,
+      HOST_ENGINE_CONNECT_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.
@@ -565,10 +585,68 @@ function buildCapabilities(): HostCapabilities {
     mcpGateway: mcpGateway.state(),
     engineLogins: engineLoginManager.capabilities(),
     engineAccounts: engineAccountSummaries(),
+    engines: engineCatalogCapabilities(),
     githubUsers: connectedUserIds(),
   };
 }
 
+// engineCliStatuses probes binaries asynchronously; capabilities build
+// synchronously. The snapshot starts empty (cliInstalled: false) and each
+// build kicks a refresh that re-advertises only when the answer changed.
+let cliStatusSnapshot: Partial<Record<string, boolean>> = {};
+let cliStatusRefreshing = false;
+function refreshCliStatusSnapshot(): void {
+  if (cliStatusRefreshing) return;
+  cliStatusRefreshing = true;
+  void engineCliStatuses()
+    .then((next) => {
+      const changed =
+        JSON.stringify(next) !== JSON.stringify(cliStatusSnapshot);
+      cliStatusSnapshot = next;
+      if (changed) sendCapabilities();
+    })
+    .catch(() => {})
+    .finally(() => {
+      cliStatusRefreshing = false;
+    });
+}
+
+/** ADR-117: the full engine catalog for the cloud pane — descriptor metadata
+ * plus live connection/CLI state. The descriptor table stays authoritative. */
+function engineCatalogCapabilities(): EngineCatalogCapability[] {
+  try {
+    const statuses = engineStatuses();
+    const cli = cliStatusSnapshot;
+    refreshCliStatusSnapshot();
+    return engineCatalog()
+      .slice(0, MAX_ENGINE_CATALOG_ENTRIES)
+      .map((entry): EngineCatalogCapability => {
+        const keyUrl = entry.apiKeyUrl ?? entry.getKeyUrl;
+        return {
+          kind: entry.kind,
+          label: entry.label,
+          connected: statuses[entry.kind] === true,
+          cliInstalled: cli[entry.kind] === true,
+          remote:
+            entry.kind === "kimi"
+              ? "none"
+              : entry.authMode === "external-login"
+                ? "detect"
+                : "secret",
+          ...(entry.apiKeyHint !== null ? { hint: entry.apiKeyHint } : {}),
+          ...(keyUrl !== null ? { keyUrl } : {}),
+          notes: entry.notes ?? "",
+          ...(entry.loginCmd !== null ? { loginCmd: entry.loginCmd } : {}),
+        };
+      });
+  } catch (error) {
+    console.warn(
+      `[host-agent] engine catalog for capabilities failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return [];
+  }
+}
+
 /** ADR-116: the labeled-accounts advertisement — bounded, labels-only. */
 function engineAccountSummaries(): EngineAccountSummary[] {
   const summaries: EngineAccountSummary[] = [];
@@ -1118,6 +1196,18 @@ async function connect(): Promise<void> {
           engineLoginManager.stop(frame.opId).then(() => {}),
         );
         break;
+      case "engine.connect.start":
+        engineConnectManager.start(
+          frame.opId,
+          frame.engine,
+          frame.secret,
+          frame.label,
+          (event) => sendRemoteOperationFrame(event),
+        );
+        break;
+      case "engine.connect.stop":
+        engineConnectManager.stop(frame.opId);
+        break;
       case "host.config.get":
         sendHostConfigAck(
           sendRemoteOperationFrame,
@@ -2279,6 +2369,8 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
   if (isEngineLoginInputFrame(frame)) return frame;
   if (isEngineLoginCallbackFrame(frame)) return frame;
   if (isEngineLoginStopFrame(frame)) return frame;
+  if (isEngineConnectStartFrame(frame)) return frame;
+  if (isEngineConnectStopFrame(frame)) return frame;
   if (isHostConfigGetFrame(frame)) return frame;
   if (isHostConfigSetFrame(frame)) return frame;
   if (
@@ -2589,6 +2681,16 @@ function rejectFrameDuringShutdown(
         message: error,
       });
       return true;
+    case "engine.connect.start":
+      send(socket, {
+        kind: "engine.connect.event",
+        opId: frame.opId,
+        engine: frame.engine,
+        phase: "done",
+        ok: false,
+        message: error,
+      });
+      return true;
     case "host.config.get":
     case "host.config.set":
       send(socket, {
@@ -2668,6 +2770,7 @@ function rejectFrameDuringShutdown(
       return true;
     case "host.logs.stop":
     case "engine.login.stop":
+    case "engine.connect.stop":
       // Stops remain idempotent during drain and cannot admit new work.
       return false;
     case "engine.login.input":

package/src/protocol.ts

@@ -92,6 +92,12 @@ export const HOST_CONFIG_PROTOCOL_FEATURE = "host-config-v1";
 export const HOST_ENGINE_ACCOUNTS_PROTOCOL_FEATURE = "host-engine-accounts-v1";
 export const MAX_ENGINE_ACCOUNT_LABEL_CHARS = 64;
 export const MAX_ENGINE_ACCOUNTS_ADVERTISED = 48;
+/** ADR-117: one-shot engine credentials over the bridge + the full engine
+ * catalog in capabilities, so every engine renders on the cloud pane. */
+export const HOST_ENGINE_CONNECT_PROTOCOL_FEATURE = "host-engine-connect-v1";
+export const MAX_ENGINE_CONNECT_SECRET_CHARS = 8_192;
+export const MAX_ENGINE_CONNECT_LINE_CHARS = 512;
+export const MAX_ENGINE_CATALOG_ENTRIES = 8;
 export const MAX_HOST_OP_ID_CHARS = 128;
 export const MAX_HOST_LOG_LINES = 1_000;
 export const MAX_HOST_LOG_LINE_BYTES = 4 * 1_024;
@@ -363,6 +369,143 @@ export interface EngineAccountSummary {
   isDefault: boolean;
 }
 
+/** ADR-117 engine kinds — every engine the host's descriptor table knows. */
+export type EngineConnectKind =
+  | "claude"
+  | "codex"
+  | "kimi"
+  | "grok"
+  | "cursor"
+  | "opencode";
+
+/** ADR-117: one catalog row per engine, advertised in capabilities so the
+ * cloud pane renders every engine from host truth — including the exact
+ * instruction copy for flows that only work on the host itself. */
+export interface EngineCatalogCapability {
+  kind: EngineConnectKind;
+  label: string;
+  connected: boolean;
+  cliInstalled: boolean;
+  /** What the cloud can do remotely: submit a one-shot secret, re-detect a
+   * host-side login, or nothing (instructions only). */
+  remote: "secret" | "detect" | "none";
+  hint?: string;
+  keyUrl?: string;
+  notes: string;
+  loginCmd?: string;
+}
+
+/** ADR-117: start a one-shot connect. `secret` is the operator's pasted
+ * credential — the ONLY frame it ever rides; it is never echoed back,
+ * logged, or persisted cloud-side (ADR-100 amendment). */
+export interface EngineConnectStartFrame {
+  kind: "engine.connect.start";
+  opId: HostOpId;
+  engine: EngineConnectKind;
+  secret?: string;
+  label?: string;
+}
+
+export interface EngineConnectStopFrame {
+  kind: "engine.connect.stop";
+  opId: HostOpId;
+}
+
+/** Secret-blind host→cloud connect progress: sanitized CLI/progress lines,
+ * then exactly one `done`. */
+export interface EngineConnectEventFrame {
+  kind: "engine.connect.event";
+  opId: HostOpId;
+  engine: EngineConnectKind;
+  phase: "line" | "done";
+  line?: string;
+  ok?: boolean;
+  message?: string;
+}
+
+export function isEngineConnectKind(
+  value: unknown,
+): value is EngineConnectKind {
+  return (
+    value === "claude" ||
+    value === "codex" ||
+    value === "kimi" ||
+    value === "grok" ||
+    value === "cursor" ||
+    value === "opencode"
+  );
+}
+
+export function isEngineConnectStartFrame(
+  value: unknown,
+): value is EngineConnectStartFrame {
+  const frame = exactWireObject(
+    value,
+    ["kind", "opId", "engine"],
+    ["secret", "label"],
+  );
+  if (
+    !frame ||
+    frame.kind !== "engine.connect.start" ||
+    !isHostOpId(frame.opId) ||
+    !isEngineConnectKind(frame.engine)
+  ) {
+    return false;
+  }
+  if (frame.secret !== undefined) {
+    if (
+      typeof frame.secret !== "string" ||
+      frame.secret.length < 1 ||
+      frame.secret.length > MAX_ENGINE_CONNECT_SECRET_CHARS
+    ) {
+      return false;
+    }
+  }
+  return frame.label === undefined || isEngineAccountLabel(frame.label);
+}
+
+export function isEngineConnectStopFrame(
+  value: unknown,
+): value is EngineConnectStopFrame {
+  const frame = exactWireObject(value, ["kind", "opId"]);
+  return Boolean(
+    frame && frame.kind === "engine.connect.stop" && isHostOpId(frame.opId),
+  );
+}
+
+export function isEngineConnectEventFrame(
+  value: unknown,
+): value is EngineConnectEventFrame {
+  const frame = exactWireObject(
+    value,
+    ["kind", "opId", "engine", "phase"],
+    ["line", "ok", "message"],
+  );
+  if (
+    !frame ||
+    frame.kind !== "engine.connect.event" ||
+    !isHostOpId(frame.opId) ||
+    !isEngineConnectKind(frame.engine)
+  ) {
+    return false;
+  }
+  if (frame.phase === "line") {
+    return (
+      typeof frame.line === "string" &&
+      frame.line.length >= 1 &&
+      frame.line.length <= MAX_ENGINE_CONNECT_LINE_CHARS &&
+      frame.ok === undefined &&
+      frame.message === undefined
+    );
+  }
+  if (frame.phase !== "done") return false;
+  return (
+    typeof frame.ok === "boolean" &&
+    frame.line === undefined &&
+    (frame.message === undefined || isBoundedMessage(frame.message))
+  );
+}
+
 /** The exact local host settings ADR-100 permits over the bridge. */
 export interface HostConfigState {
   agentCliAutoupdate: boolean;
@@ -803,6 +946,10 @@ export interface HostCapabilities {
   /** ADR-116: labeled engine accounts (default + extras), re-advertised on
    * every account mutation. Labels only — credentials never leave the host. */
   engineAccounts?: EngineAccountSummary[];
+  /** ADR-117: the full engine catalog — connection state plus the metadata
+   * the cloud pane needs to render every engine, including the instruction
+   * copy for host-only sign-in flows. */
+  engines?: EngineCatalogCapability[];
   // ADR-033: cloud user ids that currently have a GitHub token ON THIS HOST —
   // 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.
@@ -1320,6 +1467,8 @@ export type CloudToHost =
   | EngineLoginInputFrame
   | EngineLoginCallbackFrame
   | EngineLoginStopFrame
+  | EngineConnectStartFrame
+  | EngineConnectStopFrame
   | HostConfigGetFrame
   | HostConfigSetFrame
   | {
@@ -1470,6 +1619,7 @@ export type HostToCloud =
   | HostLogsChunkFrame
   | HostLogsEndFrame
   | EngineLoginEventFrame
+  | EngineConnectEventFrame
   | HostConfigAckFrame;
 
 export type HostEvent =