@runuai/host 0.9.115 → 0.9.117

package/lib/env.ts

@@ -57,6 +57,10 @@ const schema = z.object({
   // ADR-135: the broker Lambda a Uai-operated host invokes for a reactive
   // refresh (name or ARN). Unset = scheduled refreshes only.
   UAI_TOKEN_BROKER_FUNCTION: z.string().min(1).optional(),
+  // Who keeps the standard image and agent CLIs current. `host` (owned hosts):
+  // this process, hourly. `external` (Uai-operated hosts): a cloud job keeps
+  // the payload AMI fresh and this host only reconciles once at start.
+  UAI_IMAGE_MAINTENANCE: z.enum(["host", "external"]).default("host"),
   NODE_ENV: z
     .enum(["development", "production", "test"])
     .default("development"),

package/lib/orchestrator.ts

@@ -135,6 +135,7 @@ import type {
   HostEvent,
 } from "../src/protocol";
 import {
+  type TaskStartStage,
   HOST_ACCOUNT_SCOPE,
   MAX_AGENT_ID_CHARS,
   MAX_SECRETARY_DISPATCH_ID_CHARS,
@@ -455,6 +456,11 @@ export class Orchestrator {
     this.emitHost({ kind: "system.note", taskId, text });
   }
 
+  /** A task-start stage boundary (the launch screen on the task page). */
+  emitTaskStage(taskId: string, stage: TaskStartStage): void {
+    this.emitHost({ kind: "task.stage", taskId, stage, at: Date.now() });
+  }
+
   private emitHost(event: HostEvent): void {
     for (const fn of this.hostSubscribers) {
       try {
@@ -1889,6 +1895,7 @@ export class Orchestrator {
     // which the client caps at 10s (Codex) / 30s (Claude Code). Idempotent
     // and ~0.5s once the build is present; a failure arms its own 60s retry
     // rather than depending on another delivery/ensure to arrive.
+    this.emitTaskStage(channel.taskId, "tools");
     await this.ensureBrowserSetup(
       channel,
       initialRoster.some((a) => a.kind === "codex"),
@@ -1923,6 +1930,7 @@ export class Orchestrator {
       return false;
     }
 
+    this.emitTaskStage(channel.taskId, "agents");
     for (const agent of initialRoster) {
       if (!this.isActiveChannel(channel)) return false;
       // A prior partial start or an independently guarded recovery may already
@@ -1972,6 +1980,7 @@ export class Orchestrator {
     // so it both duplicated the opening turn AND re-injected it on a host
     // restart, making agents redo the first turn mid-task. The persona/mission
     // an agent needs live in the always-on system preamble, so nothing is lost.
+    this.emitTaskStage(channel.taskId, "ready");
     return true;
   }
 

package/lib/standard-image.ts

@@ -1128,21 +1128,54 @@ function markAgentClisReady(): void {
  * `{ ok, error? }` so the caller decides (boot: fire-and-forget; taskUp:
  * surface the reason). Resolves `agentClisReady` on every exit path.
  */
-export function ensureStandardImage(): Promise<StandardImageResult> {
+export function ensureStandardImage(
+  opts: { maxAgeMs?: number } = {},
+): Promise<StandardImageResult> {
+  // A task-up passes maxAgeMs: a pass that succeeded recently for the same
+  // engine configuration is reused instead of spending ~15 s spinning a
+  // maintenance container per task (live 2026-09-09: 16 s of every task
+  // start). The hourly schedule (main.ts) and the boot pass keep it fresh.
+  const engines = configuredOptionalEngines();
+  const key = optionalEngineConfigurationKey(engines);
+  const recent = lastOkByKey.get(key);
+  if (
+    opts.maxAgeMs !== undefined &&
+    recent !== undefined &&
+    Date.now() - recent.at <= opts.maxAgeMs
+  ) {
+    markAgentClisReady();
+    return Promise.resolve(recent.result);
+  }
   // Startup, runtime recovery, and a newly-arrived task can all discover the
   // same daemon transition. One shared volume repair/build must own that
   // window; concurrent maintenance containers can otherwise replace the same
   // CLI shims underneath each other and defeat agentClisReady's fence.
-  const engines = configuredOptionalEngines();
-  return ensureQueue.run(optionalEngineConfigurationKey(engines), () =>
-    ensureStandardImageInner(engines).finally(() => {
-      // Always signal — even a docker-down bail — so agent spawns never hang
-      // waiting on a reconcile that will not happen this boot.
-      markAgentClisReady();
-    }),
+  return ensureQueue.run(key, () =>
+    ensureStandardImageInner(engines)
+      .then((result) => {
+        if (result.ok) lastOkByKey.set(key, { at: Date.now(), result });
+        else lastOkByKey.delete(key);
+        return result;
+      })
+      .finally(() => {
+        // Always signal — even a docker-down bail — so agent spawns never hang
+        // waiting on a reconcile that will not happen this boot.
+        markAgentClisReady();
+      }),
   );
 }
 
+/** Last successful pass per engine configuration (in-process). */
+const lastOkByKey = new Map<string, { at: number; result: StandardImageResult }>();
+
+/** Tests: forget every remembered pass. */
+export function resetStandardImageMemo(): void {
+  lastOkByKey.clear();
+}
+
+/** The owned-host schedule (docs/agent-notes.md, "image maintenance"). */
+export const MAINTENANCE_INTERVAL_MS = 60 * 60_000;
+
 async function ensureStandardImageInner(
   engines: OptionalEngineConfiguration,
 ): Promise<StandardImageResult> {

package/lib/task-environment/index.ts

@@ -128,7 +128,7 @@ registry.register(appleProvider);
 // host) until machine-backing becomes a per-task property.
 // ---------------------------------------------------------------------------
 
-function machineTasksEnabled(): boolean {
+export function machineTasksEnabled(): boolean {
   return process.env.UAI_MACHINE_TASKS === "1";
 }
 

package/package.json

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

@@ -77,6 +77,7 @@ import {
 } from "../lib/container-runtime";
 import { vnodeAdmissionProblem } from "../lib/vnode-pressure";
 import {
+  machineTasksEnabled,
   provisionTaskEnvironment,
   reconstructPersistedTaskEnvironment,
 } from "../lib/task-environment";
@@ -792,7 +793,10 @@ export const hostCommands: HostCommands = {
         // a real build only when missing/stale (Docker is definitely up now, a
         // task just arrived). On a build FAILURE, surface WHY to the cloud (not
         // just the host log — the operator can't read a remote user's machine).
-        const img = await ensureStandardImage();
+        // A pass that succeeded within the hour is reused (2026-09-09: the
+        // re-check cost 16 s of every task start); the hourly schedule in
+        // main.ts and the boot pass keep it fresh.
+        const img = await ensureStandardImage({ maxAgeMs: 60 * 60_000 });
         if (!img.ok) {
           throw new AgentError(
             "STANDARD_IMAGE_UNAVAILABLE",
@@ -815,6 +819,13 @@ export const hostCommands: HostCommands = {
             "GitHub is connected on this host, but Uai could not prepare its credential for Git. Retry the task; if it persists, reconnect GitHub on this host.",
           );
         }
+        // Launch screen: the first stage boundary. A machine-backed task
+        // spends the next minute launching an EC2 instance; a container
+        // task goes straight to preparing its workspace.
+        orchestrator.emitTaskStage(
+          input.task.id,
+          machineTasksEnabled() ? "machine" : "workspace",
+        );
         try {
           const provisioned = gitCredential
             ? await gitCredential.run(() =>

package/src/main.ts

@@ -179,6 +179,7 @@ import {
 import "../lib/agents/factory";
 import {
   areAgentClisReady,
+  MAINTENANCE_INTERVAL_MS,
   configuredOptionalEngines,
   ensureStandardImage,
   onAgentClisReady,
@@ -468,6 +469,17 @@ void reconcileEngineAccountsFromStore({ hostId })
       `[engine-accounts] credential store reconcile failed: ${error instanceof Error ? error.message : String(error)}`,
     );
   });
+// Image + agent-CLI maintenance runs where the compute is owned: an owned
+// host keeps its own image current on an hourly schedule (a task-up reuses
+// the last pass instead of blocking on one); a Uai-operated host sets
+// UAI_IMAGE_MAINTENANCE=external — a cloud job keeps the payload AMI fresh —
+// and reconciles only once, at start.
+if (env.UAI_IMAGE_MAINTENANCE === "host") {
+  const maintenanceTimer = setInterval(() => {
+    void ensureStandardImage().catch(() => undefined);
+  }, MAINTENANCE_INTERVAL_MS);
+  maintenanceTimer.unref?.();
+}
 // ADR-135: one refresher per rotating credential. Owned host → the in-process
 // loop refreshes and re-pushes; Uai-operated host → the broker Lambda
 // refreshes and this host picks up changed parameter versions.

package/src/protocol.ts

@@ -1831,6 +1831,15 @@ export type HostToCloud =
   | EngineConnectEventFrame
   | HostConfigAckFrame;
 
+/** Task start stages, in order (docs/agent-notes.md "task start screen"). The
+ *  host emits them as `task.stage` events while a task comes up; the page
+ *  shows a launch screen instead of the chat until `ready`. */
+export const TASK_START_STAGES = ["machine", "workspace", "tools", "agents", "ready"] as const;
+export type TaskStartStage = (typeof TASK_START_STAGES)[number];
+export function isTaskStartStage(value: unknown): value is TaskStartStage {
+  return (TASK_START_STAGES as readonly unknown[]).includes(value);
+}
+
 export type HostEvent =
   | {
       kind: "task.status_changed";
@@ -1838,6 +1847,7 @@ export type HostEvent =
       from: string;
       to: string;
     }
+  | { kind: "task.stage"; taskId: string; stage: TaskStartStage; at: number }
   | {
       kind: "task.log";
       taskId: string;