@moondeck/station 0.0.1 → 1.0.0

package/lib/skills.ts

@@ -0,0 +1,489 @@
+/**
+ * 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 `.moondeck/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 { taskWorkspaceDir } from "./env";
+import { dockerCli } from "./docker-exec";
+import {
+  taskAppContainerName,
+  taskContainerCli,
+} from "./task-container-cli";
+import { runtimeAuthorityDockerExecArgs } from "./runtime-authority";
+import type { RosterAgent, RosterSkill } from "./agents/types";
+import {
+  SKILL_FILES_DIR,
+  SKILL_FILES_MANIFEST,
+  flatSkills,
+  isSkillFileName,
+  renderSkillLayout,
+  skillSlug,
+} from "./skill-layout";
+
+export {
+  SKILL_FILE_MAX_BYTES,
+  SKILL_FILE_MAX_LINES,
+  SKILL_FILES_DIR,
+  SKILL_INDEX_THRESHOLD_LINES,
+  fitsSkillFileBudget,
+  hasSkillIndex,
+  isSkillFileName,
+  renderSkillLayout,
+  renderSkillMd,
+  skillSlug,
+  skillSummary,
+  splitSkillDocument,
+  type SkillLayout,
+} from "./skill-layout";
+import {
+  makeContainedDirectories,
+  makeContainedDirectoriesSync,
+  readContainedFrom,
+  removeContainedEntry,
+  removeContainedEntrySync,
+  WorkspaceDirectoryMissingError,
+  writeContainedFileSync,
+  type RuntimeNamespace,
+} from "./task-environment/workspace-files";
+
+/** The container path of an agent's SKILL.md — what the preamble points at. */
+export function containerSkillFile(agentId: string): string {
+  return `/workspace/.moondeck/agents/${agentId}/SKILL.md`;
+}
+
+/** The files the last split wrote, from its manifest; none when unreadable. */
+function previousSkillFiles(workspace: string, folder: readonly string[]): string[] {
+  try {
+    const read = readContainedFrom(workspace, [...folder, SKILL_FILES_MANIFEST], 0, 256 * 1024);
+    if (!read) return [];
+    return read.bytes.toString("utf8").split("\n").filter(isSkillFileName);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Each agent's skills work still in flight through the task's runtime
+ * (macOS), by task and agent. A write while one is in flight waits for it,
+ * then reads the folder and writes its layout, so no deletion or write of an
+ * older layout ever lands after a newer one. On Linux every step is done at
+ * once and nothing waits here.
+ */
+const skillsInFlight = new Map<string, Promise<void>>();
+/**
+ * Each agent's latest write, so a queued write that a newer one replaced is
+ * skipped. Only queued writes read it, so a key is dropped once nothing is
+ * queued for it: the runner is long-lived, and tasks and agents come and go.
+ */
+const skillWrites = new Map<string, number>();
+
+/** Tests only: how many agents the runner still holds skills state for. */
+export function skillsStateForTests(): { writes: number; inFlight: number } {
+  return { writes: skillWrites.size, inFlight: skillsInFlight.size };
+}
+
+/**
+ * Write an agent's SKILL.md into the task workspace (idempotent: overwrites,
+ * or removes the file when the agent has no skills). A split skill's files
+ * go beside it in `skills/`, written before the index that names them.
+ * Files the previous layout wrote and this one does not are removed first;
+ * never a file this layout writes. Returns the container path when written
+ * (or queued behind runtime work still in flight), 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,
+  runtime?: () => Promise<RuntimeNamespace | null>,
+): string | null {
+  const key = `${taskId}\0${agent.id}`;
+  const generation = (skillWrites.get(key) ?? 0) + 1;
+  skillWrites.set(key, generation);
+  const result = flatSkills(agent).length === 0 ? null : containerSkillFile(agent.id);
+  const inFlight = skillsInFlight.get(key);
+  if (inFlight) {
+    // Behind the runtime work of an earlier write; only the latest queued one runs.
+    track(key, inFlight.then(() => (skillWrites.get(key) === generation ? writeSkillsNow(taskId, agent, runtime)?.done : undefined)));
+    return result;
+  }
+  const attempt = writeSkillsNow(taskId, agent, runtime);
+  if (attempt?.done) {
+    track(key, attempt.done);
+  } else {
+    // Done at once (or refused), with nothing queued: no state to keep.
+    skillWrites.delete(key);
+  }
+  return attempt === null ? null : attempt.path;
+}
+
+/**
+ * Hold `work` as the agent's in-flight skills work until it settles. When
+ * it is still the latest (nothing newer queued behind it), the agent's
+ * state goes with it, however the work ended.
+ */
+function track(key: string, work: Promise<void>): void {
+  const settled = work.catch(() => {}).finally(() => {
+    if (skillsInFlight.get(key) !== settled) return;
+    skillsInFlight.delete(key);
+    skillWrites.delete(key);
+  });
+  skillsInFlight.set(key, settled);
+}
+
+/**
+ * One write, done at once where the host can. What only the runtime can do
+ * is in `done`, in order: removals first, then writes. Null when refused.
+ */
+function writeSkillsNow(
+  taskId: string,
+  agent: RosterAgent,
+  runtime?: () => Promise<RuntimeNamespace | null>,
+): { path: string | null; done?: Promise<void> } | null {
+  // Into the task's own .moondeck, never through a link the task put there
+  // (#cb3j0z). Where only the task's runtime can make the agent's directory
+  // (macOS), it is made there once the runtime is reachable, then the file
+  // written; the agent reads it when it consults its skills.
+  const workspace = taskWorkspaceDir(taskId);
+  const directory = [".moondeck", "agents", agent.id];
+  const file = [...directory, "SKILL.md"];
+  const folder = [...directory, SKILL_FILES_DIR];
+  const later: ((reached: RuntimeNamespace) => Promise<void>)[] = [];
+  /**
+   * Remove entries now where the host can; the rest through the runtime,
+   * in order, never a skills file the layout being written names (`keep`).
+   */
+  const remove = (entries: string[][], keep: ReadonlySet<string>) => {
+    const left: string[][] = [];
+    for (const entry of entries) {
+      try {
+        removeContainedEntrySync(workspace, entry);
+      } catch {
+        left.push(entry);
+      }
+    }
+    if (left.length === 0) return;
+    later.push(async (reached) => {
+      for (const entry of left) {
+        const inFolder = entry.length === folder.length + 1 && entry.slice(0, -1).join("/") === folder.join("/");
+        if (inFolder && keep.has(entry[entry.length - 1]!)) continue;
+        await removeContainedEntry(workspace, entry, reached);
+      }
+    });
+  };
+  const deferred = (): Promise<void> | undefined => {
+    if (later.length === 0 || !runtime) return undefined;
+    return (async () => {
+      const reached = await runtime();
+      if (!reached) return;
+      for (const step of later) await step(reached);
+    })();
+  };
+  try {
+    const previous = previousSkillFiles(workspace, folder);
+    const previousEntries = previous.length
+      ? [...previous.map((name) => [...folder, name]), [...folder, SKILL_FILES_MANIFEST]]
+      : [];
+    if (flatSkills(agent).length === 0) {
+      remove([...previousEntries, file], new Set());
+      return { path: null, done: deferred() };
+    }
+    const { skillMd, files } = renderSkillLayout(agent);
+    const names = files.map((f) => f.name);
+    if (names.some((name) => !isSkillFileName(name))) return null;
+    const keep = new Set(names);
+    const writes: { parts: string[]; bytes: Uint8Array }[] = [
+      ...files.map((f) => ({ parts: [...folder, f.name], bytes: Buffer.from(f.content) })),
+      ...(files.length ? [{ parts: [...folder, SKILL_FILES_MANIFEST], bytes: Buffer.from(`${names.join("\n")}\n`) }] : []),
+      { parts: file, bytes: Buffer.from(skillMd) },
+    ];
+    // Stale: what the previous layout wrote and this one does not, removed
+    // before the new manifest is written. A flat layout keeps none.
+    remove(
+      files.length
+        ? previous.filter((name) => !keep.has(name)).map((name) => [...folder, name])
+        : previousEntries,
+      keep,
+    );
+    const directories = files.length ? [directory, folder] : [directory];
+    const writeAll = () => {
+      for (const write of writes) writeContainedFileSync(workspace, write.parts, write.bytes);
+    };
+    if (!directories.every((d) => makeContainedDirectoriesSync(workspace, d))) {
+      let written = false;
+      try {
+        writeAll();
+        written = true;
+      } catch (error) {
+        if (!(error instanceof WorkspaceDirectoryMissingError) || !runtime) throw error;
+      }
+      if (!written) {
+        later.push(async (reached) => {
+          for (const d of directories) await makeContainedDirectories(workspace, d, reached);
+          writeAll();
+        });
+      }
+      return { path: containerSkillFile(agent.id), done: deferred() };
+    }
+    writeAll();
+    return { path: containerSkillFile(agent.id), done: deferred() };
+  } 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 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 }>;
+
+export function packageSkillDockerExecArgs(
+  container: string,
+  cmd: string[],
+  cwd?: string,
+): string[] {
+  return [
+    "exec",
+    "-u",
+    "node",
+    ...(cwd ? ["-w", cwd] : []),
+    ...runtimeAuthorityDockerExecArgs(),
+    container,
+    ...cmd,
+  ];
+}
+
+const dockerExec: SkillExec = async (container, cmd, cwd) => {
+  const full = packageSkillDockerExecArgs(container, cmd, cwd);
+  const res = await taskContainerCli(full, { timeoutMs: SKILL_EXEC_TIMEOUT_MS });
+  return { status: res.status, stderr: res.stderr };
+};
+
+/**
+ * A `skills add …` install command (github.com/vercel-labs/skills, the CLI
+ * behind the skills marketplace) asks which agents to install for and for a
+ * confirmation unless an agent is detected or `-y`/`--agent` are given. The
+ * install runs at task-up with no TTY and, on a fresh machine, before any
+ * agent has left its footprint, so the CLI refused: "Interactive prompt
+ * required but stdin is not a TTY … Use --agent <name> and -y" (every task
+ * start since the Marketing persona gained the skill; live 2026-09-10).
+ * Insert the two flags right after `skills add` when the author left them
+ * out — after the subcommand, so a trailing `&& …` or a leading `cd …`
+ * keeps working. Any other install command is returned as written.
+ */
+export function nonInteractiveInstallCommand(command: string): string {
+  const add = /\bskills\s+add\b/;
+  const found = add.exec(command);
+  if (!found) return command;
+  // Only the flags AFTER the subcommand count: `npx -y skills add …` is npx's
+  // own -y, not the CLI's. And the CLI wants its options AFTER the source —
+  // put before it, the parser reports "Missing required argument: source"
+  // (live 2026-09-10, smoke 14) — so the flags go right after the source
+  // token: the first token past `add` that is not an option or an option's
+  // value, stopping at a shell operator.
+  const afterAdd = found.index + found[0].length;
+  const rest = command.slice(afterAdd);
+  const tail = rest.split(/(?=\s(?:&&|\|\||[|;]))/)[0] ?? rest;
+  const flags: string[] = [];
+  if (!/(^|\s)(-y|--yes)(\s|$)/.test(tail)) flags.push("-y");
+  if (!/(^|\s)(-a|--agent)(\s|=)/.test(tail)) flags.push("--agent claude-code");
+  if (flags.length === 0) return command;
+  const valued = /^(-a|--agent|-s|--skill)$/;
+  const tokens = [...tail.matchAll(/\S+/g)];
+  let sourceEnd = -1;
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]![0];
+    if (token.startsWith("-")) {
+      if (valued.test(token)) i += 1; // skip the option's value
+      continue;
+    }
+    sourceEnd = tokens[i]!.index! + token.length;
+    break;
+  }
+  const at = sourceEnd >= 0 ? afterAdd + sourceEnd : afterAdd + tail.length;
+  return `${command.slice(0, at)} ${flags.join(" ")}${command.slice(at)}`;
+}
+
+/**
+ * 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 = taskAppContainerName(taskId);
+  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", nonInteractiveInstallCommand(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;
+}