@runuai/host 0.1.0

package/lib/standard-image.ts

@@ -0,0 +1,152 @@
+/**
+ * Standard-image build pipeline (ADR-022 / docs/runtime.md).
+ *
+ * Every host builds exactly one standard image (`uai-standard:dev`) and
+ * caches it. `ensureStandardImage()` is called once at host startup:
+ *
+ *   1. `docker volume create uai-asdf-data` — the host-wide asdf data volume
+ *      that caches lazily-installed runtime versions across tasks (idempotent;
+ *      `docker volume create` is a no-op if the volume already exists).
+ *   2. `docker image inspect uai-standard:dev` — if it resolves, the image is
+ *      present and we skip the build. Otherwise `docker build` it from
+ *      `host-agent/images/standard/`.
+ *
+ * Best-effort: any failure (docker missing, daemon down, build error) is
+ * logged and swallowed so the host process still boots and serves tunnels.
+ * task-up surfaces the real error to the user if a build is genuinely needed.
+ */
+
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Pinned, host-wide constants (must match task-up.sh and the compose gen). */
+export const STANDARD_IMAGE_TAG = "uai-standard:dev";
+export const ASDF_DATA_VOLUME = "uai-asdf-data";
+
+/**
+ * Runtimes the standard image's asdf plugins can satisfy, with a sensible set
+ * of advertised versions per kind (ADR-021 `runtimes`). These are the
+ * versions the cloud's task-creation picker hints; asdf will lazily install
+ * any of them on first use (docs/runtime.md). The first entry of each list is
+ * the root `/etc/.tool-versions` default baked into the image.
+ *
+ * KEEP IN SYNC with host-agent/images/standard/ (the asdf plugins and the
+ * root tool-versions). Treat that directory as authoritative for the numbers;
+ * this list is the advertisement surface.
+ */
+export const STANDARD_RUNTIMES: ReadonlyArray<{
+  kind: string;
+  availableVersions: string[];
+}> = [
+  { kind: "node", availableVersions: ["22.11.0", "20.18.0", "18.20.4"] },
+  { kind: "python", availableVersions: ["3.12.4", "3.11.9"] },
+  { kind: "go", availableVersions: ["1.23.2", "1.22.8"] },
+  { kind: "ruby", availableVersions: ["3.3.5", "3.2.5"] },
+  { kind: "rust", availableVersions: ["1.81.0"] },
+];
+
+/** A fresh, mutable copy of the advertised runtimes for the capability frame. */
+export function standardRuntimes(): Array<{
+  kind: string;
+  availableVersions: string[];
+}> {
+  return STANDARD_RUNTIMES.map((r) => ({
+    kind: r.kind,
+    availableVersions: [...r.availableVersions],
+  }));
+}
+
+/** Absolute path to the standard image build context. */
+function standardImageDir(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  // lib/standard-image.ts -> host-agent/ -> images/standard
+  return resolve(here, "..", "images", "standard");
+}
+
+interface RunResult {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+/** Run a command to completion, capturing stdio. Never rejects. */
+function run(command: string, args: string[]): Promise<RunResult> {
+  return new Promise<RunResult>((resolveRun) => {
+    let stdout = "";
+    let stderr = "";
+    const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk: string) => {
+      stdout += chunk;
+    });
+    child.stderr?.on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+    child.on("error", (err: Error) => {
+      resolveRun({ code: null, stdout, stderr: stderr + err.message });
+    });
+    child.on("close", (code) => {
+      resolveRun({ code, stdout, stderr });
+    });
+  });
+}
+
+/**
+ * Ensure the standard image and the shared asdf data volume exist. Builds the
+ * image only when `docker image inspect` fails. Best-effort: logs and returns
+ * on any error so the host keeps booting.
+ */
+export async function ensureStandardImage(): Promise<void> {
+  // 1. Shared asdf data volume — idempotent.
+  const vol = await run("docker", ["volume", "create", ASDF_DATA_VOLUME]);
+  if (vol.code !== 0) {
+    console.warn(
+      `[host-agent] could not create asdf data volume (${ASDF_DATA_VOLUME}); ` +
+        `continuing. ${vol.stderr.trim()}`,
+    );
+    // If docker itself is unavailable, the image step will also fail; bail
+    // early so we don't double-log a confusing build error.
+    if (vol.code === null) return;
+  }
+
+  // 2. Is the image already built?
+  const inspect = await run("docker", [
+    "image",
+    "inspect",
+    STANDARD_IMAGE_TAG,
+  ]);
+  if (inspect.code === 0) {
+    console.log(`[host-agent] standard image ${STANDARD_IMAGE_TAG} present`);
+    return;
+  }
+  if (inspect.code === null) {
+    console.warn(
+      "[host-agent] docker unavailable; skipping standard image build. " +
+        "Tasks will fail until docker is running.",
+    );
+    return;
+  }
+
+  // 3. Build it.
+  const context = standardImageDir();
+  console.log(
+    `[host-agent] building standard image ${STANDARD_IMAGE_TAG} from ${context}`,
+  );
+  const build = await run("docker", [
+    "build",
+    "-t",
+    STANDARD_IMAGE_TAG,
+    context,
+  ]);
+  if (build.code === 0) {
+    console.log(`[host-agent] built standard image ${STANDARD_IMAGE_TAG}`);
+    return;
+  }
+  console.warn(
+    `[host-agent] standard image build failed (exit ${build.code ?? "spawn"}); ` +
+      "continuing. Tasks needing the image will surface this error.\n" +
+      build.stderr.trim(),
+  );
+}

