@runuai/host 0.9.145 → 0.9.146

package/lib/sidecar-assign.ts

@@ -0,0 +1,49 @@
+/**
+ * The warm-pool claim's host half (docs/machine-warm-pool.md): the cloud's
+ * `sidecarAssign` names the task this pool machine now serves. The task id
+ * is appended to the sidecar unit's EnvironmentFile and the process exits
+ * with ASSIGN_RESTART_EXIT_CODE — systemd (`Restart=on-failure`) brings the
+ * unit back up in plain sidecar mode, the tested runner-restart path.
+ * Rewriting a root-owned file and restarting is deliberately boring: no
+ * runtime re-wiring of boot-time gates, no half-pool half-task states.
+ */
+import { appendFileSync, readFileSync } from "node:fs";
+
+import { sidecarPoolMode } from "./sidecar";
+
+/** Anything but 0 and 3: 0 would not restart the unit, 3 is the lease-denied
+ *  latch (`RestartPreventExitStatus=3`). */
+export const ASSIGN_RESTART_EXIT_CODE = 64;
+const EXIT_DELAY_MS = 500;
+
+export function sidecarEnvFile(): string {
+  return process.env.UAI_SIDECAR_ENV_FILE ?? "/etc/uai/sidecar.env";
+}
+
+export function applySidecarAssign(
+  taskId: string,
+  deps: {
+    envFile?: string;
+    exit?: (code: number) => void;
+    append?: (file: string, text: string) => void;
+    read?: (file: string) => string;
+  } = {},
+): void {
+  if (!sidecarPoolMode()) {
+    throw new Error("not a pool machine (already assigned, or not a sidecar)");
+  }
+  if (!/^[a-z0-9]{1,32}$/i.test(taskId)) throw new Error("invalid task id");
+  const file = deps.envFile ?? sidecarEnvFile();
+  const read = deps.read ?? ((f: string) => readFileSync(f, "utf8"));
+  const current = read(file);
+  if (/^UAI_SIDECAR_TASK=/m.test(current)) {
+    throw new Error("this machine already carries a task assignment");
+  }
+  const append = deps.append ?? ((f: string, text: string) => appendFileSync(f, text));
+  append(file, `UAI_SIDECAR_TASK=${taskId}\n`);
+  // Ack first, then die: the delay lets the command reply flush to the
+  // bridge before the socket goes with the process.
+  const exit = deps.exit ?? ((code: number) => process.exit(code));
+  const timer = setTimeout(() => exit(ASSIGN_RESTART_EXIT_CODE), EXIT_DELAY_MS);
+  timer.unref?.();
+}

package/lib/sidecar.ts

@@ -13,8 +13,19 @@ export function sidecarTaskId(): string | null {
   return value && /^[a-z0-9]{1,32}$/i.test(value) ? value : null;
 }
 
+/**
+ * Warm-pool mode (docs/machine-warm-pool.md): a sidecar with no task yet.
+ * Same machine gates as sidecar mode, no lease (nothing to scope one to);
+ * the process waits for `sidecarAssign` to write `UAI_SIDECAR_TASK` into
+ * the unit env and restart it into plain sidecar mode. Once a task id is
+ * present, pool mode is over — even before the restart lands.
+ */
+export function sidecarPoolMode(): boolean {
+  return process.env.UAI_SIDECAR_POOL === "1" && sidecarTaskId() === null;
+}
+
 export function sidecarMode(): boolean {
-  return sidecarTaskId() !== null;
+  return sidecarTaskId() !== null || sidecarPoolMode();
 }
 
 /**

package/package.json

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

package/src/index.ts

@@ -1459,6 +1459,17 @@ export const hostCommands: HostCommands = {
     }
   },
 
+  async sidecarAssign(ctx, input) {
+    logCommand(ctx, "sidecarAssign", input.taskId);
+    try {
+      const { applySidecarAssign } = await import("../lib/sidecar-assign");
+      applySidecarAssign(input.taskId);
+      return ok(undefined);
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
   async channelInterrupt(ctx, taskId, agentId) {
     logCommand(ctx, "channelInterrupt", taskId, agentId);
     try {

package/src/main.ts

@@ -257,7 +257,7 @@ import {
 } from "./protocol";
 import { isEnvironmentTransportProvider } from "../lib/task-environment/types";
 import { LeaseManager } from "../lib/lease";
-import { markSidecarReady, sidecarMode, sidecarTaskId } from "../lib/sidecar";
+import { markSidecarReady, sidecarMode, sidecarPoolMode, sidecarTaskId } from "../lib/sidecar";
 import {
   purgeDefaultEngineSlots,
   SIGN_IN_BOX_TASK_REFUSAL,
@@ -638,7 +638,9 @@ if (signInBoxMode()) {
  * reconciles and the S3 file mounts run. A denial means the task is no
  * longer ours to run — exit 3 and let the cloud's sweep reclaim the machine.
  */
