@runuai/host 0.1.0

package/images/standard/container/code-server-settings.json

@@ -0,0 +1,36 @@
+{
+  "//": "uai — slimmed code-server defaults. Seeded into the User settings",
+  "//2": "dir by uai-init when none exists yet. Trims welcome/telemetry/chat",
+  "//3": "chrome so the Editor pane is a focused editor, not a full AI-IDE.",
+
+  "telemetry.telemetryLevel": "off",
+  "workbench.startupEditor": "none",
+  "workbench.tips.enabled": false,
+  "workbench.welcomePage.walkthroughs.openOnInstall": false,
+  "window.commandCenter": false,
+  "chat.commandCenter.enabled": false,
+  "update.mode": "none",
+  "extensions.autoCheckUpdates": false,
+  "extensions.autoUpdate": false,
+  "git.openRepositoryInParentFolders": "always",
+  "workbench.activityBar.location": "top",
+  "chat.viewSessions.enabled": false,
+  "workbench.secondarySideBar.defaultVisibility": "hidden",
+  "workbench.colorTheme": "Dark 2026",
+
+  "//4": "Workspace Trust — every task runs in an isolated container off the",
+  "//5": "user's own repos. The 'do you trust this folder?' prompt is pure",
+  "//6": "friction here; the user already trusts their code and the container",
+  "//7": "is the security boundary.",
+  "security.workspace.trust.enabled": false,
+
+  "//8": "Port forwarding — code-server's own auto-forward / 'Open in Browser'",
+  "//9": "popup can't reach anything useful here: dev servers are exposed",
+  "//10": "through uai's preview tunnel (ADR-025), not code-server's forwarder.",
+  "//11": "Disable it so the popup doesn't mislead.",
+  "remote.autoForwardPorts": false,
+  "remote.restoreForwardedPorts": false,
+
+  "//12": "Integrated terminal uses zsh + oh-my-zsh (the node login shell).",
+  "terminal.integrated.defaultProfile.linux": "zsh"
+}

package/images/standard/container/uai-init