package/lib/task-diff.ts

@@ -0,0 +1,113 @@
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+
+import type { TaskDiffInput, TaskDiffResult } from "../src/protocol";
+import { taskWorkspaceDir } from "./env";
+import { parseGitDiff, runGitDiff, runGitDiffInContainer } from "./git-diff";
+import { getHostTask } from "./runtime-state";
+
+export async function buildTaskDiff(
+  input: TaskDiffInput,
+): Promise<TaskDiffResult> {
+  const workspaceRoot = taskWorkspaceDir(input.taskId);
+  const runtime = getHostTask(input.taskId);
+  const containerName =
+    runtime?.statusMirror === "running" && runtime.composeProject
+      ? `${runtime.composeProject}-app-1`
+      : null;
+  const out: TaskDiffResult["repos"] = [];
+
+  for (const project of input.projects) {
+    const cwd = join(workspaceRoot, project.slug);
+    const containerCwd = `/workspace/${project.slug}`;
+    if (!containerName && !existsSync(cwd)) continue;
+
+    // Base branch is derived from the worktree's upstream (the worktree was
+    // created off `origin/<defaultBranch>` at task-up; ADR-022 derives and
+    // persists the default branch on the worktree, not the project record).
+    const base = resolveBase(containerName, cwd, containerCwd, project.slug);
+    const range = `${base}..HEAD`;
+    try {
+      const text = containerName
+        ? await runGitDiffInContainer(containerName, containerCwd, range)
+        : await runGitDiff(cwd, range);
+      out.push({
+        id: project.id,
+        name: project.slug,
+        mountPath: project.slug,
+        defaultBranch: stripOriginPrefix(base),
+        files: parseGitDiff(text),
+      });
+    } catch (err) {
+      out.push({
+        id: project.id,
+        name: project.slug,
+        mountPath: project.slug,
+        defaultBranch: stripOriginPrefix(base),
+        files: [],
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  return { repos: out };
+}
+
+/**
+ * Resolve the diff base for a worktree. Prefer the configured upstream
+ * (`@{upstream}`); fall back to the remote's default branch
+ * (`origin/HEAD`), then `origin/main`. Runs git in-container when the task
+ * is live so credential behavior stays inside the sandbox (see git-diff).
+ */
+function resolveBase(
+  containerName: string | null,
+  hostCwd: string,
+  containerCwd: string,
+  _slug: string,
+): string {
+  const upstream = runGitText(
+    containerName,
+    hostCwd,
+    containerCwd,
+    ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"],
+  );
+  if (upstream) return upstream;
+
+  const head = runGitText(
+    containerName,
+    hostCwd,
+    containerCwd,
+    ["rev-parse", "--abbrev-ref", "origin/HEAD"],
+  );
+  if (head) return head;
+
+  return "origin/main";
+}
+
+function stripOriginPrefix(ref: string): string {
+  return ref.startsWith("origin/") ? ref.slice("origin/".length) : ref;
+}
+
+/**
+ * Run a read-only git command (host or in-container) and return trimmed
+ * stdout, or null on any failure. Used for base-branch resolution where a
+ * missing upstream is expected, not exceptional.
+ */
+function runGitText(
+  containerName: string | null,
+  hostCwd: string,
+  containerCwd: string,
+  args: string[],
+): string | null {
+  const result = containerName
+    ? spawnSync(
+        "docker",
+        ["exec", "-w", containerCwd, containerName, "git", ...args],
+        { encoding: "utf8" },
+      )
+    : spawnSync("git", ["-C", hostCwd, ...args], { encoding: "utf8" });
+  if (result.status !== 0) return null;
+  const text = (result.stdout ?? "").trim();
+  return text.length > 0 ? text : null;
+}

package/lib/task-status.ts

@@ -0,0 +1,46 @@
+export const ACTIVE_STATUSES = [
+  "queued",
+  "starting",
+  "running",
+  "error",
+] as const;
+
+export const STOPPED_STATUSES = ["stopped"] as const;
+
+export const TERMINAL_STATUSES = [
+  "finished",
+  "canceled",
+  "killed",
+  "shipped",
+] as const;
+
+export const DASHBOARD_STATUSES = [
+  ...ACTIVE_STATUSES,
+  ...STOPPED_STATUSES,
+] as const;
+
+export const NON_TERMINAL_STATUSES = [
+  ...ACTIVE_STATUSES,
+  ...STOPPED_STATUSES,
+] as const;
+
+export type TaskStatus =
+  | (typeof ACTIVE_STATUSES)[number]
+  | (typeof STOPPED_STATUSES)[number]
+  | (typeof TERMINAL_STATUSES)[number];
+
+export function isActive(status: string): boolean {
+  return (ACTIVE_STATUSES as readonly string[]).includes(status);
+}
+
+export function isStopped(status: string): boolean {
+  return (STOPPED_STATUSES as readonly string[]).includes(status);
+}
+
+export function isTerminal(status: string): boolean {
+  return (TERMINAL_STATUSES as readonly string[]).includes(status);
+}
+
+export function isOnDashboard(status: string): boolean {
+  return isActive(status) || isStopped(status);
+}

package/lib/transcript.ts

@@ -0,0 +1,30 @@
+/**
+ * The shared channel transcript (ADR-027-adjacent). Agents have private,
+ * isolated conversations — each only hears what it's addressed. So they can opt
+ * into cross-agent awareness, the host maintains a plain-text log of every chat
+ * message at `<workspace>/.uai/chat.md` (mounted at /workspace), which any agent
+ * can read on demand. Messages only — no tool calls / actions.
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { taskWorkspaceDir } from "./env";
+import { rewriteAttachmentRefs } from "./orchestrator";
+
+/** Container path agents are pointed at. */
+export const CONTAINER_TRANSCRIPT_PATH = "/workspace/.uai/chat.md";
+
+export function appendTranscript(
+  taskId: string,
+  author: string,
+  text: string,
+): 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 dir = resolve(taskWorkspaceDir(taskId), ".uai");
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(resolve(dir, "chat.md"), `## ${author}\n\n${body}\n\n`);
+}

package/lib/ulid.ts

@@ -0,0 +1,7 @@
+import { ulid } from "ulid";
+
+export function newId(): string {
+  return ulid().toLowerCase();
+}
+
+export { ulid as monotonicUlid };

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@runuai/host",
+  "version": "0.1.0",
+  "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
+  "license": "MIT",
+  "author": "Diogo Perillo <diogo.perillo@gmail.com>",
+  "homepage": "https://github.com/runuai/uai#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/runuai/uai.git",
+    "directory": "host-agent"
+  },
+  "bugs": {
+    "url": "https://github.com/runuai/uai/issues"
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "claude",
+    "codex",
+    "docker",
+    "dev-container",
+    "self-hosted",
+    "orchestrator"
+  ],
+  "type": "module",
+  "bin": {
+    "uai-host": "./bin/uai-host.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "src",
+    "lib",
+    "db",
+    "scripts/agent",
+    "scripts/install",
+    "images/standard",
+    "ui",
+    "README.md",
+    "!**/*.test.ts",
+    "!**/*.bats",
+    "!scripts/agent/tests"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./protocol": {
+      "types": "./src/protocol.ts",
+      "default": "./src/protocol.ts"
+    }
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json",
+    "test:unit": "vitest run --config vitest.config.ts",
+    "start": "tsx src/cli.ts run",
+    "uai-host": "tsx src/cli.ts"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.3.0",
+    "dotenv": "^16.4.5",
+    "drizzle-orm": "^0.36.0",
+    "tsx": "^4.19.2",
+    "ulid": "^2.3.0",
+    "ws": "^8.18.3",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.59.4",
+    "@typescript-eslint/parser": "^8.59.4",
+    "@types/node": "^22.9.0",
+    "@types/ws": "^8.18.1",
+    "eslint": "^9.14.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  }
+}

package/scripts/agent/_common.sh

@@ -0,0 +1,248 @@
+#!/usr/bin/env bash
+# uai agent — shared helpers.
+#
+# Every agent script source's this file at the top. It establishes the
+# strict-mode posture, structured JSON output contract, sqlite access
+# helpers, and a uniform error trap.
+#
+# Output contract (docs/agent.md):
+#
+#   success  → stdout:  {"ok":true,"data":{...}}
+#   failure  → stderr:  {"ok":false,"error":{"code":"...","message":"...","step":"..."}}
+#               exit non-zero.
+#
+# Environment:
+#   UAI_DB_PATH        absolute path to uai.sqlite          (required)
+#   UAI_OWNER_HOME     host $HOME (for ~/.claude, ~/.codex) (default: $HOME)
+#   UAI_TTYD_BIND      ttyd listen address                  (default: 127.0.0.1)
+#   UAI_LOG_DIR        directory for ttyd / docker logs     (default: $UAI_DATA_DIR/logs)
+#   UAI_DATA_DIR       base data dir                        (default: dirname of UAI_DB_PATH)
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Strict env.
+# ---------------------------------------------------------------------------
+
+: "${UAI_DB_PATH:?UAI_DB_PATH must be set (path to uai.sqlite)}"
+
+UAI_DATA_DIR="${UAI_DATA_DIR:-$(dirname "$UAI_DB_PATH")}"
+UAI_OWNER_HOME="${UAI_OWNER_HOME:-$HOME}"
+# uai-owned storage tree (~/.uai by default). task-up / task-down derive
+# the per-project mirrors and per-task dirs from here (mirrors lib/env.ts).
+UAI_WORKSPACE_ROOT="${UAI_WORKSPACE_ROOT:-$UAI_OWNER_HOME/.uai}"
+UAI_TTYD_BIND="${UAI_TTYD_BIND:-127.0.0.1}"
+UAI_LOG_DIR="${UAI_LOG_DIR:-$UAI_DATA_DIR/logs}"
+mkdir -p "$UAI_LOG_DIR"
+
+# Optional dependencies — fail fast with a structured error if missing.
+for bin in sqlite3 jq docker git; do
+  if ! command -v "$bin" >/dev/null 2>&1; then
+    printf '{"ok":false,"error":{"code":"MISSING_DEPENDENCY","message":"%s not found on PATH"}}\n' "$bin" >&2
+    exit 127
+  fi
+done
+
+# ---------------------------------------------------------------------------
+# Logger. All log lines go to stderr so stdout stays reserved for JSON.
+# ---------------------------------------------------------------------------
+
+_uai_ts() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
+
+log() { printf '[uai-agent %s] %s\n' "$(_uai_ts)" "$*" >&2; }
+
+# ---------------------------------------------------------------------------
+# JSON output helpers.
+# ---------------------------------------------------------------------------
+
+# emit_ok '{"foo":"bar"}'
+#
+# NOTE: do not use `${1:-{}}` here — bash parses `{` inside the default
+# as a literal and the matching `}` closes the substitution prematurely,
+# so a real payload gets a trailing `}` appended. Use an explicit check.
+emit_ok() {
+  local data="$1"
+  if [ -z "$data" ]; then data='{}'; fi
+  printf '{"ok":true,"data":%s}\n' "$data"
+}
+
+# emit_err <code> <message> [step]
+#
+# Persists status='error' on the current task (if UAI_TASK_ID is set),
+# logs an `error` event, prints structured JSON to stderr, and exits 1.
+emit_err() {
+  local code="$1" msg="$2" step="${3:-${UAI_CURRENT_STEP:-}}"
+  _uai_mark_error "$code" "$step"
+  local json
+  if [ -n "$step" ]; then
+    json=$(jq -nc --arg c "$code" --arg m "$msg" --arg s "$step" \
+      '{ok:false,error:{code:$c,message:$m,step:$s}}')
+  else
+    json=$(jq -nc --arg c "$code" --arg m "$msg" \
+      '{ok:false,error:{code:$c,message:$m}}')
+  fi
+  printf '%s\n' "$json" >&2
+  exit 1
+}
+
+# _uai_mark_error <code> <step>  — best-effort persist of status=error.
+# Shared between emit_err (explicit) and the ERR trap (set -e).
+_uai_mark_error() {
+  local code="$1" step="$2"
+  if [ -n "${UAI_TASK_ID:-}" ] && [ -n "${UAI_DB_PATH:-}" ]; then
+    sqlite_exec "UPDATE uai_tasks SET status='error', locked_at=NULL, updated_at=(unixepoch()*1000) WHERE id='$(sql_escape "$UAI_TASK_ID")'" 2>/dev/null || true
+    local payload
+    payload=$(jq -nc --arg c "$code" --arg s "$step" '{code:$c,step:$s}')
+    sqlite_exec "INSERT INTO uai_task_events (id, task_id, kind, payload) VALUES ('$(sql_escape "$(_uai_event_id)")', '$(sql_escape "$UAI_TASK_ID")', 'error', '$(sql_escape "$payload")')" 2>/dev/null || true
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# SQLite helpers. The DB is local SQLite; concurrency is single-writer per
+# task (enforced via lock_task below + Next.js).
+# ---------------------------------------------------------------------------
+
+# sqlite_exec "<sql>"
+sqlite_exec() {
+  sqlite3 "$UAI_DB_PATH" "$1"
+}
+
+# sqlite_json "<sql>"  →  JSON array
+sqlite_json() {
+  sqlite3 -json "$UAI_DB_PATH" "$1"
+}
+
+# sql_escape <value>  →  single-quote-safe string for inline SQL.
+#
+# We pipe through sed instead of using bash parameter expansion because
+# bash 3.2 (macOS default) keeps backslashes in `${var//\'/\'\'}` —
+# producing `you\'\'re` from `you're` and breaking SQL string parsing.
+# sed handles it identically on bash 3.2 and 5+.
+sql_escape() {
+  printf '%s' "$1" | sed "s/'/''/g"
+}
+
+# db_get_task <id>  →  JSON array (one row) or "[]"
+db_get_task() {
+  local out
+  out=$(sqlite_json "SELECT * FROM uai_tasks WHERE id='$(sql_escape "$1")'")
+  printf '%s' "${out:-[]}"
+}
+
+# db_get_projects_for_task <taskId>  →  JSON array of the task's selected
+# projects, in position order. Each element carries every uai_projects
+# column plus the `position` from uai_task_projects. Empty array when the
+# task has no selected projects (scratchpad).
+db_get_projects_for_task() {
+  local out
+  out=$(sqlite_json "SELECT p.*, tp.position AS position FROM uai_projects p JOIN uai_task_projects tp ON tp.project_id = p.id WHERE tp.task_id = '$(sql_escape "$1")' ORDER BY tp.position ASC")
+  printf '%s' "${out:-[]}"
+}
+
+# db_update_task <id> "col=value" "col=value" ...
+#
+# Values must be pre-quoted by the caller (e.g. status='running', port=42).
+db_update_task() {
+  local id="$1"; shift
+  local set_clause
+  set_clause=$(IFS=','; echo "$*")
+  sqlite_exec "UPDATE uai_tasks SET ${set_clause}, updated_at=(unixepoch()*1000) WHERE id='$(sql_escape "$id")'"
+}
+
+# emit_event <task_id> <kind> <payload-json>
+emit_event() {
+  local tid="$1" kind="$2" payload="$3"
+  if [ -z "$payload" ]; then payload='{}'; fi
+  local eid
+  eid=$(_uai_event_id)
+  sqlite_exec "INSERT INTO uai_task_events (id, task_id, kind, payload) VALUES ('$(sql_escape "$eid")', '$(sql_escape "$tid")', '$(sql_escape "$kind")', '$(sql_escape "$payload")')"
+}
+
+# _uai_event_id — ULID-shaped fallback id generator (Crockford base32 prefix).
+# Real ULIDs come from the Next.js layer; agent-side events use ev_<unix><rand>.
+_uai_event_id() {
+  printf 'ev_%s%s' "$(date +%s%N | cut -c1-13)" "$(_uai_rand 10)"
+}
+
+_uai_rand() {
+  # Lowercase alphanumeric, length $1. Avoids depending on `uuidgen` etc.
+  local n="$1"
+  LC_ALL=C tr -dc 'a-z0-9' </dev/urandom | head -c "$n"
+}
+
+# ---------------------------------------------------------------------------
+# Locking. The Task row carries `locked_at`. Next.js also checks this
+# before invoking the agent; the shell-side lock is a safety net for
+# concurrent invocations of the same script.
+# ---------------------------------------------------------------------------
+
+lock_task() {
+  local id="$1"
+  # Atomic CAS via UPDATE WHERE locked_at IS NULL; success = changes()==1.
+  local changes
+  changes=$(sqlite_exec "UPDATE uai_tasks SET locked_at=(unixepoch()*1000), updated_at=(unixepoch()*1000) WHERE id='$(sql_escape "$id")' AND locked_at IS NULL; SELECT changes();")
+  [ "$changes" = "1" ] || emit_err "TASK_LOCKED" "task $id is already locked" "lock"
+  UAI_LOCK_HELD="$id"
+}
+
+unlock_task() {
+  local id="$1"
+  sqlite_exec "UPDATE uai_tasks SET locked_at=NULL, updated_at=(unixepoch()*1000) WHERE id='$(sql_escape "$id")'"
+  UAI_LOCK_HELD=""
+}
+
+# ---------------------------------------------------------------------------
+# Step tracking + ERR trap.
+#
+# `step <code> <label>` declares the next risky operation. If the script
+# exits non-zero, the trap emits a structured error tagged with the
+# current step's code + label, marks the task `status=error`, and
+# releases the lock.
+# ---------------------------------------------------------------------------
+
+UAI_CURRENT_STEP=""
+UAI_ERROR_CODE="UNKNOWN"
+UAI_TASK_ID=""
+UAI_LOCK_HELD=""
+
+step() {
+  UAI_ERROR_CODE="$1"
+  UAI_CURRENT_STEP="$2"
+  log "step: $UAI_CURRENT_STEP"
+}
+
+_uai_on_err() {
+  local rc=$?
+  # Disable further ERR trap recursion.
+  trap - ERR
+
+  local code="$UAI_ERROR_CODE"
+  local stepname="$UAI_CURRENT_STEP"
+
+  _uai_mark_error "$code" "$stepname"
+
+  local out
+  out=$(jq -nc --arg c "$code" --arg m "agent step failed" --arg s "$stepname" --argjson rc "$rc" \
+    '{ok:false,error:{code:$c,message:$m,step:$s,exit_code:$rc}}')
+  printf '%s\n' "$out" >&2
+  exit "$rc"
+}
+
+setup_err_trap() {
+  trap _uai_on_err ERR
+}
+
+# ---------------------------------------------------------------------------
+# Compose project name + container name conventions.
+# ---------------------------------------------------------------------------
+
+# Belt-and-braces: docker compose only accepts lowercase project names.
+# We also lowercase ulids at generation (lib/ulid.ts) but defensive
+# lowercasing here protects against any caller passing mixed case.
+_uai_lower() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]'; }
+compose_project_for_task()    { printf 'task-%s' "$(_uai_lower "$1")"; }
+# Compose v2 names containers as `<project>-<service>-<replica>`. We
+# never scale beyond one replica, so the suffix is always `-1`. If we
+# ever do scale, swap to discovering the container name via the
+# `com.docker.compose.project` + `com.docker.compose.service` labels.
+app_container_for_task()      { printf 'task-%s-app-1' "$(_uai_lower "$1")"; }