-const leaseManager: LeaseManager | null = sidecarMode()
+// A POOL-mode sidecar requests no lease: it has no task to scope one to,
+// and the cloud would refuse it anyway (docs/machine-warm-pool.md).
+const leaseManager: LeaseManager | null = sidecarTaskId()
   ? new LeaseManager({
       taskId: sidecarTaskId()!,
       send: (frame) => {
@@ -931,7 +933,11 @@ function buildCapabilities(): HostCapabilities {
           },
         }
       : {}),
-    ...(sidecarTaskId() ? { sidecar: { taskId: sidecarTaskId()! } } : {}),
+    ...(sidecarTaskId()
+      ? { sidecar: { taskId: sidecarTaskId()! } }
+      : sidecarPoolMode()
+        ? { sidecar: { pool: true } }
+        : {}),
     maintenanceReady: areAgentClisReady(),
     mcpGateway: mcpGateway.state(),
     engineLogins: engineLoginManager.capabilities(),
@@ -2777,6 +2783,8 @@ async function dispatchCommand(
       );
     case "filesOp":
       return hostCommands.filesOp(ctx, expectFilesOpInput(args, 0));
+    case "sidecarAssign":
+      return hostCommands.sidecarAssign(ctx, expectSidecarAssignInput(args, 0));
     case "channelInterrupt":
       return hostCommands.channelInterrupt(
         ctx,
@@ -2910,6 +2918,26 @@ function expectEngineAccountRemoveInput(
   };
 }
 
+function expectSidecarAssignInput(
+  args: unknown[],
+  index: number,
+): { hostId: string; taskId: string } {
+  const value = args[index];
+  const hostId = (value as { hostId?: unknown } | null)?.hostId;
+  const taskId = (value as { taskId?: unknown } | null)?.taskId;
+  if (
+    !value ||
+    typeof value !== "object" ||
+    typeof hostId !== "string" ||
+    hostId.length === 0 ||
+    typeof taskId !== "string" ||
+    !/^[a-z0-9]{1,32}$/i.test(taskId)
+  ) {
+    throw new Error(`invalid command args: expected sidecar assignment at ${index}`);
+  }
+  return { hostId, taskId };
+}
+
 function expectNumberArg(args: unknown[], index: number): number {
   const value = args[index];
   if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -3505,6 +3533,7 @@ const HOST_COMMAND_NAMES = {
   attachmentWrite: true,
   attachmentRead: true,
   filesOp: true,
+  sidecarAssign: true,
   channelInterrupt: true,
   appendTranscript: true,
   previewEnsure: true,

package/src/protocol.ts

@@ -1075,8 +1075,10 @@ export interface HostCapabilities {
    * provider/region on the host page and, eventually, per-task backing
    * choice keys off it. */
   /** ADR-133 sidecar mode: this host IS the task's machine — exactly one
-   *  task, no container runtime, tunnels on loopback. */
-  sidecar?: { taskId: string };
+   *  task, no container runtime, tunnels on loopback. A warm-pool machine
+   *  (docs/machine-warm-pool.md) advertises `pool` instead of a task until
+   *  `sidecarAssign` restarts it into task mode. */
+  sidecar?: { taskId?: string; pool?: boolean };
   machineTasks?: {
     provider: string;
     region?: string;
@@ -1550,6 +1552,14 @@ export interface HostCommands {
     ctx: CommandContext,
     input: FilesOpInput,
   ): Promise<HostCommandResult<FilesOpValue>>;
+  /** Warm pool claim (docs/machine-warm-pool.md): tell a POOL-mode sidecar
+   *  which task it now serves. The sidecar writes `UAI_SIDECAR_TASK` into
+   *  its unit env, acks, and restarts into plain sidecar mode; a runner not
+   *  in pool mode refuses. */
+  sidecarAssign(
+    ctx: CommandContext,
+    input: { hostId: string; taskId: string },
+  ): Promise<HostCommandResult<void>>;
   channelInterrupt(
     ctx: CommandContext,
     taskId: string,