@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+# uai-init — prepare a standard-image task container (ADR-022).
+#
+# Runs INSIDE the container (Linux, bash 5 — may use anything). Invoked by
+# the host via `docker exec <app> /usr/local/bin/uai-init` after compose up.
+# Spec: ../../../docs/runtime.md §uai-init.
+#
+# Workspace layout (ADR-022): /workspace/<project-slug>/ — one git worktree
+# per selected project. A 0-project (scratchpad) task has an empty /workspace.
+#
+# Responsibilities:
+#   1. For each /workspace/<slug>/ that carries a .tool-versions: `asdf
+#      install` (downloads cached on the host-wide /opt/asdf-data volume),
+#      then a dependency-install heuristic for the folder's stack.
+#   2. Launch code-server on 0.0.0.0:8080 (auth disabled — reached only via
+#      the authenticated tunnel), opening /workspace.
+#
+# Best-effort + idempotent: a failing folder logs and is skipped; it never
+# aborts the whole init. Re-running when things are already up is a no-op.
+# uai-init itself always exits 0 so task-up's `docker exec ... uai-init` step
+# succeeds as long as the container is reachable.
+
+set -uo pipefail
+
+WORKSPACE="${UAI_WORKSPACE:-/workspace}"
+ASDF_SH="${ASDF_DIR:-/opt/asdf}/asdf.sh"
+
+log() { echo "uai-init: $*"; }
+
+# Make asdf + its shims available to this non-interactive shell. A bare
+# `docker exec` sources no profile, so source asdf explicitly here.
+if [ -f "$ASDF_SH" ]; then
+  # shellcheck disable=SC1090
+  . "$ASDF_SH"
+else
+  log "warning: asdf not found at $ASDF_SH; runtime install will be skipped"
+fi
+
+# ---------------------------------------------------------------------------
+# 0. GitHub auth for in-container git (ADR-027). git rides the host's uai SSH
+#    identity (docker-cp'd to ~/.ssh, registered on GitHub for auth + signing),
+#    NOT an HTTPS token. Route every GitHub remote — including https:// ones —
+#    over SSH so a project's clone scheme doesn't matter, and trust github's
+#    host key non-interactively so a fresh container's first push doesn't stall
+#    on a prompt. `gh` is separate: it authenticates from its own config file,
+#    which the host writes via `gh auth login --with-token` with the user's
+#    short-lived token. We must NOT set GH_TOKEN in the env — `gh` would prefer
+#    it over that stored credential (and re-attribute every PR to it).
+# ---------------------------------------------------------------------------
+
+if [ -f "$HOME/.ssh/id_ed25519" ]; then
+  log "routing git GitHub remotes over the uai SSH identity"
+  git config --global url."git@github.com:".insteadOf "https://github.com/"
+  git config --global core.sshCommand "ssh -o StrictHostKeyChecking=accept-new"
+fi
+
+# Signed commits (policy): when the uai SSH identity is present, configure git
+# to SSH-sign every commit + tag with it. The pubkey is registered on GitHub
+# (via `setup-identity`) so commits show as Verified. The same key also carries
+# git push over SSH (configured above).
+if [ -f "$HOME/.ssh/id_ed25519.pub" ]; then
+  log "enabling SSH commit signing with the uai identity"
+  git config --global gpg.format ssh
+  git config --global user.signingkey "$HOME/.ssh/id_ed25519.pub"
+  git config --global commit.gpgsign true
+  git config --global tag.gpgsign true
+fi
+
+# Attribution policy: never co-author with the agents. Claude Code honors
+# `includeCoAuthoredBy: false` (drops the "Co-Authored-By: Claude" commit
+# trailer and the "Generated with Claude Code" PR footer). Seed it into the
+# per-task Claude user settings if absent. Codex is covered by the
+# orchestrator's system preamble.
+cc_settings="$HOME/.claude/settings.json"
+if [ ! -f "$cc_settings" ]; then
+  mkdir -p "$HOME/.claude"
+  printf '{\n  "includeCoAuthoredBy": false\n}\n' > "$cc_settings"
+  log "seeded ~/.claude/settings.json (includeCoAuthoredBy: false)"
+fi
+
+# ---------------------------------------------------------------------------
+# 1. Per-folder runtime + dependency install.
+# ---------------------------------------------------------------------------
+
+install_node_deps() {
+  # Pick the package manager from the packageManager field, else a lockfile,
+  # else npm. corepack provisions pnpm/yarn from the packageManager field.
+  local pm=""
+  if [ -f package.json ]; then
+    pm=$(jq -r '.packageManager // ""' package.json 2>/dev/null | sed 's/@.*//')
+  fi
+  if [ -z "$pm" ]; then
+    if [ -f pnpm-lock.yaml ]; then pm="pnpm"
+    elif [ -f yarn.lock ]; then pm="yarn"
+    elif [ -f package-lock.json ] || [ -f npm-shrinkwrap.json ]; then pm="npm"
+    elif [ -f bun.lockb ] || [ -f bun.lock ]; then pm="bun"
+    else pm="npm"
+    fi
+  fi
+
+  # corepack ships with Node and resolves pnpm/yarn per the packageManager
+  # field; harmless no-op when already enabled.
+  corepack enable >/dev/null 2>&1 || true
+
+  case "$pm" in
+    pnpm) log "pnpm install"; pnpm install ;;
+    yarn) log "yarn install"; yarn install ;;
+    bun)  log "bun install";  bun install ;;
+    *)    log "npm install";  npm install --no-audit --no-fund ;;
+  esac
+}
+
+install_python_deps() {
+  # uv handles both requirements.txt and pyproject.toml; create a project .venv
+  # so the install is isolated to the folder. Pin uv to ASDF's Python (the
+  # version asdf just resolved from the in-scope .tool-versions) so the venv
+  # matches the project's declared runtime. uv otherwise selects via
+  # .python-version / requires-python, which can disagree with .tool-versions
+  # (or be junk, e.g. a stray pyenv-virtualenv name) — asdf is the authority.
+  local py
+  py="$(asdf which python 2>/dev/null || true)"
+  if [ -f pyproject.toml ]; then
+    log "uv sync (pyproject.toml)${py:+ — asdf python $py}"
+    if [ -n "$py" ]; then uv sync --python "$py"; else uv sync; fi
+  elif [ -f requirements.txt ]; then
+    log "uv venv + pip install -r requirements.txt${py:+ — asdf python $py}"
+    if [ -n "$py" ]; then uv venv --python "$py"; else uv venv; fi \
+      && uv pip install -r requirements.txt
+  fi
+}
+
+install_folder() {
+  local dir="$1" name
+  name=$(basename "$dir")
+
+  # Enter the folder; asdf auto-resolves the nearest .tool-versions here.
+  cd "$dir" || { log "cannot cd into $name — skipping"; return; }
+
+  # Runtime install. asdf reads the in-scope .tool-versions and downloads any
+  # missing versions (cached on the /opt/asdf-data volume).
+  if command -v asdf >/dev/null 2>&1; then
+    log "asdf install ($name)"
+    asdf install || log "asdf install failed in $name — continuing"
+  fi
+
+  # Dependency-install heuristic. Run every matcher that applies (a polyglot
+  # folder may have more than one); each is independently best-effort.
+  if [ -f package.json ]; then
+    install_node_deps || log "node deps failed in $name — continuing"
+  fi
+  if [ -f pyproject.toml ] || [ -f requirements.txt ]; then
+    install_python_deps || log "python deps failed in $name — continuing"
+  fi
+  if [ -f Cargo.toml ]; then
+    log "cargo build ($name)"
+    cargo build || log "cargo build failed in $name — continuing"
+  fi
+  if [ -f go.mod ]; then
+    log "go mod download ($name)"
+    go mod download || log "go mod download failed in $name — continuing"
+  fi
+}
+
+if [ -d "$WORKSPACE" ]; then
+  shopt -s nullglob
+  for folder in "$WORKSPACE"/*/; do
+    [ -d "$folder" ] || continue
+    if [ -f "${folder}.tool-versions" ]; then
+      # Run in a subshell so a `cd` (or a failing command under the relaxed
+      # error mode) in one folder never leaks into the next.
+      ( install_folder "$folder" )
+    else
+      log "no .tool-versions in $(basename "$folder") — skipping per-folder install"
+    fi
+  done
+  shopt -u nullglob
+else
+  log "workspace $WORKSPACE missing — scratchpad/no-project task, skipping installs"
+fi
+
+# ---------------------------------------------------------------------------
+# 2. code-server — the Editor pane. Bound to 0.0.0.0:8080, auth disabled
+#    (reached only through the authenticated tunnel / editor proxy). Opens
+#    /workspace so all worktrees are visible at the top level. Idempotent:
+#    skips launch if already running.
+# ---------------------------------------------------------------------------
+
+editor_root="$WORKSPACE"
+[ -d "$editor_root" ] || editor_root="/home/node"
+
+# Seed the curated code-server defaults (slim chrome, telemetry off, trust
+# off) into the User settings dir when the task hasn't written its own yet.
+cs_user_dir="$HOME/.local/share/code-server/User"
+cs_seed="/usr/local/share/uai/code-server-settings.json"
+if [ -f "$cs_seed" ] && [ ! -f "$cs_user_dir/settings.json" ]; then
+  mkdir -p "$cs_user_dir"
+  cp "$cs_seed" "$cs_user_dir/settings.json"
+  log "seeded code-server settings"
+fi
+
+if pgrep -f 'code-server.*--bind-addr' >/dev/null 2>&1; then
+  log "code-server already running"
+else
+  log "launching code-server on 0.0.0.0:8080"
+  nohup code-server \
+    --auth none \
+    --disable-telemetry \
+    --bind-addr 0.0.0.0:8080 \
+    "$editor_root" \
+    >/tmp/code-server.log 2>&1 &
+  disown
+fi
+
+# Always succeed: the container is up and code-server has been (re)launched.
+exit 0

package/images/standard/tool-versions

@@ -0,0 +1,2 @@
+nodejs 22.11.0
+python 3.12.4

package/lib/agent.ts

@@ -0,0 +1,292 @@
+/**
+ * Typed wrapper around the host-agent shell scripts.
+ *
+ * The agent's wire contract (docs/agent.md):
+ *   success → stdout: { ok: true, data: ... }
+ *   failure → stderr: { ok: false, error: { code, message, step?, exit_code? } }
+ *   non-zero exit on failure.
+ *
+ * This module shells out to scripts/agent/*.sh (or UAI_AGENT_DIR/*.sh in
+ * production), pipes UAI_DB_PATH + UAI_DATA_DIR into the child, parses
+ * the JSON, and returns typed result objects — or throws AgentError.
+ *
+ * Same-process for MVP (per ADR-004). When uai is extracted to a hosted
+ * product, this module becomes a JSON-RPC client over a websocket; the
+ * surface stays the same.
+ */
+
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+
+import {
+  createTaskDownCommandDb,
+  createTaskStatusCommandDb,
+  createTaskUpCommandDb,
+  removeCommandDb,
+} from "./command-db";
+import { env } from "./env";
+import { PreviewPortRuntimesSchema } from "./preview-ports";
+import { getHostTask } from "./runtime-state";
+import { removeTaskIdentity, writeTaskIdentity } from "./ssh";
+import type { TaskDownInput, TaskLaunchInput } from "../src/protocol";
+
+// ---------------------------------------------------------------------------
+// Locate the agent scripts. They ship inside the package, so by default we
+// resolve them relative to this module — which works identically in a repo
+// checkout (host-agent/scripts/agent) and an npm install
+// (node_modules/@runuai/host/scripts/agent). An explicit UAI_AGENT_DIR
+// overrides this (e.g. hacking on scripts against a running host).
+// ---------------------------------------------------------------------------
+
+function packageAgentScriptsDir(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..", "scripts", "agent");
+}
+
+function agentDir(): string {
+  return env.agentDir ?? packageAgentScriptsDir();
+}
+
+// ---------------------------------------------------------------------------
+// Result schemas. Each command shares the success envelope and produces a
+// command-specific `data` payload.
+// ---------------------------------------------------------------------------
+
+const ErrorPayload = z.object({
+  code: z.string(),
+  message: z.string(),
+  step: z.string().optional(),
+  exit_code: z.number().optional(),
+});
+
+const SuccessEnvelope = <T extends z.ZodTypeAny>(data: T) =>
+  z.object({ ok: z.literal(true), data });
+
+const FailureEnvelope = z.object({
+  ok: z.literal(false),
+  error: ErrorPayload,
+});
+
+// task-up
+const TaskUpData = z.object({
+  composeProject: z.string(),
+  worktreePath: z.string(),
+  codeServerPort: z.number().int().positive().optional(),
+  previewPorts: PreviewPortRuntimesSchema.optional(),
+});
+export type TaskUpResult = z.infer<typeof TaskUpData>;
+
+// task-down
+const TaskDownData = z
+  .object({
+    status: z.string().optional(),
+    alreadyGone: z.boolean().optional(),
+  })
+  .passthrough();
+export type TaskDownResult = z.infer<typeof TaskDownData>;
+
+// task-status
+const TaskStatusData = z.object({
+  composeRunning: z.boolean(),
+  containers: z.array(z.string()),
+  worktreePresent: z.boolean(),
+});
+export type TaskStatusResult = z.infer<typeof TaskStatusData>;
+
+// ---------------------------------------------------------------------------
+// Error type. All call sites should `catch (err)` and use `AgentError.is`.
+// ---------------------------------------------------------------------------
+
+export class AgentError extends Error {
+  override readonly name = "AgentError";
+  readonly code: string;
+  readonly step: string | undefined;
+  readonly exitCode: number | undefined;
+
+  constructor(
+    code: string,
+    message: string,
+    options: { step?: string; exitCode?: number; cause?: unknown } = {},
+  ) {
+    super(
+      message,
+      options.cause === undefined ? undefined : { cause: options.cause },
+    );
+    this.code = code;
+    this.step = options.step;
+    this.exitCode = options.exitCode;
+  }
+
+  static is(err: unknown): err is AgentError {
+    return err instanceof AgentError;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal: run an agent script and parse the JSON envelope.
+// ---------------------------------------------------------------------------
+
+async function runAgent<T extends z.ZodTypeAny>(
+  scriptName: string,
+  args: string[],
+  dataSchema: T,
+  commandDbPath: string,
+  extraEnv: Record<string, string> = {},
+): Promise<z.infer<T>> {
+  const scriptPath = resolve(agentDir(), scriptName);
+
+  const child = spawn(scriptPath, args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    env: {
+      ...process.env,
+      UAI_DB_PATH: commandDbPath,
+      UAI_DATA_DIR: env.dataDir,
+      ...extraEnv,
+    },
+  });
+
+  let stdoutBuf = "";
+  let stderrBuf = "";
+  child.stdout.on("data", (chunk) => {
+    stdoutBuf += chunk.toString("utf8");
+  });
+  child.stderr.on("data", (chunk) => {
+    stderrBuf += chunk.toString("utf8");
+  });
+
+  const exitCode: number = await new Promise((res, rej) => {
+    child.on("error", rej);
+    child.on("close", (code) => res(code ?? 0));
+  });
+
+  // Try to parse whichever stream has the JSON. On failure the agent puts
+  // its envelope on stderr; on success, on stdout.
+  if (exitCode !== 0) {
+    // Log the full stderr so the dev terminal shows the underlying tool's
+    // output (docker's stderr, git's stderr, etc.) — the shell agent only
+    // surfaces the code + step on the structured envelope.
+    if (stderrBuf.trim()) {
+      console.error(
+        `[uai-agent] ${scriptName} stderr (exit ${exitCode}):\n${stderrBuf.trim()}`,
+      );
+    }
+    const parsed = tryParseLastJsonLine(stderrBuf);
+    if (parsed) {
+      const failure = FailureEnvelope.safeParse(parsed);
+      if (failure.success) {
+        throw new AgentError(
+          failure.data.error.code,
+          failure.data.error.message,
+          {
+            step: failure.data.error.step,
+            exitCode: failure.data.error.exit_code ?? exitCode,
+          },
+        );
+      }
+    }
+    throw new AgentError(
+      "AGENT_UNKNOWN_FAILURE",
+      `${scriptName} exited ${exitCode}: ${stderrBuf.trim() || "no stderr"}`,
+      { exitCode },
+    );
+  }
+
+  const parsed = tryParseLastJsonLine(stdoutBuf);
+  if (!parsed) {
+    throw new AgentError(
+      "AGENT_BAD_OUTPUT",
+      `${scriptName} stdout was not JSON: ${stdoutBuf.trim().slice(0, 200)}`,
+      { exitCode },
+    );
+  }
+  const envelope = SuccessEnvelope(dataSchema).safeParse(parsed);
+  if (!envelope.success) {
+    throw new AgentError(
+      "AGENT_BAD_OUTPUT",
+      `${scriptName} returned unexpected shape: ${envelope.error.message}`,
+      { exitCode },
+    );
+  }
+  return envelope.data.data;
+}
+
+/**
+ * The agent may log info lines to stderr alongside the JSON envelope.
+ * On stdout we expect a single trailing JSON object; on stderr the
+ * envelope is the last line. This helper takes the last non-empty line
+ * and parses it as JSON.
+ */
+function tryParseLastJsonLine(buf: string): unknown {
+  const trimmed = buf.trim();
+  if (!trimmed) return null;
+  const lines = trimmed.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = (lines[i] ?? "").trim();
+    if (!line) continue;
+    try {
+      return JSON.parse(line);
+    } catch {
+      // Keep walking back; agent log lines are not JSON.
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Public API. One function per agent command.
+// ---------------------------------------------------------------------------
+
+export const agent = {
+  async taskUp(input: TaskLaunchInput): Promise<TaskUpResult> {
+    const commandDbPath = createTaskUpCommandDb(input);
+    // Materialize the creator's per-user SSH key so task-up.sh clones + pushes
+    // as them (ADR-029); null → task-up.sh falls back to the operator identity.
+    const identityDir = writeTaskIdentity(input.task.id, input.task.ownerUserId);
+    try {
+      return await runAgent(
+        "task-up.sh",
+        [input.task.id],
+        TaskUpData,
+        commandDbPath,
+        identityDir ? { UAI_TASK_IDENTITY_DIR: identityDir } : {},
+      );
+    } finally {
+      removeCommandDb(commandDbPath);
+      removeTaskIdentity(input.task.id);
+    }
+  },
+
+  async taskDown(input: TaskDownInput): Promise<TaskDownResult> {
+    const commandDbPath = createTaskDownCommandDb(
+      input,
+      getHostTask(input.taskId),
+    );
+    try {
+      return await runAgent(
+        "task-down.sh",
+        [input.taskId],
+        TaskDownData,
+        commandDbPath,
+      );
+    } finally {
+      removeCommandDb(commandDbPath);
+    }
+  },
+
+  async taskStatus(taskId: string): Promise<TaskStatusResult> {
+    const commandDbPath = createTaskStatusCommandDb(taskId, getHostTask(taskId));
+    try {
+      return await runAgent(
+        "task-status.sh",
+        [taskId],
+        TaskStatusData,
+        commandDbPath,
+      );
+    } finally {
+      removeCommandDb(commandDbPath);
+    }
+  },
+};
+
+export type Agent = typeof agent;