@runuai/host 0.9.119 → 0.9.121

package/lib/task-environment/machine-task-up.ts

@@ -67,6 +67,14 @@ export interface MachineHostTaskUpDeps {
   /** The task owner's GitHub access token, or null when GitHub is not
    * connected (public/anonymous clone fallback). */
   githubToken(userId: string): Promise<{ accessToken: string } | null>;
+  /** ADR-133: how this environment gets its shared files. Default = the
+   * point-in-time copy from the host's shared directory (machines over
+   * ssh); the sidecar mounts them from S3 instead. */
+  sharedFiles?: (
+    handle: TaskEnvironmentHandle<unknown>,
+    workspacePath: string,
+    task: { ownerOrgId?: string; ownerUserId: string; sharedFiles?: string },
+  ) => Promise<string | null>;
 }
 
 /** Mirrors src/index.ts isGithubRepo — host-side predicate only. */
@@ -430,6 +438,15 @@ async function ensureCodeServer(
   }
 }
 
+/** The identity the host records for the task's runtime: the machine id for
+ * a machine over ssh (what recovery and orphan sweeps key on), the handle's
+ * durable identity for anything else (sidecar mode: `self:<task>`). */
+function environmentRuntimeIdentity(handle: TaskEnvironmentHandle<unknown>): string {
+  return handle.descriptor.locator.provider === MACHINE_TASK_ENVIRONMENT_PROVIDER
+    ? parseMachineTaskEnvironmentLocator(handle.descriptor.locator).machineId
+    : handle.durableIdentity;
+}
+
 /** Wrap the void-teardown machine handle so registry consumers get the
  * TaskDownResult contract the compose providers speak. */
 function withTaskDownResult(
@@ -477,7 +494,9 @@ export function createMachineHostTaskEnvironmentProvider(
   TaskDownResult
 > {
   return {
-    kind: MACHINE_TASK_ENVIRONMENT_PROVIDER,
+    // The provider kind is whichever environment sits underneath: a machine
+    // over ssh, or this machine in sidecar mode (ADR-133).
+    kind: deps.environment.kind,
 
     async provision(
       request: TaskEnvironmentProvisionRequest<TaskLaunchInput, TaskUpCredentials>,
@@ -528,7 +547,7 @@ export function createMachineHostTaskEnvironmentProvider(
       }
 
       // ADR-062 shared files: point-in-time copy (see copySharedFiles).
-      const sharedWarning = await copySharedFiles(handle, workspacePath, {
+      const sharedWarning = await (deps.sharedFiles ?? copySharedFiles)(handle, workspacePath, {
         ...(input.task.ownerOrgId ? { ownerOrgId: input.task.ownerOrgId } : {}),
         ownerUserId: input.task.ownerUserId,
         ...(input.task.sharedFiles ? { sharedFiles: input.task.sharedFiles } : {}),
@@ -570,13 +589,12 @@ export function createMachineHostTaskEnvironmentProvider(
         );
       });
 
-      const machineId = parseMachineTaskEnvironmentLocator(
-        handle.descriptor.locator,
-      ).machineId;
       return {
         handle: withTaskDownResult(handle),
         result: {
-          composeProject: machineId,
+          // Recorded as the task's runtime identity (the compose-project
+          // column): the machine id over ssh, `self:<task>` in sidecar mode.
+          composeProject: environmentRuntimeIdentity(handle),
           worktreePath: deps.taskControlDir(request.taskId),
           codeServerPort: MACHINE_CODE_SERVER_PORT,
           ...(warnings.length > 0

package/lib/task-environment/self.ts

@@ -0,0 +1,346 @@
+/**
+ * ADR-133 sidecar mode: the task environment IS this machine.
+ *
+ * The runner runs on the task's own EC2 machine (`uai-host run --task`), so
+ * there is no container to exec into and no ssh hop to make: every request
+ * runs as a local child process, as user `node` (the runner itself is root
+ * so it can drop privileges, mount S3, and own the workspace), in the same
+ * shape the machine provider sends over ssh. `machine-task-up.ts` (clone,
+ * editor, browser) and `agents/machine-durable.ts` (durable agent sessions)
+ * take a handle, not a transport, so they run unchanged on top of this one.
+ *
+ * What is deliberately NOT here: launch/stop/terminate. The cloud owns the
+ * machine's lifecycle (hostless-implementation.md §7); `stop` and `teardown`
+ * are no-ops because a parked or closed task ends with the cloud stopping or
+ * terminating the instance this process lives on.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+import { buildRemoteCommand } from "../machine-exec";
+import { capturedCliExec, streamingCliExec } from "./docker";
+import type { MachineTaskInput } from "./machine";
+import {
+  assertTaskEnvironmentProcessRequest,
+  assertTaskEnvironmentSessionRequest,
+  assertWorkspaceScopedPath,
+  type TaskEnvironmentCopyRequest,
+  type TaskEnvironmentDescriptor,
+  type TaskEnvironmentDetachedSessionRequest,
+  type TaskEnvironmentExecRequest,
+  type TaskEnvironmentExecResult,
+  type TaskEnvironmentHandle,
+  type TaskEnvironmentLocator,
+  type TaskEnvironmentPort,
+  type TaskEnvironmentProcess,
+  type TaskEnvironmentProvider,
+  type TaskEnvironmentProvisionRequest,
+  type TaskEnvironmentProvisioned,
+  type TaskEnvironmentRecoveryContext,
+  type TaskEnvironmentRecoveryResult,
+  type TaskEnvironmentSessionRequest,
+  type TaskEnvironmentSpawnRequest,
+  type TaskEnvironmentStatus,
+  TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION,
+} from "./types";
+
+export const SELF_TASK_ENVIRONMENT_PROVIDER = "self";
+
+/** The task user every agent, editor, and shell runs as. */
+export const SELF_TASK_USER = "node";
+
+const SAFE_TASK_ID = /^[a-z0-9]{1,32}$/i;
+
+export interface SelfTaskEnvironmentLocatorValue {
+  taskId: string;
+  /** Absolute workspace path on this machine. */
+  workspacePath: string;
+}
+
+export interface SelfTaskEnvironmentDeps {
+  spawn?: typeof nodeSpawn;
+  /** Whether this process may drop privileges with setpriv (root). Tests and
+   * a non-root dev run keep everything as the current user. */
+  privileged?: () => boolean;
+}
+
+export function selfTaskEnvironmentLocator(
+  value: SelfTaskEnvironmentLocatorValue,
+): TaskEnvironmentLocator {
+  return {
+    schemaVersion: TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION,
+    provider: SELF_TASK_ENVIRONMENT_PROVIDER,
+    value: { taskId: value.taskId, workspacePath: value.workspacePath },
+  };
+}
+
+export function parseSelfTaskEnvironmentLocator(
+  locator: TaskEnvironmentLocator,
+): SelfTaskEnvironmentLocatorValue {
+  if (
+    locator.schemaVersion !== TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION ||
+    locator.provider !== SELF_TASK_ENVIRONMENT_PROVIDER ||
+    typeof locator.value !== "object" ||
+    locator.value === null
+  ) {
+    throw new Error("not a self task environment locator");
+  }
+  const value = locator.value as Record<string, unknown>;
+  if (
+    typeof value.taskId !== "string" ||
+    !SAFE_TASK_ID.test(value.taskId) ||
+    typeof value.workspacePath !== "string" ||
+    !value.workspacePath.startsWith("/") ||
+    value.workspacePath.includes("\0")
+  ) {
+    throw new Error("malformed self task environment locator");
+  }
+  return { taskId: value.taskId, workspacePath: value.workspacePath };
+}
+
+/**
+ * The local command for a request: the same `cd … && exec env … argv` shell
+ * line the machine provider ships over ssh, run through setpriv when this
+ * process is root and the request wants a task user. Values ride argv here
+ * exactly as they ride the ssh command line on a machine task — the machine
+ * is one task's trust domain (machine-exec.ts).
+ */
+export function selfCommand(
+  request: {
+    argv: readonly string[];
+    cwd?: string;
+    user?: string;
+    inheritEnv?: readonly string[];
+    env?: Readonly<Record<string, string>>;
+  },
+  mode: "interactive" | "detached",
+  privileged: boolean,
+): { command: string; args: string[] } {
+  const line = buildRemoteCommand({ ...request, detached: mode === "detached" });
+  const user = request.user ?? SELF_TASK_USER;
+  if (privileged && user !== "root") {
+    return {
+      command: "/usr/bin/setpriv",
+      args: [
+        `--reuid=${user}`,
+        `--regid=${user}`,
+        "--init-groups",
+        "--reset-env",
+        "--",
+        "/bin/sh",
+        "-lc",
+        line,
+      ],
+    };
+  }
+  return { command: "/bin/sh", args: ["-lc", line] };
+}
+
+class SelfTaskEnvironmentHandle implements TaskEnvironmentHandle {
+  readonly descriptor: TaskEnvironmentDescriptor;
+  readonly durableIdentity: string;
+  readonly #value: SelfTaskEnvironmentLocatorValue;
+  readonly #spawn: typeof nodeSpawn;
+  readonly #privileged: () => boolean;
+
+  constructor(locator: TaskEnvironmentLocator, deps: SelfTaskEnvironmentDeps) {
+    this.#value = parseSelfTaskEnvironmentLocator(locator);
+    this.#spawn = deps.spawn ?? nodeSpawn;
+    this.#privileged =
+      deps.privileged ?? (() => typeof process.getuid === "function" && process.getuid() === 0);
+    this.durableIdentity = `self:${this.#value.taskId}`;
+    this.descriptor = {
+      taskId: this.#value.taskId,
+      locator,
+      workspacePath: this.#value.workspacePath,
+    };
+  }
+
+  async readWorkspaceFile(path: string): Promise<Uint8Array | null> {
+    assertWorkspaceScopedPath(this.descriptor, path);
+    try {
+      return new Uint8Array(await readFile(path));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw error;
+    }
+  }
+
+  async writeWorkspaceFile(path: string, bytes: Uint8Array): Promise<void> {
+    assertWorkspaceScopedPath(this.descriptor, path);
+    // Through the task user, so the file is owned like everything else the
+    // agents touch (a root-owned file inside the workspace is a trap).
+    const result = await this.exec({
+      argv: ["/bin/sh", "-c", 'mkdir -p "$(dirname "$1")" && cat > "$1"', "write", path],
+      stdin: bytes,
+      timeoutMs: 120_000,
+      maxOutputBytes: 1024 * 1024,
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `workspace write failed: ${Buffer.from(result.stderr).toString("utf8").trim()}`,
+      );
+    }
+  }
+
+  async exec(request: TaskEnvironmentExecRequest): Promise<TaskEnvironmentExecResult> {
+    assertTaskEnvironmentProcessRequest(request);
+    const { command, args } = selfCommand(request, "interactive", this.#privileged());
+    return capturedCliExec(this.#spawn, command, args, request);
+  }
+
+  async spawn(request: TaskEnvironmentSpawnRequest): Promise<TaskEnvironmentProcess> {
+    assertTaskEnvironmentProcessRequest(request);
+    const { command, args } = selfCommand(request, "interactive", this.#privileged());
+    return streamingCliExec(this.#spawn, command, args, request);
+  }
+
+  async spawnSession(request: TaskEnvironmentSessionRequest): Promise<TaskEnvironmentProcess> {
+    assertTaskEnvironmentSessionRequest(request);
+    const session = { ...request, cwd: request.cwd ?? this.#value.workspacePath };
+    const { command, args } = selfCommand(session, "interactive", this.#privileged());
+    return streamingCliExec(this.#spawn, command, args, session);
+  }
+
+  async launchDetachedSession(
+    request: TaskEnvironmentDetachedSessionRequest,
+  ): Promise<TaskEnvironmentExecResult> {
+    assertTaskEnvironmentSessionRequest(request);
+    const session = { ...request, cwd: request.cwd ?? this.#value.workspacePath };
+    const { command, args } = selfCommand(session, "detached", this.#privileged());
+    return capturedCliExec(this.#spawn, command, args, {
+      ...session,
+      timeoutMs: session.launchTimeoutMs,
+    });
+  }
+
+  async copy(request: TaskEnvironmentCopyRequest): Promise<void> {
+    if (
+      !request.source.startsWith("/") ||
+      !request.destination.startsWith("/") ||
+      request.source.includes("\0") ||
+      request.destination.includes("\0")
+    ) {
+      throw new Error("self copy paths must be absolute and NUL-free");
+    }
+    // Both sides are this machine. `cp -a` keeps directory trees intact
+    // (engine-account homes), and the result is chowned to the task user so
+    // the agents can read what was copied in for them.
+    const script =
+      request.direction === "into"
+        ? 'mkdir -p "$(dirname "$2")" && cp -a "$1" "$2" && chown -R node:node "$2"'
+        : 'mkdir -p "$(dirname "$2")" && cp -a "$1" "$2"';
+    const result = await this.exec({
+      argv: ["/bin/sh", "-c", script, "copy", request.source, request.destination],
+      user: "root",
+      timeoutMs: 5 * 60_000,
+      maxOutputBytes: 64 * 1024,
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `self copy failed: ${Buffer.from(result.stderr).toString("utf8").trim()}`,
+      );
+    }
+  }
+
+  async ports(): Promise<TaskEnvironmentPort[]> {
+    return [];
+  }
+
+  /** Every tunnel dials loopback: the editor and preview servers listen on
+   * this machine, and the runner that answers the tunnel is this process. */
+  async inspectRoute(): Promise<{ kind: "running"; ipv4Address: string }> {
+    return { kind: "running", ipv4Address: "127.0.0.1" };
+  }
+
+  async status(): Promise<TaskEnvironmentStatus> {
+    return {
+      state: "running",
+      instances: [this.durableIdentity],
+      workspacePresent: existsSync(this.#value.workspacePath),
+    };
+  }
+
+  async recover(
+    context: TaskEnvironmentRecoveryContext,
+  ): Promise<TaskEnvironmentRecoveryResult> {
+    await context.maintenanceReady;
+    if (!context.isCurrent()) {
+      return { outcome: "deferred", detail: "runtime generation superseded" };
+    }
+    context.allowConsumers?.();
+    await context.ensureConsumersStarted?.();
+    if (!context.isCurrent()) {
+      await context.quarantineConsumers?.();
+      return { outcome: "deferred", detail: "runtime generation superseded" };
+    }
+    return { outcome: "recovered", status: await this.status() };
+  }
+
+  /** Parking is the cloud stopping this instance; nothing to do locally. */
+  async stop(): Promise<void> {}
+
+  /** Closing is the cloud terminating this instance; the workspace dies
+   * with it. Nothing is deleted here so a close that races a late read (a
+   * final diff, a transcript flush) still finds the files. */
+  async teardown(): Promise<void> {}
+}
+
+export function createSelfTaskEnvironmentProvider(
+  deps: SelfTaskEnvironmentDeps = {},
+): TaskEnvironmentProvider<MachineTaskInput, void, TaskEnvironmentDescriptor> {
+  return {
+    kind: SELF_TASK_ENVIRONMENT_PROVIDER,
+
+    // Takes the machine input shape so `createMachineHostTaskEnvironmentProvider`
+    // can sit on top unchanged; image/cpus/memory describe a machine the cloud
+    // already launched and are ignored here.
+    async provision(
+      request: TaskEnvironmentProvisionRequest<MachineTaskInput, void>,
+    ): Promise<TaskEnvironmentProvisioned<TaskEnvironmentDescriptor>> {
+      const { taskId, input } = request;
+      if (!SAFE_TASK_ID.test(taskId)) {
+        throw new Error("self provisioning refused an unsafe task id");
+      }
+      const workspacePath = input.workspacePath ?? "/workspace";
+      const locator = selfTaskEnvironmentLocator({ taskId, workspacePath });
+      await request.onPrepared?.(locator);
+      const handle = new SelfTaskEnvironmentHandle(locator, deps);
+      const prepare = await handle.exec({
+        argv: ["/bin/sh", "-c", 'mkdir -p "$1" && chown node:node "$1"', "prepare", workspacePath],
+        user: "root",
+        timeoutMs: 30_000,
+        maxOutputBytes: 64 * 1024,
+      });
+      if (prepare.exitCode !== 0) {
+        throw new Error(
+          `workspace preparation failed: ${Buffer.from(prepare.stderr).toString("utf8").trim()}`,
+        );
+      }
+      if (input.repo) {
+        const clone = await handle.exec({
+          argv: [
+            "/usr/bin/git",
+            "clone",
+            ...(input.repo.branch ? ["--branch", input.repo.branch] : []),
+            input.repo.url,
+            workspacePath,
+          ],
+          timeoutMs: 10 * 60_000,
+          maxOutputBytes: 4 * 1024 * 1024,
+        });
+        if (clone.exitCode !== 0) {
+          throw new Error(
+            `clone failed: ${Buffer.from(clone.stderr).toString("utf8").trim()}`,
+          );
+        }
+      }
+      return { handle, result: handle.descriptor };
+    },
+
+    async reconstruct(locator: TaskEnvironmentLocator): Promise<TaskEnvironmentHandle> {
+      return new SelfTaskEnvironmentHandle(locator, deps);
+    },
+  };
+}

package/lib/task-environment/types.ts

@@ -446,3 +446,16 @@ function assertJsonValue(value: unknown, depth: number): void {
   }
   throw new Error("task environment locator is not JSON-serializable");
 }
+
+/**
+ * Providers whose workspace is reached only through the environment
+ * transport — a machine over ssh (ADR-121) or this very machine in sidecar
+ * mode (ADR-133) — as opposed to a container the host can `docker exec` into
+ * or bind-mount. Every "is this a machine task?" branch in the host means
+ * exactly this, so it asks here rather than comparing one provider name.
+ */
+export function isEnvironmentTransportProvider(
+  provider: string | null | undefined,
+): boolean {
+  return provider === "machine" || provider === "self";
+}

package/package.json

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

package/src/cli.ts

@@ -132,7 +132,7 @@ async function main(): Promise<void> {
   const follow = rest.includes("--follow") || rest.includes("-f");
   switch (cmd) {
     case "run":
-      return cmdRun();
+      return cmdRun(rest);
     case "status":
       return cmdStatus();
     case "open":
@@ -190,7 +190,12 @@ function timestampServiceLogs(): void {
   }
 }
 
-async function cmdRun(): Promise<void> {
+async function cmdRun(rest: string[] = []): Promise<void> {
+  // ADR-133 sidecar mode: `uai-host run --task <id>` on the task's own
+  // machine. The flag becomes the environment the rest of the process asks
+  // (lib/sidecar.ts) — set before main.ts loads, since its boot reads it.
+  const sidecarTask = flagValue(rest, "--task");
+  if (sidecarTask) process.env.UAI_SIDECAR_TASK = sidecarTask;
   // Timestamped service logs: the ADR-106 live smoke burned an hour dating
   // undated scrollback. Applies to the service process only, not one-shot CLI
   // commands.

package/src/index.ts

@@ -184,6 +184,7 @@ export type {
   PreviewPortDeclaration,
   PreviewPortRuntime,
 } from "../lib/preview-ports";
+import { isEnvironmentTransportProvider } from "../lib/task-environment/types";
 
 export const hostEvents: HostEventStream = {
   subscribe(handler) {
@@ -479,7 +480,7 @@ export const hostCommands: HostCommands = {
         }
       } else if (
         existingTask?.statusMirror === "running" &&
-        existingTask.environmentProvider === "machine"
+        isEnvironmentTransportProvider(existingTask.environmentProvider)
       ) {
         // ADR-121: a machine-backed task revalidates through its own
         // provider — the compose fast path below speaks docker and would
@@ -894,7 +895,7 @@ export const hostCommands: HostCommands = {
         // the compose reconciler would probe for an app container, find none,
         // and silently skip. Reconnect re-injection for machines is a
         // follow-up alongside the machine recovery pass.
-        if (getHostTask(input.task.id)?.environmentProvider === "machine") {
+        if (isEnvironmentTransportProvider(getHostTask(input.task.id)?.environmentProvider)) {
           void machineTaskGithubAuth(
             input.task.id,
             input.task.ownerUserId,
@@ -1005,7 +1006,7 @@ export const hostCommands: HostCommands = {
         // with no consumer (owner, 2026-08-29 — 16 parked disks after one
         // evening of testing). The task branch lives on the remote; the
         // machine's disk is not a preservation surface once the task ends.
-        if (environment.descriptor.locator.provider === "machine") {
+        if (isEnvironmentTransportProvider(environment.descriptor.locator.provider)) {
           stopMachineGatewayTunnel(input.taskId);
         }
         return taskDownResultForInput(input, await environment.teardown());
@@ -1437,7 +1438,7 @@ export const hostCommands: HostCommands = {
       // tasks keep the direct host-FS write (their workspace is a bind
       // mount and the sync path is cheaper than a docker exec per message).
       const task = getHostTask(taskId);
-      if (task?.environmentProvider === "machine") {
+      if (isEnvironmentTransportProvider(task?.environmentProvider)) {
         const environment = await reconstructHostTaskEnvironment(taskId);
         if (environment) {
           await appendTranscriptViaEnvironment(