@runuai/host 0.9.70 → 0.9.72

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

@@ -0,0 +1,333 @@
+/**
+ * ADR-121: the machine-backed task-up adapter.
+ *
+ * Bridges the host's task contract (TaskLaunchInput → TaskUpResult) onto the
+ * pure machine environment provider (MachineTaskInput → descriptor). This is
+ * where task semantics live for machines: project clones happen IN the
+ * machine's world with a one-shot credential over stdin, the task branch is
+ * created off the clone's default HEAD, and repo problems degrade into an
+ * initWarning system note instead of failing the task (a machine with an
+ * empty workspace and a clear message beats a respawn loop).
+ *
+ * Compose-era result fields are satisfied honestly rather than faked:
+ * `composeProject` carries the machine id (the one durable runtime name this
+ * task owns) and `worktreePath` carries the host-side task control dir (the
+ * directory that really does hold this task's host-side state — its machine
+ * key). Consumers that need the workspace go through the environment handle.
+ */
+import type {
+  TaskDownResult,
+  TaskLaunchInput,
+  TaskUpCredentials,
+  TaskUpResult,
+} from "../agent";
+import {
+  MACHINE_TASK_ENVIRONMENT_PROVIDER,
+  parseMachineTaskEnvironmentLocator,
+  type MachineTaskInput,
+} from "./machine";
+import type {
+  TaskEnvironmentDescriptor,
+  TaskEnvironmentHandle,
+  TaskEnvironmentProvider,
+  TaskEnvironmentProvisionRequest,
+  TaskEnvironmentProvisioned,
+} from "./types";
+
+/** In-machine clone budget per project. */
+const CLONE_TIMEOUT_MS = 10 * 60_000;
+const GIT_STEP_TIMEOUT_MS = 60_000;
+const STEP_OUTPUT_BYTES = 256 * 1024;
+
+export interface MachineHostTaskUpDeps {
+  /** The pure machine environment provider (createMachineTaskEnvironmentProvider). */
+  environment: TaskEnvironmentProvider<
+    MachineTaskInput,
+    void,
+    TaskEnvironmentDescriptor
+  >;
+  /** Host-side control dir for the task (holds the machine key). */
+  taskControlDir(taskId: string): string;
+  machineImage(): string;
+  machineCpus(): number;
+  machineMemoryMiB(): number;
+  /** macOS-local machines need loopback-published ssh; cloud machines don't. */
+  publishSsh(): boolean;
+  /** 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>;
+}
+
+/** Mirrors src/index.ts isGithubRepo — host-side predicate only. */
+export function isGithubRepoUrl(input: string): boolean {
+  const value = input.trim();
+  if (/^(?:[^@/]+@)?(?:www\.)?github\.com:/i.test(value)) return true;
+  if (/^[\w.-]+\/[\w.-]+(?:\.git)?\/?$/i.test(value)) return true;
+  try {
+    const url = new URL(value);
+    return /^(?:www\.)?github\.com$/i.test(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/** Canonical HTTPS form for GitHub repos (shorthand and ssh forms included);
+ * non-GitHub URLs pass through untouched. */
+export function machineCloneUrl(repoUrl: string): string {
+  const value = repoUrl.trim();
+  const ssh = /^(?:[^@/]+@)?(?:www\.)?github\.com:(.+)$/i.exec(value);
+  if (ssh?.[1]) {
+    return `https://github.com/${ssh[1].replace(/\.git$/i, "")}.git`;
+  }
+  if (/^[\w.-]+\/[\w.-]+(?:\.git)?\/?$/i.test(value)) {
+    return `https://github.com/${value.replace(/\/+$/, "").replace(/\.git$/i, "")}.git`;
+  }
+  return value;
+}
+
+/** Workspace-safe project directory name. The slug is cloud-normalized, but
+ * the machine path re-checks: a path-capable slug must never reach argv. */
+function projectDirectoryName(slug: string): string {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug) || slug.includes("..")) {
+    throw new Error(`unsafe project slug for machine clone: ${slug}`);
+  }
+  return slug;
+}
+
+interface StepResult {
+  exitCode: number | null;
+  stderr: string;
+}
+
+/** One-shot exec with stdin: spawn, deliver the secret, drain, await exit.
+ * The secret rides the ssh stream only — never argv, never the persisted
+ * env, never machine disk. */
+async function execWithStdin(
+  handle: TaskEnvironmentHandle<unknown>,
+  argv: readonly [string, ...string[]],
+  stdin: string,
+  timeoutMs: number,
+): Promise<StepResult> {
+  const proc = await handle.spawn({
+    argv,
+    inheritEnv: [],
+    env: { GIT_TERMINAL_PROMPT: "0" },
+    timeoutMs,
+    maxOutputBytes: STEP_OUTPUT_BYTES,
+  });
+  let stderr = "";
+  const drainOut = (async () => {
+    for await (const chunk of proc.stdout) {
+      void chunk; // drained; clone progress is not retained
+    }
+  })();
+  const drainErr = (async () => {
+    for await (const chunk of proc.stderr) {
+      stderr = (stderr + Buffer.from(chunk).toString("utf8")).slice(-8192);
+    }
+  })();
+  await proc.write(Buffer.from(stdin));
+  await proc.closeInput();
+  const exit = await proc.completion;
+  await Promise.allSettled([drainOut, drainErr]);
+  return { exitCode: exit.exitCode, stderr: stderr.trim() };
+}
+
+async function execStep(
+  handle: TaskEnvironmentHandle<unknown>,
+  argv: readonly [string, ...string[]],
+  timeoutMs: number,
+): Promise<StepResult> {
+  const result = await handle.exec({
+    argv,
+    env: { GIT_TERMINAL_PROMPT: "0" },
+    timeoutMs,
+    maxOutputBytes: STEP_OUTPUT_BYTES,
+  });
+  return {
+    exitCode: result.exitCode,
+    stderr: Buffer.from(result.stderr).toString("utf8").trim().slice(-8192),
+  };
+}
+
+/** The remote clone script for the credentialed path. The token is read from
+ * stdin into the clone process env; /usr/local/bin/uai-git-askpass (baked in
+ * the machine image) answers git's prompts from it. */
+const CREDENTIALED_CLONE_SCRIPT =
+  'IFS= read -r UAI_GIT_TOKEN && export UAI_GIT_TOKEN GIT_ASKPASS=/usr/local/bin/uai-git-askpass GIT_TERMINAL_PROMPT=0 && exec git clone -- "$1" "$2"';
+
+async function cloneProject(
+  handle: TaskEnvironmentHandle<unknown>,
+  workspacePath: string,
+  project: { slug: string; repoUrl: string },
+  taskBranch: string,
+  owner: { name?: string; email?: string },
+  token: string | null,
+): Promise<string | null> {
+  const destination = `${workspacePath}/${projectDirectoryName(project.slug)}`;
+  const url = machineCloneUrl(project.repoUrl);
+  const useToken = token !== null && isGithubRepoUrl(project.repoUrl);
+
+  // Resume/retry idempotency: a repository that already exists is the task's
+  // live work — never re-clone over it, and leave its branch state alone.
+  const already = await execStep(
+    handle,
+    ["/bin/sh", "-c", 'test -e "$1/.git"', "check", destination],
+    GIT_STEP_TIMEOUT_MS,
+  );
+  if (already.exitCode === 0) return null;
+
+  const clone = useToken
+    ? await execWithStdin(
+        handle,
+        ["/bin/sh", "-c", CREDENTIALED_CLONE_SCRIPT, "clone", url, destination],
+        `${token}\n`,
+        CLONE_TIMEOUT_MS,
+      )
+    : await execStep(
+        handle,
+        ["git", "clone", "--", url, destination],
+        CLONE_TIMEOUT_MS,
+      );
+  if (clone.exitCode !== 0) {
+    return `could not clone ${project.repoUrl} for ${project.slug}: ${clone.stderr || "clone failed"}`;
+  }
+
+  // Task branch off the clone's default HEAD (matches the compose path's
+  // `-b <branch> origin/<default>`). -B keeps an empty-repo clone (unborn
+  // HEAD) and a re-run both working; failure degrades, never fails the task.
+  const branch = await execStep(
+    handle,
+    ["git", "-C", destination, "checkout", "-B", taskBranch],
+    GIT_STEP_TIMEOUT_MS,
+  );
+  if (branch.exitCode !== 0) {
+    return `cloned ${project.slug} but could not create branch ${taskBranch}: ${branch.stderr}`;
+  }
+
+  // Repo-local commit identity so agent commits work out of the box.
+  if (owner.name) {
+    await execStep(
+      handle,
+      ["git", "-C", destination, "config", "user.name", owner.name],
+      GIT_STEP_TIMEOUT_MS,
+    );
+  }
+  if (owner.email) {
+    await execStep(
+      handle,
+      ["git", "-C", destination, "config", "user.email", owner.email],
+      GIT_STEP_TIMEOUT_MS,
+    );
+  }
+  return null;
+}
+
+/** Wrap the void-teardown machine handle so registry consumers get the
+ * TaskDownResult contract the compose providers speak. */
+function withTaskDownResult(
+  handle: TaskEnvironmentHandle<unknown>,
+): TaskEnvironmentHandle<TaskDownResult> {
+  // Explicit delegation, never Object.create: the machine handle is a class
+  // with private fields, and a prototype-borrowed method invoked on a foreign
+  // receiver throws on its first #member access.
+  return {
+    descriptor: handle.descriptor,
+    durableIdentity: handle.durableIdentity,
+    readWorkspaceFile: (path) => handle.readWorkspaceFile(path),
+    writeWorkspaceFile: (path, bytes) => handle.writeWorkspaceFile(path, bytes),
+    exec: (request) => handle.exec(request),
+    spawn: (request) => handle.spawn(request),
+    spawnSession: (request) => handle.spawnSession(request),
+    launchDetachedSession: (request) => handle.launchDetachedSession(request),
+    copy: (request) => handle.copy(request),
+    ports: () => handle.ports(),
+    status: () => handle.status(),
+    recover: (context) => handle.recover(context),
+    stop: () => handle.stop(),
+    teardown: async (): Promise<TaskDownResult> => {
+      await handle.teardown();
+      return { status: "terminated" };
+    },
+  };
+}
+
+export function createMachineHostTaskEnvironmentProvider(
+  deps: MachineHostTaskUpDeps,
+): TaskEnvironmentProvider<
+  TaskLaunchInput,
+  TaskUpCredentials,
+  TaskUpResult,
+  TaskDownResult
+> {
+  return {
+    kind: MACHINE_TASK_ENVIRONMENT_PROVIDER,
+
+    async provision(
+      request: TaskEnvironmentProvisionRequest<TaskLaunchInput, TaskUpCredentials>,
+    ): Promise<TaskEnvironmentProvisioned<TaskUpResult, TaskDownResult>> {
+      const { input } = request;
+      const provisioned = await deps.environment.provision({
+        taskId: request.taskId,
+        input: {
+          image: deps.machineImage(),
+          cpus: deps.machineCpus(),
+          memoryMiB: deps.machineMemoryMiB(),
+          ...(deps.publishSsh() ? { publishSsh: true } : {}),
+        },
+        credentials: undefined,
+        onPrepared: request.onPrepared,
+      });
+      const handle = provisioned.handle;
+      const workspacePath = handle.descriptor.workspacePath;
+      const warnings: string[] = [];
+
+      try {
+        const projects = [...input.projects].sort(
+          (a, b) => a.position - b.position,
+        );
+        const wantsGithub = projects.some((project) =>
+          isGithubRepoUrl(project.repoUrl),
+        );
+        const token = wantsGithub
+          ? await deps.githubToken(input.task.ownerUserId)
+          : null;
+        for (const project of projects) {
+          const warning = await cloneProject(
+            handle,
+            workspacePath,
+            project,
+            input.task.branch,
+            { name: input.ownerName, email: input.ownerEmail },
+            token?.accessToken ?? null,
+          );
+          if (warning) warnings.push(warning);
+        }
+      } catch (error) {
+        // Provisioning-infrastructure failures (ssh died, unsafe slug) tear
+        // the machine down rather than stranding an orphan; per-repo problems
+        // were already converted to warnings above and do not land here.
+        await handle.teardown().catch(() => {});
+        throw error;
+      }
+
+      const machineId = parseMachineTaskEnvironmentLocator(
+        handle.descriptor.locator,
+      ).machineId;
+      return {
+        handle: withTaskDownResult(handle),
+        result: {
+          composeProject: machineId,
+          worktreePath: deps.taskControlDir(request.taskId),
+          ...(warnings.length > 0
+            ? { initWarning: warnings.join("\n") }
+            : {}),
+        },
+      };
+    },
+
+    async reconstruct(locator) {
+      return withTaskDownResult(await deps.environment.reconstruct(locator));
+    },
+  };
+}

package/lib/task-environment/machine.ts

@@ -340,12 +340,18 @@ class MachineTaskEnvironmentHandle implements TaskEnvironmentHandle {
     request: TaskEnvironmentSessionRequest,
   ): Promise<TaskEnvironmentProcess> {
     assertTaskEnvironmentSessionRequest(request);
+    // Sessions default to the workspace the way container images default to
+    // WORKDIR /workspace — an agent CLI must start in the task's world.
+    const sessionRequest = {
+      ...request,
+      cwd: request.cwd ?? this.#value.workspacePath,
+    };
     const target = await this.#target();
     return streamingCliExec(
       this.#deps.spawn,
       "ssh",
-      machineEnvironmentSshArgs(target, request, "interactive"),
-      request,
+      machineEnvironmentSshArgs(target, sessionRequest, "interactive"),
+      sessionRequest,
     );
   }
 
@@ -353,14 +359,18 @@ class MachineTaskEnvironmentHandle implements TaskEnvironmentHandle {
     request: TaskEnvironmentDetachedSessionRequest,
   ): Promise<TaskEnvironmentExecResult> {
     assertTaskEnvironmentSessionRequest(request);
+    const sessionRequest = {
+      ...request,
+      cwd: request.cwd ?? this.#value.workspacePath,
+    };
     const target = await this.#target();
     return capturedCliExec(
       this.#deps.spawn,
       "ssh",
-      machineEnvironmentSshArgs(target, request, "detached"),
+      machineEnvironmentSshArgs(target, sessionRequest, "detached"),
       {
-        ...request,
-        timeoutMs: request.launchTimeoutMs,
+        ...sessionRequest,
+        timeoutMs: sessionRequest.launchTimeoutMs,
       },
     );
   }
@@ -630,23 +640,44 @@ export function createMachineTaskEnvironmentProvider(
       });
       await request.onPrepared?.(locator);
 
-      const launched = await deps.machines.launch({
-        taskId,
-        image: input.image,
-        cpus: input.cpus,
-        memoryMiB: input.memoryMiB,
-        authorizedPublicKey: keys.publicKey,
-        ...(input.publishSsh ? { publishSsh: true } : {}),
-      });
-      if (launched.id !== machineId) {
-        // The backend named the machine something other than what the
-        // durable locator promises — tear it down rather than strand an
-        // untracked machine, then fail the provision loudly.
-        await deps.machines.terminate(launched.id);
+      // Resume-aware launch: a machine may already exist for this task
+      // (host restart mid-provision, task resume after stop). Only a
+      // machine PROVEN to carry this task's ownership label may be reused;
+      // an unlabeled or foreign occupant of the name fails the provision —
+      // it is never adopted and never terminated from here.
+      const existing = await deps.machines.describe(machineId);
+      if (existing.state !== "absent" && existing.taskLabel !== taskId) {
+        throw new Error(
+          `machine name ${machineId} is occupied by a resource not labeled for task ${taskId}`,
+        );
+      }
+      if (existing.state === "unknown") {
         throw new Error(
-          `machine backend named ${launched.id}, locator promised ${machineId}`,
+          `machine ${machineId} state is unknown: ${existing.detail ?? "no detail"}`,
         );
       }
+      if (existing.state === "absent") {
+        const launched = await deps.machines.launch({
+          taskId,
+          image: input.image,
+          cpus: input.cpus,
+          memoryMiB: input.memoryMiB,
+          authorizedPublicKey: keys.publicKey,
+          ...(input.publishSsh ? { publishSsh: true } : {}),
+        });
+        if (launched.id !== machineId) {
+          // The backend named the machine something other than what the
+          // durable locator promises — tear it down rather than strand an
+          // untracked machine, then fail the provision loudly.
+          await deps.machines.terminate(launched.id);
+          throw new Error(
+            `machine backend named ${launched.id}, locator promised ${machineId}`,
+          );
+        }
+      } else if (existing.state === "stopped") {
+        await deps.machines.start(machineId);
+      }
+      // running/pending: fall through to the ssh-readiness proof below.
 
       const handle = new MachineTaskEnvironmentHandle(locator, deps);
       await waitForSsh(handle, deps.readyTimeoutMs ?? 120_000);

package/lib/transcript.ts

@@ -14,6 +14,7 @@ import { resolve } from "node:path";
 
 import { taskWorkspaceDir } from "./env";
 import { rewriteAttachmentRefs } from "./orchestrator";
+import type { TaskEnvironmentHandle } from "./task-environment/types";
 import type { TranscriptTarget } from "../src/protocol";
 
 /** Container path agents are pointed at. */
@@ -26,20 +27,97 @@ const TARGET_FILENAME: Record<TranscriptTarget, string> = {
   "chat-front": "chat-front.md",
 };
 
+function transcriptEntry(author: string, text: string): string | null {
+  // Rewrite cloud attachment URLs to the in-container path so an agent reading
+  // the transcript can open referenced files directly.
+  const body = rewriteAttachmentRefs(text).trim();
+  if (!body) return null;
+  return `## ${author}\n\n${body}\n\n`;
+}
+
 export function appendTranscript(
   taskId: string,
   author: string,
   text: string,
   targets: TranscriptTarget[],
 ): void {
-  // Rewrite cloud attachment URLs to the in-container path so an agent reading
-  // the transcript can open referenced files directly.
-  const body = rewriteAttachmentRefs(text).trim();
-  if (!body) return;
+  const entry = transcriptEntry(author, text);
+  if (entry === null) return;
   const dir = resolve(taskWorkspaceDir(taskId), ".uai");
   mkdirSync(dir, { recursive: true });
-  const entry = `## ${author}\n\n${body}\n\n`;
   for (const target of new Set(targets)) {
     appendFileSync(resolve(dir, TARGET_FILENAME[target]), entry);
   }
 }
+
+// ---------------------------------------------------------------------------
+// ADR-121: environment-side transcript for machine-backed tasks. The
+// workspace lives in the machine's world, so the append travels over the
+// environment transport (entry via stdin). A per-task promise chain
+// preserves message order the way the sync host-FS path did implicitly.
+// ---------------------------------------------------------------------------
+
+const environmentAppendChains = new Map<string, Promise<void>>();
+
+async function appendOneViaEnvironment(
+  environment: TaskEnvironmentHandle<unknown>,
+  target: TranscriptTarget,
+  entry: string,
+): Promise<void> {
+  const path = `${environment.descriptor.workspacePath}/.uai/${TARGET_FILENAME[target]}`;
+  const proc = await environment.spawn({
+    argv: [
+      "/bin/sh",
+      "-c",
+      'mkdir -p "$(dirname "$1")" && cat >> "$1"',
+      "append",
+      path,
+    ],
+    inheritEnv: [],
+    env: {},
+    timeoutMs: 30_000,
+    maxOutputBytes: 8 * 1024,
+  });
+  const drains = [
+    (async () => {
+      for await (const chunk of proc.stdout) void chunk;
+    })(),
+    (async () => {
+      for await (const chunk of proc.stderr) void chunk;
+    })(),
+  ];
+  await proc.write(Buffer.from(entry));
+  await proc.closeInput();
+  const exit = await proc.completion;
+  await Promise.allSettled(drains);
+  if (exit.exitCode !== 0) {
+    throw new Error(`environment transcript append exited ${exit.exitCode}`);
+  }
+}
+
+export function appendTranscriptViaEnvironment(
+  taskId: string,
+  environment: TaskEnvironmentHandle<unknown>,
+  author: string,
+  text: string,
+  targets: TranscriptTarget[],
+): Promise<void> {
+  const entry = transcriptEntry(author, text);
+  if (entry === null) return Promise.resolve();
+  const previous = environmentAppendChains.get(taskId) ?? Promise.resolve();
+  const next = previous
+    .catch(() => {})
+    .then(async () => {
+      for (const target of new Set(targets)) {
+        await appendOneViaEnvironment(environment, target, entry);
+      }
+    });
+  environmentAppendChains.set(taskId, next);
+  // Bound the map: forget the chain once it settles as the latest entry.
+  void next.finally(() => {
+    if (environmentAppendChains.get(taskId) === next) {
+      environmentAppendChains.delete(taskId);
+    }
+  });
+  return next;
+}

package/package.json

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