@runuai/host 0.9.145 → 0.9.147

package/lib/agent-cli.ts

@@ -305,7 +305,22 @@ async function main() {
     case "memory search": {
       const q = pos.join(" ") || flags.q || "";
       const author = flags.as ? "&author=" + encodeURIComponent(flags.as) : "";
-      out((await api("GET", "/api/agent/memory?q=" + encodeURIComponent(q) + author)).memories);
+      const limit = flags.limit ? "&limit=" + encodeURIComponent(String(flags.limit)) : "";
+      const res = await api(
+        "GET",
+        "/api/agent/memory?q=" + encodeURIComponent(q) + author + limit,
+      );
+      out(res.memories);
+      // Truncation goes to stderr so it cannot corrupt piped JSON, and it is
+      // stated rather than implied: recalling across tasks means reading the
+      // WHOLE store, and a short page that says nothing reads as all there is.
+      // NOTE: this file is a template literal. No backticks, no \${} in here.
+      if (res.truncated) {
+        console.error(
+          "uai: showing " + res.memories.length + " of " + res.total +
+            " — re-run with --limit all for every row.",
+        );
+      }
       break;
     }
     case "memory save": {
@@ -453,7 +468,7 @@ async function main() {
         "  uai task list",
         "  uai task create --name <n> --prompt <p> [--projects id,id] [--team id] [--agents handle,handle]",
         '  uai task close --status finished|canceled [--reason "final report"]',
-        "  uai memory search <query>",
+        "  uai memory search <query> [--as handle] [--limit N|all]",
         "  uai memory save <text> [--project id] [--tags a,b]",
         "  uai memory delete <id>",
         "  uai todo list",

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/lib/stopped-task-status-queue.ts

@@ -4,8 +4,21 @@
  * mirror remains the authority at flush time so a later Resume wins over an
  * older queued stop.
  */
+/**
+ * Why the host stopped the task, when the host knows.
+ *
+ * `"manual"` is ADR-028's local-UI Stop — a person at the machine pressed it.
+ * Everything else the host reports through this frame is automatic (writable
+ * -container quarantine during a runtime activation or a shared-volume
+ * repair), and carries no reason. The cloud needs the difference because
+ * ADR-144 lets a collaborator resume a task that stopped on its own but not
+ * one a human deliberately paused, and until now both arrived as the same
+ * three fields.
+ */
+export type StoppedTaskReason = "manual";
+
 export class StoppedTaskStatusQueue {
-  private readonly pending = new Set<string>();
+  private readonly pending = new Map<string, StoppedTaskReason | undefined>();
 
   constructor(
     private readonly statusForTask: (
@@ -13,8 +26,13 @@ export class StoppedTaskStatusQueue {
     ) => string | null | undefined,
   ) {}
 
-  enqueue(taskId: string): void {
-    this.pending.add(taskId);
+  enqueue(taskId: string, reason?: StoppedTaskReason): void {
+    // A reason, once known, STICKS across a re-enqueue. The same task can be
+    // queued twice before a flush — an operator Stop, then a quarantine sweep
+    // that finds its container already down — and the automatic pass arriving
+    // second does not make the human's decision retroactively automatic.
+    // Dropping it would silently hand the task back to every collaborator.
+    this.pending.set(taskId, reason ?? this.pending.get(taskId));
   }
 
   /** A failed taskUp may have stopped a legacy runtime before recreation lost
@@ -35,9 +53,9 @@ export class StoppedTaskStatusQueue {
     return true;
   }
 
-  flush(publish: (taskId: string) => void): void {
-    for (const taskId of [...this.pending]) {
-      if (this.statusForTask(taskId) === "stopped") publish(taskId);
+  flush(publish: (taskId: string, reason?: StoppedTaskReason) => void): void {
+    for (const [taskId, reason] of [...this.pending]) {
+      if (this.statusForTask(taskId) === "stopped") publish(taskId, reason);
       this.pending.delete(taskId);
     }
   }

package/package.json

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

@@ -28,7 +28,10 @@ import {
   getHostTask,
   hasInFlightHostTaskLifecycle,
 } from "../lib/runtime-state";
-import { StoppedTaskStatusQueue } from "../lib/stopped-task-status-queue";
+import {
+  StoppedTaskStatusQueue,
+  type StoppedTaskReason,
+} from "../lib/stopped-task-status-queue";
 import {
   getOrchestrator,
   quarantineWritableRuntimeContainers,
@@ -257,7 +260,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 +641,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) => {
@@ -864,7 +869,11 @@ async function startLocalUi(): Promise<void> {
         invalidateMachineTunnelRoute(taskId);
         try {
           const result = await getOrchestrator().stopTask(taskId);
-          if (result.ok) queueStoppedTaskStatus(taskId);
+          // A PERSON pressed Stop on this machine's own UI — ADR-028. Labelled
+          // as such because the cloud otherwise cannot tell it apart from the
+          // quarantine sweeps below, which reach the bridge through this same
+          // frame, and ADR-144 turns that difference into who may undo it.
+          if (result.ok) queueStoppedTaskStatus(taskId, "manual");
           return result;
         } finally {
           invalidateMachineTunnelRoute(taskId);
@@ -931,7 +940,11 @@ function buildCapabilities(): HostCapabilities {
           },
         }
       : {}),
-    ...(sidecarTaskId() ? { sidecar: { taskId: sidecarTaskId()! } } : {}),
+    ...(sidecarTaskId()
+      ? { sidecar: { taskId: sidecarTaskId()! } }
+      : sidecarPoolMode()
+        ? { sidecar: { pool: true } }
+        : {}),
     maintenanceReady: areAgentClisReady(),
     mcpGateway: mcpGateway.state(),
     engineLogins: engineLoginManager.capabilities(),
@@ -1036,15 +1049,18 @@ function sendCapabilities(): void {
 
 /** Keep a rolling-isolation/local-UI stop from remaining cloud-ghost-running
  * merely because the bridge was between connections at the transition. */
-function queueStoppedTaskStatus(taskId: string): void {
-  pendingRuntimeIsolationStatuses.enqueue(taskId);
+function queueStoppedTaskStatus(
+  taskId: string,
+  reason?: StoppedTaskReason,
+): void {
+  pendingRuntimeIsolationStatuses.enqueue(taskId, reason);
   flushStoppedTaskStatuses();
 }
 
 function flushStoppedTaskStatuses(socket: WebSocket | null = ws): void {
   if (!socket || socket.readyState !== WebSocket.OPEN) return;
-  pendingRuntimeIsolationStatuses.flush((taskId) => {
-    send(socket, { kind: "task.status", taskId, status: "stopped" });
+  pendingRuntimeIsolationStatuses.flush((taskId, reason) => {
+    send(socket, { kind: "task.status", taskId, status: "stopped", reason });
   });
 }
 
@@ -2777,6 +2793,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 +2928,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 +3543,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,
@@ -1802,9 +1812,21 @@ export type HostToCloud =
   // 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 }
+  // Host-pushed task lifecycle: the cloud mirrors the status (currently
+  // "stopped"). TWO different events arrive through this one frame — ADR-028's
+  // local-UI Stop, where the host operator paused the task's containers, and
+  // the automatic writable-container quarantine a runtime activation or
+  // shared-volume repair performs. `reason: "manual"` is the first; its
+  // absence is the second.
+  //
+  // The cloud cannot infer it. ADR-144 lets a collaborator resume a task that
+  // stopped on its own and not one a human deliberately paused, and with both
+  // stops indistinguishable on the wire the deliberate one was reversible by
+  // anyone on the task. OPTIONAL so an older host stays compatible: it sends
+  // no reason, the cloud records none, and that host's operator Stop keeps the
+  // pre-ADR-144 behaviour rather than mislabelling its quarantines as manual
+  // and blocking the recovery path they exist to enable.
+  | { kind: "task.status"; taskId: string; status: string; reason?: string }
   | { kind: "ping"; ts: number }
   // ADR-133: a sidecar asks for (or refreshes) its task-scoped AWS lease.
   | { kind: "lease.request"; opId: string; taskId: string }