@runuai/host 0.3.0 → 0.4.0

package/lib/agent-cli.ts

@@ -0,0 +1,223 @@
+/**
+ * In-container `uai` CLI materialisation (ADR-048).
+ *
+ * At task-up the host writes two files into the task workspace (bind-mounted at
+ * /workspace, like skills — no docker cp/exec needed):
+ *   - `.uai/cli.mjs`   — the self-contained agent CLI (Node ESM, fetch-only).
+ *   - `.uai/uai.json`  — { apiUrl, token, permissions } the CLI reads.
+ *
+ * The token is minted here (host-side) carrying the task id, its owner user, and
+ * the UNION of the roster's permissions; the cloud verifies it. Agents invoke it
+ * as `node /workspace/.uai/cli.mjs <cmd>` (surfaced in the system preamble).
+ */
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { env, taskWorkspaceDir } from "./env";
+import { signTaskToken } from "./task-token";
+import type { RosterAgent } from "./agents/types";
+
+/** Container path of the CLI — what the preamble tells agents to run. */
+export const CONTAINER_CLI_PATH = "/workspace/.uai/cli.mjs";
+
+// The task's cli secret lives HOST-PRIVATE (never the container), so it survives
+// host restarts without a DB migration. The cloud re-sends it on each task-up.
+function taskSecretPath(taskId: string): string {
+  return resolve(env.dataDir, "task-secrets", taskId);
+}
+
+/** Persist the cloud-issued per-task cli secret (ADR-048). Best-effort. */
+export function storeTaskCliSecret(taskId: string, secret: string): void {
+  try {
+    mkdirSync(resolve(env.dataDir, "task-secrets"), { recursive: true });
+    writeFileSync(taskSecretPath(taskId), secret, { mode: 0o600 });
+  } catch {
+    // best-effort — the CLI is simply unavailable if we can't persist it
+  }
+}
+
+/** Read the per-task cli secret, or null if we don't have it. */
+export function loadTaskCliSecret(taskId: string): string | null {
+  try {
+    return readFileSync(taskSecretPath(taskId), "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** The union of a roster's permissions (ADR-048) — the task's effective powers. */
+export function rosterPermissions(roster: RosterAgent[]): string[] {
+  return Array.from(new Set(roster.flatMap((a) => a.permissions ?? [])));
+}
+
+/** Derive the cloud HTTPS API base from the host's cloud WSS url. */
+export function apiUrlFromCloudUrl(cloudUrl: string | undefined): string | null {
+  if (!cloudUrl) return null;
+  try {
+    const u = new URL(cloudUrl);
+    const proto = u.protocol === "wss:" ? "https:" : u.protocol === "ws:" ? "http:" : u.protocol;
+    return `${proto}//${u.host}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the CLI script + shared config (apiUrl only — NO token) into the task
+ * workspace. Each agent's OWN token is injected per-agent via its docker exec
+ * env (agentCliEnv), so no shared file ever holds a token. Best-effort +
+ * idempotent. No-op (false) if there's no api url or the roster has zero
+ * permissions — nothing the CLI could do.
+ */
+export function writeAgentCli(
+  taskId: string,
+  roster: RosterAgent[],
+  apiUrl: string | null,
+): boolean {
+  if (!apiUrl || rosterPermissions(roster).length === 0) return false;
+  try {
+    const dir = resolve(taskWorkspaceDir(taskId), ".uai");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(resolve(dir, "uai.json"), `${JSON.stringify({ apiUrl }, null, 2)}\n`);
+    const cliPath = resolve(dir, "cli.mjs");
+    writeFileSync(cliPath, CLI_SOURCE);
+    try {
+      chmodSync(cliPath, 0o755);
+    } catch {
+      // best-effort
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Per-agent env for the `docker exec` that spawns one agent (ADR-048): its OWN
+ * task token (carrying only ITS permissions) + the API url. Empty when the agent
+ * has no permissions (or no owner/url) — its `uai` CLI then reports "not
+ * available" rather than borrowing anyone else's powers.
+ */
+export function agentCliEnv(
+  taskId: string,
+  agent: RosterAgent,
+  ownerUserId: string | null,
+  apiUrl: string | null,
+  cliSecret: string | null,
+): Record<string, string> {
+  const permissions = agent.permissions ?? [];
+  if (!ownerUserId || !apiUrl || !cliSecret || permissions.length === 0) return {};
+  return {
+    UAI_TASK_TOKEN: signTaskToken(
+      { taskId, userId: ownerUserId, permissions, agentId: agent.id },
+      cliSecret,
+    ),
+    UAI_API_URL: apiUrl,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The CLI itself — kept as a self-contained ESM string so the host writes ONE
+// file with no dependencies (Node 22 in the image provides global fetch).
+// ---------------------------------------------------------------------------
+
+const CLI_SOURCE = `#!/usr/bin/env node
+// uai — in-task agent CLI (ADR-048). Talks to the cloud agent API as the task.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+let cfg = {};
+try { cfg = JSON.parse(readFileSync(join(here, "uai.json"), "utf8")); } catch {}
+// Per-agent token comes from the env (each agent's docker exec carries only its
+// own — ADR-048); apiUrl from env or the shared config file.
+const TOKEN = process.env.UAI_TASK_TOKEN || cfg.token;
+const API_URL = process.env.UAI_API_URL || cfg.apiUrl;
+if (!TOKEN || !API_URL) {
+  console.error("uai: not available for this agent — no permissions granted (or not inside a task).");
+  process.exit(1);
+}
+
+function parseFlags(args) {
+  const flags = {}; const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) { const k = a.slice(2); const v = args[i + 1] && !args[i + 1].startsWith("--") ? args[++i] : "true"; flags[k] = v; }
+    else rest.push(a);
+  }
+  return { flags, rest };
+}
+
+async function api(method, path, body) {
+  const res = await fetch(API_URL + path, {
+    method,
+    headers: { authorization: "Bearer " + TOKEN, "content-type": "application/json" },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let json; try { json = JSON.parse(text); } catch { json = text; }
+  if (!res.ok) {
+    const msg = (json && json.error && json.error.message) || text || res.statusText;
+    console.error("uai: " + res.status + " " + msg);
+    process.exit(1);
+  }
+  return json;
+}
+function out(v) { console.log(typeof v === "string" ? v : JSON.stringify(v, null, 2)); }
+
+const argv = process.argv.slice(2);
+const [group, action, ...rest] = argv;
+const { flags, rest: pos } = parseFlags(rest);
+
+async function main() {
+  const key = group + " " + (action || "");
+  switch (key) {
+    case "projects list": out((await api("GET", "/api/agent/projects")).projects); break;
+    case "people list": out(await api("GET", "/api/agent/people")); break;
+    case "task list": out((await api("GET", "/api/agent/tasks")).tasks); break;
+    case "memory search": {
+      const q = pos.join(" ") || flags.q || "";
+      const author = flags.as ? "&author=" + encodeURIComponent(flags.as) : "";
+      out((await api("GET", "/api/agent/memory?q=" + encodeURIComponent(q) + author)).memories);
+      break;
+    }
+    case "memory save": {
+      const text = pos.join(" ") || flags.text || "";
+      if (!text) { console.error("uai: memory save needs text"); process.exit(1); }
+      out((await api("POST", "/api/agent/memory", {
+        text,
+        author: flags.as || null,
+        projectId: flags.project || null,
+        tags: flags.tags ? String(flags.tags).split(",").map((s) => s.trim()).filter(Boolean) : [],
+      })).memory);
+      break;
+    }
+    case "task create": {
+      out((await api("POST", "/api/agent/tasks", {
+        name: flags.name,
+        prompt: flags.prompt,
+        projects: flags.projects ? String(flags.projects).split(",").map((s) => s.trim()).filter(Boolean) : [],
+        team: flags.team || null,
+        agents: flags.agents ? String(flags.agents).split(",").map((s) => s.trim()).filter(Boolean) : [],
+        parent: flags.parent || null,
+      })).task);
+      break;
+    }
+    case "whoami ": case "whoami undefined": out({ apiUrl: API_URL }); break;
+    default:
+      console.error([
+        "uai — agent CLI. Commands:",
+        "  uai projects list",
+        "  uai people list",
+        "  uai task list",
+        "  uai task create --name <n> --prompt <p> [--projects id,id] [--team id] [--agents handle,handle]",
+        "  uai memory search <query>",
+        "  uai memory save <text> [--project id] [--tags a,b]",
+        "  uai whoami",
+      ].join("\\n"));
+      process.exit(argv.length ? 1 : 0);
+  }
+}
+main().catch((e) => { console.error("uai: " + (e && e.message ? e.message : e)); process.exit(1); });
+`;

package/lib/agents/claude.ts

@@ -200,6 +200,7 @@ export class ClaudeSession implements AgentSession {
     agent: RosterAgent;
     containerName: string;
     systemPreamble: string;
+    agentEnv?: Record<string, string>;
   }) {
     this.agentId = args.agent.id;
 
@@ -234,6 +235,7 @@ export class ClaudeSession implements AgentSession {
       "claude",
       cliArgs,
       ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
+      args.agentEnv ?? {},
     );
     this.proc = new LineProcess({
       command,
@@ -346,6 +348,6 @@ register({
         process.env.ANTHROPIC_API_KEY ||
         process.env.ANTHROPIC_AUTH_TOKEN,
     ),
-  create: async ({ agent, containerName, systemPreamble }) =>
-    new ClaudeSession({ agent, containerName, systemPreamble }),
+  create: async ({ agent, containerName, systemPreamble, agentEnv }) =>
+    new ClaudeSession({ agent, containerName, systemPreamble, agentEnv }),
 });

package/lib/agents/codex.ts

@@ -227,6 +227,7 @@ export class CodexSession implements AgentSession {
     agent: RosterAgent;
     containerName: string;
     systemPreamble: string;
+    agentEnv?: Record<string, string>;
   }) {
     this.agentId = args.agent.id;
     this.systemPreamble = args.systemPreamble;
@@ -247,6 +248,8 @@ export class CodexSession implements AgentSession {
       args.containerName,
       "codex",
       codexArgs,
+      [],
+      args.agentEnv ?? {},
     );
     this.proc = new LineProcess({
       command,
@@ -528,6 +531,6 @@ register({
     existsSync(
       join(process.env.UAI_OWNER_HOME?.trim() || homedir(), ".codex", "auth.json"),
     ),
-  create: async ({ agent, containerName, systemPreamble }) =>
-    new CodexSession({ agent, containerName, systemPreamble }),
+  create: async ({ agent, containerName, systemPreamble, agentEnv }) =>
+    new CodexSession({ agent, containerName, systemPreamble, agentEnv }),
 });

package/lib/agents/proc.ts

@@ -160,11 +160,20 @@ export function dockerExecArgs(
    * cloud (ADR-015). Only vars actually set on the host are forwarded.
    */
   passEnv: string[] = [],
+  /**
+   * Explicit per-exec env values (`-e NAME=value`) — used for per-agent values
+   * that don't live in the host's own env, e.g. the agent's task-scoped
+   * `UAI_TASK_TOKEN` (ADR-048). Values are argv, never a shell string.
+   */
+  explicitEnv: Record<string, string> = {},
 ): { command: string; args: string[] } {
   const envArgs: string[] = [];
   for (const name of passEnv) {
     if (process.env[name]) envArgs.push("-e", name);
   }
+  for (const [name, value] of Object.entries(explicitEnv)) {
+    envArgs.push("-e", `${name}=${value}`);
+  }
   return {
     command: "docker",
     args: ["exec", "-i", ...envArgs, containerName, cli, ...cliArgs],

package/lib/agents/types.ts

@@ -26,6 +26,19 @@ export type AgentKind = z.infer<typeof AgentKind>;
  *  `@<id>` mention token. `kind` selects the adapter; `model` is passed
  *  through to the CLI. There is no `role` field. `initialPrompt` (if set)
  *  drives this agent's first turn at container-ready. */
+/** Reference material (a link or inline document) materialised onto an agent
+ *  from its persona + team (ADR-046). The host writes these to a per-agent
+ *  SKILL.md at session start. */
+export const RosterSkill = z.object({
+  name: z.string().min(1),
+  type: z.string().min(1), // 'link' | 'document' | 'package' (ADR-047)
+  value: z.string(),
+  // ADR-047 package skills: 'git' | 'cli' install mode + (git) repo subpath.
+  source: z.string().nullable().optional(),
+  subpath: z.string().nullable().optional(),
+});
+export type RosterSkill = z.infer<typeof RosterSkill>;
+
 export const RosterAgent = z.object({
   id: z
     .string()
@@ -37,6 +50,8 @@ export const RosterAgent = z.object({
   effort: z.string().min(1).optional(), // CLI reasoning level, passed through
   defaultPrompt: z.string().optional(), // persona
   initialPrompt: z.string().optional(), // first-turn instructions, this task only
+  skills: z.array(RosterSkill).optional(), // ADR-046 reference material
+  permissions: z.array(z.string()).optional(), // ADR-048 `uai` CLI capabilities
 });
 export type RosterAgent = z.infer<typeof RosterAgent>;
 
@@ -129,5 +144,8 @@ export interface AgentSessionFactory {
     containerName: string;
     /** Initial briefing — project.defaultPrompt — sent on session start. */
     systemPreamble: string;
+    /** ADR-048: extra per-agent env for the `docker exec` (e.g. this agent's
+     *  own UAI_TASK_TOKEN so its `uai` CLI carries only its own permissions). */
+    agentEnv?: Record<string, string>;
   }): Promise<AgentSession>;
 }

package/lib/orchestrator.ts

@@ -37,6 +37,20 @@ import { getHostTask, upsertHostTask } from "./runtime-state";
 import { setupTaskGithub } from "./github-tokens";
 import { setupTaskGitIdentity } from "./git-identity";
 import { dockerCli } from "./docker-exec";
+import {
+  containerSkillFile,
+  installedSkillPath,
+  installPackageSkills,
+  writeAgentSkills,
+} from "./skills";
+import {
+  CONTAINER_CLI_PATH,
+  agentCliEnv,
+  apiUrlFromCloudUrl,
+  loadTaskCliSecret,
+  writeAgentCli,
+} from "./agent-cli";
+import { env } from "./env";
 import type { ChannelEnsureInput, HostEvent } from "../src/protocol";
 
 export type HostEventSubscriber = (event: HostEvent) => void;
@@ -143,6 +157,9 @@ class Orchestrator {
           spec.branch,
         ),
       );
+      // ADR-046: materialise this agent's skills to its per-agent SKILL.md in
+      // the workspace (bind-mounted into the container). Best-effort.
+      writeAgentSkills(taskId, agent);
       // ADR-022: any agent with a non-empty initialPrompt opens a first
       // turn at container-ready. The rest stay silent until addressed.
       const firstTurn = assembleFirstTurnPrompt(
@@ -222,12 +239,28 @@ class Orchestrator {
       void setupTaskGithub(channel.taskId, task.ownerUserId);
     }
 
+    // ADR-047: install any package skills (native Claude Agent Skills) into the
+    // container BEFORE spawning agents, so they're discoverable on the first
+    // turn. Idempotent + best-effort (returns fast when there are none); a slow
+    // clone/install briefly delays start, which is acceptable for skill-bearing
+    // tasks. Never throws.
+    await installPackageSkills(channel.taskId, channel.roster);
+
+    // ADR-048: write the in-container `uai` CLI (apiUrl only, no token) into the
+    // workspace. Each agent's OWN task token — carrying only ITS permissions — is
+    // injected per-agent via its docker exec env below, so per-persona permissions
+    // are actually enforced. Best-effort, host-side.
+    const apiUrl = apiUrlFromCloudUrl(env.UAI_CLOUD_URL);
+    const cliSecret = loadTaskCliSecret(channel.taskId);
+    writeAgentCli(channel.taskId, channel.roster, apiUrl);
+
     for (const agent of channel.roster) {
       const session = await this.factory.create({
         taskId: channel.taskId,
         agent,
         containerName: channel.containerName,
         systemPreamble: channel.preambles.get(agent.id) ?? "",
+        agentEnv: agentCliEnv(channel.taskId, agent, task.ownerUserId, apiUrl, cliSecret),
       });
       channel.sessions.set(agent.id, session);
       session.onEvent((event) => {
@@ -825,6 +858,71 @@ export function buildSystemPreamble(
     "part of the project. Never review, edit, stage, commit, or flag it;",
     "treat it as ignored, even though git may show it as untracked.",
     "",
+    // ADR-046: link/document skills are materialised to a per-agent SKILL.md.
+    // Point the agent at its own file (package skills are handled below).
+    ...((agent.skills ?? []).some((s) => s.type !== "package")
+      ? [
+          "## Your skills",
+          "",
+          "Reference material (links + documents) has been prepared for you at",
+          `\`${containerSkillFile(agent.id)}\`. Read it when a task touches what`,
+          "it covers. It's yours — other agents have their own.",
+          "",
+        ]
+      : []),
+    // ADR-047: package skills are native Claude Agent Skills installed into the
+    // container's skills dir (Claude-only). List them so the agent knows they're
+    // available even if headless auto-discovery is unreliable.
+    ...(agent.kind === "claude" &&
+    (agent.skills ?? []).some((s) => s.type === "package")
+      ? [
+          "## Installed skills",
+          "",
+          "These Claude Agent Skills are installed for this task — invoke them",
+          "when a task touches what they cover:",
+          ...(agent.skills ?? [])
+            .filter((s) => s.type === "package")
+            .map((s) => `- **${s.name}** (\`${installedSkillPath(s)}\`)`),
+          "",
+        ]
+      : []),
+    // ADR-048: tell agents with permissions about their `uai` CLI.
+    ...((agent.permissions?.length ?? 0) > 0
+      ? [
+          "## The uai CLI",
+          "",
+          `You can query and plan through Uai by running \`node ${CONTAINER_CLI_PATH}`,
+          "<command>` in the shell. Your permissions:",
+          `\`${(agent.permissions ?? []).join(", ")}\`. Commands: \`projects list\`,`,
+          "`people list`, `task list`" +
+            (agent.permissions?.includes("tasks.create")
+              ? ", `task create --name <n> --prompt <p> [--projects id,id] [--team id] [--agents handle,handle]`"
+              : "") +
+            (agent.permissions?.includes("memory.write")
+              ? ", `memory save <text>`"
+              : "") +
+            (agent.permissions?.includes("memory.read")
+              ? ", `memory search <query>`"
+              : "") +
+            ".",
+          ...(agent.permissions?.includes("tasks.create")
+            ? [
+                "Tasks you create are DRAFTS — a human reviews and starts them;",
+                "nothing runs (or spends) until then.",
+              ]
+            : []),
+          ...(agent.permissions?.includes("memory.read") ||
+          agent.permissions?.includes("memory.write")
+            ? [
+                `Your memory handle is \`${agent.id}\` — pass \`--as ${agent.id}\` so`,
+                "memories are attributed to you. Recall relevant past work with",
+                "`memory search` before you start; save durable learnings with",
+                "`memory save` when you finish something worth remembering.",
+              ]
+            : []),
+          "",
+        ]
+      : []),
     "## Commit policy",
     "",
     "Commits are SSH-signed automatically (git is configured for it) — do",

package/lib/skills.ts

@@ -0,0 +1,263 @@
+/**
+ * Per-agent skills materialisation (ADR-046).
+ *
+ * A task agent's skills (reference links + documents, resolved cloud-side from
+ * its persona + team) are written to a per-agent `SKILL.md` inside the task
+ * workspace. The workspace is bind-mounted into the container at `/workspace`
+ * (ADR-014), so writing on the host makes the file appear in the container —
+ * no `docker cp`/`exec` needed (same mechanism as attachments).
+ *
+ * Each agent gets its OWN file under `.uai/agents/<id>/` so agents in a shared
+ * container don't see each other's material; the agent's system preamble points
+ * at its file (buildSystemPreamble), which is the reliable cross-CLI delivery
+ * (no dependency on Claude's project-skill auto-discovery in headless mode).
+ *
+ * ADR-047 adds a `package` skill type — a native Claude Agent Skill (folder +
+ * scripts) installed into the container's Claude skills dir via `docker exec`
+ * (git clone or an install command), so Claude discovers it natively. Package
+ * skills are Claude-only and task-level (shared by the container's agents),
+ * NOT written into the flat per-agent SKILL.md.
+ */
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { taskWorkspaceDir } from "./env";
+import { dockerCli } from "./docker-exec";
+import type { RosterAgent, RosterSkill } from "./agents/types";
+
+/** Skills that go into the flat per-agent SKILL.md — link/document only. The
+ *  ADR-047 `package` skills install into the container's skills dir instead. */
+function flatSkills(agent: RosterAgent): RosterSkill[] {
+  return (agent.skills ?? []).filter((s) => s.type !== "package");
+}
+
+/** The container path of an agent's SKILL.md — what the preamble points at. */
+export function containerSkillFile(agentId: string): string {
+  return `/workspace/.uai/agents/${agentId}/SKILL.md`;
+}
+
+/** Render an agent's skills into SKILL.md markdown ("everything in one file"). */
+export function renderSkillMd(agent: RosterAgent): string {
+  const skills = flatSkills(agent);
+  const lines = [
+    `# ${agent.label} — skills`,
+    "",
+    "Reference material prepared for you (links and documents). Consult it when",
+    "a task touches what it covers.",
+    "",
+  ];
+  for (const s of skills) {
+    lines.push(`## ${s.name}`, "");
+    if (s.type === "link") lines.push(`Link: ${s.value}`, "");
+    else lines.push(s.value.trim(), "");
+  }
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+/**
+ * Write an agent's SKILL.md into the task workspace (idempotent: overwrites,
+ * or removes the file when the agent has no skills). Returns the container path
+ * when written, else null. Best-effort — a write failure is swallowed so a
+ * skills problem never blocks the agent from running.
+ */
+export function writeAgentSkills(taskId: string, agent: RosterAgent): string | null {
+  const dir = resolve(taskWorkspaceDir(taskId), ".uai", "agents", agent.id);
+  const file = resolve(dir, "SKILL.md");
+  try {
+    if (flatSkills(agent).length === 0) {
+      rmSync(file, { force: true });
+      return null;
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(file, renderSkillMd(agent));
+    return containerSkillFile(agent.id);
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ADR-047 package skills — native Claude Agent Skills installed in-container.
+// ---------------------------------------------------------------------------
+
+const SKILL_EXEC_TIMEOUT_MS = 180_000; // clones / npx installs can be slow
+
+/**
+ * In-container git-skill installer. Shallow-clones a repo, then works out where
+ * the actual skill(s) live and copies each into `~/.claude/skills/<name>/`:
+ *
+ *   - `$2` (subpath) given → that folder is the skill.
+ *   - else repo root has a SKILL.md → the whole repo is the skill.
+ *   - else search the clone for SKILL.md files → install every skill folder it
+ *     finds (a "collection" repo), each under its own folder name.
+ *   - else exit 3 → the repo isn't a ready skill (needs a build; use cli mode).
+ *
+ * Params are positional argv ($1=url, $2=subpath, $3=name) — never interpolated
+ * into this text — so a repo URL / subpath can't shell-inject. `.git` is
+ * stripped and the temp clone removed; existing skill dirs are left untouched.
+ */
+const GIT_INSTALL_SCRIPT = `
+set -eu
+url="$1"; sub="$2"; name="$3"
+skills="$HOME/.claude/skills"
+mkdir -p "$skills"
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+git clone --depth 1 --quiet "$url" "$tmp/repo"
+repo="$tmp/repo"
+install_one() {
+  src="$1"; dest="$skills/$2"
+  if [ -e "$dest" ]; then echo "skip $2"; return 0; fi
+  if [ ! -f "$src/SKILL.md" ]; then echo "no-skill-md: $src"; return 1; fi
+  rm -rf "$src/.git"
+  cp -R "$src" "$dest"
+  echo "installed $2"
+}
+if [ -n "$sub" ]; then
+  install_one "$repo/$sub" "$name"
+elif [ -f "$repo/SKILL.md" ]; then
+  install_one "$repo" "$name"
+else
+  n=0
+  while IFS= read -r -d '' md; do
+    d="$(dirname "$md")"
+    if install_one "$d" "$(basename "$d")"; then n=$((n+1)); fi
+  done < <(find "$repo" -maxdepth 4 -name SKILL.md -not -path '*/.git/*' -print0)
+  if [ "$n" -eq 0 ]; then echo "no-skills-found"; exit 3; fi
+fi
+`;
+
+/** A url-safe folder name for a skill (the dir under ~/.claude/skills/). */
+export function skillSlug(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9._-]+/g, "-")
+      .replace(/^[-.]+|[-.]+$/g, "")
+      .slice(0, 64) || "skill"
+  );
+}
+
+/** A short label for an installed package skill (for the preamble note). */
+export function installedSkillPath(s: RosterSkill): string {
+  return s.source === "git"
+    ? `~/.claude/skills/${skillSlug(s.name)}/`
+    : `${s.name} (install command)`;
+}
+
+/**
+ * Package skills across the Claude agents in a roster, deduped by folder slug.
+ * Package skills are a Claude Code capability (ADR-047), so Codex agents are
+ * skipped; the install is task-level (one container, shared skills dir).
+ */
+export function collectPackageSkills(agents: RosterAgent[]): RosterSkill[] {
+  const seen = new Set<string>();
+  const out: RosterSkill[] = [];
+  for (const a of agents) {
+    if (a.kind !== "claude") continue;
+    for (const s of a.skills ?? []) {
+      if (s.type !== "package" || !s.value) continue;
+      const key = skillSlug(s.name);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(s);
+    }
+  }
+  return out;
+}
+
+/** Injectable docker-exec seam (mocked in tests). Runs `cmd` in `container` as
+ *  the `node` user, optionally with a working dir. Values are argv, never a
+ *  shell string — a URL/subpath can't shell-inject (cli mode is the exception:
+ *  it runs the author's command via `bash -lc` by design). */
+export type SkillExec = (
+  container: string,
+  cmd: string[],
+  cwd?: string,
+) => Promise<{ status: number | null; stderr: string }>;
+
+const dockerExec: SkillExec = async (container, cmd, cwd) => {
+  const full = ["exec", "-u", "node", ...(cwd ? ["-w", cwd] : []), container, ...cmd];
+  const res = await dockerCli(full, { timeoutMs: SKILL_EXEC_TIMEOUT_MS });
+  return { status: res.status, stderr: res.stderr };
+};
+
+/**
+ * Install a roster's package skills into the task container (ADR-047). Runs at
+ * task-up (after the container is running), mirroring the git-identity/github
+ * `docker exec` setup: best-effort, idempotent, never blocks the agents.
+ *
+ * Returns the human-readable paths of skills that are now present (for the
+ * agents' preamble note). `exec` is injectable for tests.
+ */
+export async function installPackageSkills(
+  taskId: string,
+  agents: RosterAgent[],
+  exec: SkillExec = dockerExec,
+): Promise<string[]> {
+  const pkgs = collectPackageSkills(agents);
+  if (pkgs.length === 0) return [];
+  const container = `task-${taskId}-app-1`;
+  const done: string[] = [];
+
+  for (const s of pkgs) {
+    const slug = skillSlug(s.name);
+    try {
+      if (s.source === "git") {
+        // Idempotent across ensureSessions re-runs: a marker records that the
+        // clone+install already ran, so reconnects don't re-clone.
+        const marker = `/home/node/.claude/skills/.uai-git-${slug}.done`;
+        if ((await exec(container, ["test", "-e", marker])).status === 0) {
+          done.push(installedSkillPath(s));
+          continue;
+        }
+        // subpath is de-fanged against traversal; url/subpath/name reach the
+        // installer as positional argv (never interpolated) — no shell inject.
+        const sub = (s.subpath ?? "").replace(/^[/.]+/, "").replace(/\.\.+/g, "");
+        const r = await exec(container, [
+          "bash",
+          "-lc",
+          GIT_INSTALL_SCRIPT,
+          "uai-skill", // $0
+          s.value, // $1 url
+          sub, // $2 subpath
+          slug, // $3 name
+        ]);
+        if (r.status !== 0) {
+          const why =
+            r.status === 3
+              ? "no SKILL.md found — the repo may need a build (try cli mode)"
+              : r.stderr.trim();
+          console.warn(`[skills] ${taskId}: git skill ${s.name} failed: ${why}`);
+          continue;
+        }
+        await exec(container, ["mkdir", "-p", "/home/node/.claude/skills"]);
+        await exec(container, ["touch", marker]);
+        console.log(`[skills] ${taskId}: installed git skill ${s.name}`);
+        done.push(installedSkillPath(s));
+      } else if (s.source === "cli") {
+        // Idempotent across ensureSessions re-runs (reconnects): a marker file
+        // records that the command already ran, since a CLI install isn't
+        // self-idempotent like `git clone` into an existing dir.
+        const marker = `/home/node/.claude/skills/.uai-cli-${slug}.done`;
+        if ((await exec(container, ["test", "-e", marker])).status === 0) {
+          done.push(installedSkillPath(s));
+          continue;
+        }
+        // The author's CLI drops files into .claude/skills; run it in the repo.
+        const c = await exec(container, ["bash", "-lc", s.value], "/workspace");
+        if (c.status !== 0) {
+          console.warn(`[skills] ${taskId}: install cmd for ${s.name} failed: ${c.stderr.trim()}`);
+          continue;
+        }
+        await exec(container, ["mkdir", "-p", "/home/node/.claude/skills"]);
+        await exec(container, ["touch", marker]);
+        console.log(`[skills] ${taskId}: ran install command for ${s.name}`);
+        done.push(installedSkillPath(s));
+      }
+    } catch (e) {
+      console.warn(`[skills] ${taskId}: package skill ${s.name} errored: ${String(e)}`);
+    }
+  }
+  return done;
+}

package/lib/task-token.ts

@@ -0,0 +1,40 @@
+/**
+ * Task-token minting (ADR-048) — the host mints the token the in-container `uai`
+ * CLI uses; the cloud verifies it (lib/task-token.ts). The signing key is the
+ * TASK's ephemeral `cliSecret`, issued by the cloud at task-up (not a static
+ * shared secret). Algorithm MUST stay identical to the cloud side.
+ */
+import { createHmac } from "node:crypto";
+
+export interface TaskTokenPayload {
+  taskId: string;
+  userId: string;
+  permissions: string[];
+  agentId?: string;
+}
+
+const PREFIX = "uai_";
+
+function b64url(buf: Buffer): string {
+  return buf
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+export function signTaskToken(payload: TaskTokenPayload, secret: string): string {
+  const body = b64url(
+    Buffer.from(
+      JSON.stringify({
+        t: payload.taskId,
+        u: payload.userId,
+        p: payload.permissions,
+        ...(payload.agentId ? { a: payload.agentId } : {}),
+        iat: Math.floor(Date.now() / 1000),
+      }),
+    ),
+  );
+  const sig = b64url(createHmac("sha256", secret).update(body).digest());
+  return `${PREFIX}${body}.${sig}`;
+}

package/package.json

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

package/src/index.ts

@@ -1,6 +1,7 @@
 import { agent, AgentError } from "../lib/agent";
 import { cloneRepo } from "../lib/repo-clone";
 import { getOrchestrator } from "../lib/orchestrator";
+import { storeTaskCliSecret } from "../lib/agent-cli";
 import { setupTaskGithub, clearRefresh } from "../lib/github-tokens";
 import { readAttachment, writeAttachment } from "../lib/attachments";
 import { appendTranscript as writeTranscript } from "../lib/transcript";
@@ -107,6 +108,11 @@ export const hostCommands: HostCommands = {
       input.ownerName ?? null,
       input.projects.map((p) => p.slug),
     );
+    // ADR-048: persist the cloud-issued per-task cli secret (host-private) so the
+    // `uai` CLI's per-agent tokens can be minted now + after a host restart.
+    if (input.task.cliSecret) {
+      storeTaskCliSecret(input.task.id, input.task.cliSecret);
+    }
     recordHostEvent(input.task.id, "task.created");
     const result = await wrapAgent(ctx, "taskUp", () => agent.taskUp(input));
     if (result.ok) {

package/src/main.ts

@@ -1080,12 +1080,35 @@ function expectTaskAgents(value: unknown): TaskAgent[] {
       kind: expectStringValue(row.kind, "agent.kind"),
     };
     if (typeof row.model === "string") out.model = row.model;
+    // effort was previously dropped here even though the protocol + adapters
+    // carry it — fixed alongside skills (ADR-046).
+    if (typeof row.effort === "string") out.effort = row.effort;
     if (typeof row.defaultPrompt === "string") {
       out.defaultPrompt = row.defaultPrompt;
     }
     if (typeof row.initialPrompt === "string") {
       out.initialPrompt = row.initialPrompt;
     }
+    if (Array.isArray(row.skills)) {
+      const skills = row.skills
+        .filter(
+          (s): s is Record<string, unknown> =>
+            typeof s === "object" && s !== null,
+        )
+        .map((s) => ({
+          name: typeof s.name === "string" ? s.name : "",
+          type: typeof s.type === "string" ? s.type : "",
+          value: typeof s.value === "string" ? s.value : "",
+          source: typeof s.source === "string" ? s.source : null,
+          subpath: typeof s.subpath === "string" ? s.subpath : null,
+        }))
+        .filter((s) => s.name && s.type);
+      if (skills.length > 0) out.skills = skills;
+    }
+    if (Array.isArray(row.permissions)) {
+      const perms = row.permissions.filter((p): p is string => typeof p === "string");
+      if (perms.length > 0) out.permissions = perms;
+    }
     return out;
   });
 }

package/src/protocol.ts

@@ -48,6 +48,17 @@ export interface TaskAgent {
   effort?: string;
   defaultPrompt?: string;
   initialPrompt?: string;
+  /** ADR-046 reference material resolved from the agent's persona + team.
+   *  ADR-047: `type: "package"` carries `source` ('git'|'cli') + `subpath`. */
+  skills?: Array<{
+    name: string;
+    type: string;
+    value: string;
+    source?: string | null;
+    subpath?: string | null;
+  }>;
+  /** ADR-048: the source persona's flat permission list for the `uai` CLI. */
+  permissions?: string[];
 }
 
 /**
@@ -112,6 +123,9 @@ export interface TaskCommandTask {
   slug: string;
   branch: string;
   status: string;
+  /** ADR-048: the task's ephemeral `uai` CLI secret — the host signs per-agent
+   *  tokens with it. Cloud-issued at task-up; never a static shared secret. */
+  cliSecret?: string;
   globalContext?: string;
   reviewerOrder?: string[];
   agents: TaskAgent[];