@moondeck/station 0.0.0-stage → 1.0.0

package/lib/skill-layout.ts

@@ -0,0 +1,417 @@
+/**
+ * What an agent's link and document skills write (ADR-046, ADR-166): the
+ * flat SKILL.md, or an index with a file per skill beside it. Pure, with no
+ * file, process or runtime access, so the cloud's tests and build can use it
+ * too; `skills.ts` writes what this renders.
+ */
+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. */
+export function flatSkills(agent: RosterAgent): RosterSkill[] {
+  return (agent.skills ?? []).filter((s) => s.type !== "package");
+}
+
+
+/** 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"
+  );
+}
+
+
+/** 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`;
+}
+
+// ---------------------------------------------------------------------------
+// ADR-166 skill files: SKILL.md becomes an index and each document skill its
+// own file beside it, so an agent reads a skill whole when its work comes up
+// instead of one long file a `cat` or `head` cuts short.
+// ---------------------------------------------------------------------------
+
+/** The folder, beside SKILL.md, that holds an indexed agent's skill files. */
+export const SKILL_FILES_DIR = "skills";
+/** The list of files the last write put there, so a later layout removes stale ones. */
+export const SKILL_FILES_MANIFEST = ".files";
+/** Past this many lines a flat SKILL.md becomes an index, even for one document. */
+export const SKILL_INDEX_THRESHOLD_LINES = 150;
+/**
+ * Each file in `skills/` is at most this many lines and bytes, so one `cat`
+ * shows it whole on every engine: shell output is cut, and some engines show
+ * only the head and tail of a long one. A longer document is written in parts.
+ */
+export const SKILL_FILE_MAX_LINES = 150;
+export const SKILL_FILE_MAX_BYTES = 8 * 1024;
+/**
+ * The marker a document carries before each of its own per-action files (the
+ * Astronaut's guide). A comment, so a runner that predates the split shows
+ * the document flat and unchanged.
+ */
+const SKILL_FILE_MARKER = /^<!-- skill-file: (\S+) -->$/gm;
+export const SKILL_FILE_NAME = /^[a-z0-9][a-z0-9-]{0,39}\.md$/;
+/** The longest base a skill file may have: what SKILL_FILE_NAME allows before `.md`. */
+const MAX_FILE_BASE = 40;
+
+/** Whether `name` is a file the runner writes in `skills/` (and its manifest may name). */
+export function isSkillFileName(name: string): boolean {
+  return SKILL_FILE_NAME.test(name);
+}
+
+/** `<base><suffix>.md`, the base cut so the whole name stays valid. */
+function fileName(base: string, suffix = ""): string {
+  const cut = base.slice(0, MAX_FILE_BASE - suffix.length).replace(/-+$/, "") || "skill";
+  const name = `${cut}${suffix}.md`;
+  if (!isSkillFileName(name)) throw new SkillLayoutError("name");
+  return name;
+}
+const MAX_SKILL_FILES = 64;
+
+/**
+ * A document split at its markers: the part before the first is its index,
+ * and each marker starts a file that runs to the next one. Null when it has
+ * no markers, or any marker names a file badly or twice, so a malformed
+ * document is written whole rather than half split.
+ */
+export function splitSkillDocument(value: string): { index: string; files: { name: string; content: string }[] } | null {
+  const markers = [...value.matchAll(SKILL_FILE_MARKER)];
+  if (markers.length === 0 || markers.length > MAX_SKILL_FILES) return null;
+  const names = markers.map((marker) => marker[1]!);
+  if (names.some((name) => !isSkillFileName(name)) || new Set(names).size !== names.length) return null;
+  const files = markers.map((marker, i) => {
+    const start = marker.index! + marker[0].length;
+    const end = i + 1 < markers.length ? markers[i + 1]!.index! : value.length;
+    return { name: names[i]!, content: `${value.slice(start, end).trim()}\n` };
+  });
+  return { index: value.slice(0, markers[0]!.index!).trim(), files };
+}
+
+/** A skill's one-line description: its first sentence, as plain text. */
+export function skillSummary(value: string): string {
+  const line = value
+    .split("\n")
+    .map((l) => l.trim())
+    .find((l) => l && !l.startsWith("#") && !l.startsWith("<!--") && !l.startsWith("```") && !/^[-*_]{3,}$/.test(l));
+  if (!line) return "";
+  const text = line.replace(/^[-*>]\s+/, "").replace(/[*_`]/g, "").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1");
+  const sentence = /^(.*?[.!?])(?:\s|$)/.exec(text)?.[1] ?? text;
+  return sentence.length > 140 ? `${sentence.slice(0, 137).trimEnd()}…` : sentence;
+}
+
+/** A file name for a skill: its slug, made unique among names already taken. */
+function uniqueFileName(name: string, taken: Set<string>): string {
+  const base = skillSlug(name).replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "skill";
+  let candidate = fileName(base);
+  for (let n = 2; taken.has(candidate); n++) candidate = fileName(base, `-${n}`);
+  taken.add(candidate);
+  return candidate;
+}
+
+const lineCount = (text: string) => text.replace(/\n$/, "").split("\n").length;
+/** Whether a file's exact content fits the budgets: its UTF-8 bytes and its lines. */
+export function fitsSkillFileBudget(content: string): boolean {
+  return lineCount(content) <= SKILL_FILE_MAX_LINES && Buffer.byteLength(content) <= SKILL_FILE_MAX_BYTES;
+}
+
+/** A Markdown line, or a fenced code block kept whole. */
+type Block =
+  | { kind: "line"; text: string }
+  | { kind: "fence"; open: string; body: string[]; close: string };
+
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})/;
+
+/** Lines grouped so that a fenced block is one unit; an unclosed fence runs to the end. */
+function blocksOf(text: string): Block[] {
+  const lines = text.split("\n");
+  const blocks: Block[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const open = FENCE_OPEN.exec(lines[i]!);
+    if (!open) {
+      blocks.push({ kind: "line", text: lines[i]! });
+      continue;
+    }
+    const marker = open[1]!;
+    const closes = new RegExp(`^ {0,3}${marker[0] === "`" ? "`" : "~"}{${marker.length},}\\s*$`);
+    const body: string[] = [];
+    let j = i + 1;
+    while (j < lines.length && !closes.test(lines[j]!)) body.push(lines[j++]!);
+    // Unclosed in the source: closed here, so no part is left inside a fence.
+    blocks.push({ kind: "fence", open: lines[i]!, body, close: j < lines.length ? lines[j]! : marker });
+    i = j;
+  }
+  return blocks;
+}
+
+const renderBlocks = (blocks: Block[]) =>
+  blocks.map((b) => (b.kind === "line" ? b.text : [b.open, ...b.body, b.close].join("\n"))).join("\n");
+
+/** `units` split before each block `starts` marks, keeping the block. */
+function splitBefore(blocks: Block[], starts: (b: Block) => boolean): Block[][] {
+  const out: Block[][] = [];
+  for (const block of blocks) {
+    if (out.length === 0 || starts(block)) out.push([]);
+    out[out.length - 1]!.push(block);
+  }
+  return out;
+}
+
+/** Text over `bytes` cut at characters, never inside a UTF-8 sequence. */
+function cutChars(text: string, bytes: number): string[] {
+  const out: string[] = [];
+  let piece = "";
+  for (const ch of text) {
+    if (piece && Buffer.byteLength(piece + ch) > bytes) {
+      out.push(piece);
+      piece = "";
+    }
+    piece += ch;
+  }
+  return piece ? [...out, piece] : out;
+}
+
+/**
+ * Text cut into pieces that each fit `lines` and `bytes`. Cuts fall only
+ * outside fenced code: at headings, then blank lines, then lines. A fenced
+ * block too big for one piece is cut between its lines, each fragment closed
+ * and reopened with the same fence and info string. A line too long for one
+ * piece is cut at characters. Units are cut only as finely as they need,
+ * then packed in order, each keeping the separator it had.
+ */
+function cutToBudget(text: string, lines: number, bytes: number): string[] {
+  const fits = (t: string) => t.split("\n").length <= lines && Buffer.byteLength(t) <= bytes;
+  const atoms: { text: string; sep: string }[] = [];
+  const add = (blocks: Block[], sep: string, level: number) => {
+    const rendered = renderBlocks(blocks);
+    if (fits(rendered)) {
+      atoms.push({ text: rendered, sep });
+      return;
+    }
+    if (level === 0) {
+      splitBefore(blocks, (b) => b.kind === "line" && /^#{1,6} /.test(b.text)).forEach((unit, i) =>
+        add(unit, i === 0 ? sep : "\n", 1),
+      );
+      return;
+    }
+    if (level === 1) {
+      // Paragraphs: runs between blank lines outside fences.
+      const paragraphs: Block[][] = [[]];
+      for (const block of blocks) {
+        if (block.kind === "line" && block.text.trim() === "") {
+          if (paragraphs[paragraphs.length - 1]!.length) paragraphs.push([]);
+        } else paragraphs[paragraphs.length - 1]!.push(block);
+      }
+      paragraphs.filter((p) => p.length).forEach((unit, i) => add(unit, i === 0 ? sep : "\n\n", 2));
+      return;
+    }
+    if (level === 2 && blocks.length > 1) {
+      blocks.forEach((block, i) => add([block], i === 0 ? sep : "\n", 3));
+      return;
+    }
+    const block = blocks[0]!;
+    if (block.kind === "line") {
+      cutChars(block.text, bytes).forEach((piece, i) => atoms.push({ text: piece, sep: i === 0 ? sep : "\n" }));
+      return;
+    }
+    // A fence too big for one piece: fragments of its lines, each fenced.
+    const frame = `${block.open}\n\n${block.close}`;
+    const room = { lines: lines - 2, bytes: bytes - Buffer.byteLength(frame) };
+    const bodyLines = block.body.flatMap((line) => (Buffer.byteLength(line) > room.bytes ? cutChars(line, room.bytes) : [line]));
+    let group: string[] = [];
+    const flush = (first: boolean) => {
+      atoms.push({ text: [block.open, ...group, block.close].join("\n"), sep: first ? sep : "\n" });
+      group = [];
+    };
+    let first = true;
+    for (const line of bodyLines) {
+      const next = [...group, line];
+      if (group.length && (next.length > room.lines || Buffer.byteLength(next.join("\n")) > room.bytes)) {
+        flush(first);
+        first = false;
+      }
+      group.push(line);
+    }
+    flush(first);
+  };
+  add(blocksOf(text), "", 0);
+  const pieces: string[] = [];
+  let current = "";
+  for (const atom of atoms) {
+    const joined = current ? `${current}${atom.sep}${atom.text}` : atom.text;
+    if (current && !fits(joined)) {
+      pieces.push(current);
+      current = atom.text;
+    } else {
+      current = joined;
+    }
+  }
+  if (current) pieces.push(current);
+  return pieces.map((piece) => piece.replace(/^\n+/, "").trimEnd()).filter((piece) => piece.trim());
+}
+
+/**
+ * One file's content as the files to write: itself when it fits the
+ * budgets, else parts named `<base>-part-<n>.md`, each but the last naming
+ * the next. Every file is measured as written, framing included, and each
+ * name passes the manifest's own check.
+ */
+function withinBudget(name: string, title: string, content: string, taken: Set<string>): { name: string; content: string }[] {
+  if (fitsSkillFileBudget(content)) return [{ name, content }];
+  const base = name.replace(/\.md$/, "");
+  const heading = title.length > 80 ? `${title.slice(0, 79)}…` : title;
+  // The most a part's framing adds: its heading, its "continued in" line and the final newline.
+  const longestName = "x".repeat(MAX_FILE_BASE) + ".md";
+  const frame = (n: string, total: number) => ({
+    head: `# ${heading} (part ${n} of ${total})\n\n`,
+    next: (to: string) => `\n\nContinued in \`${SKILL_FILES_DIR}/${to}\`; read it too.`,
+  });
+  for (let shrink = 0; shrink < 8; shrink++) {
+    const reserve = frame("9999", 9999);
+    const reservedBytes = Buffer.byteLength(reserve.head) + Buffer.byteLength(reserve.next(longestName)) + 1;
+    const scale = 1 - shrink * 0.1;
+    const pieces = cutToBudget(
+      content.trimEnd(),
+      Math.floor((SKILL_FILE_MAX_LINES - 4) * scale),
+      Math.floor((SKILL_FILE_MAX_BYTES - reservedBytes) * scale),
+    );
+    const claimed = new Set<string>();
+    const names = pieces.map((_, i) => {
+      if (i === 0) return name;
+      let candidate = fileName(base, `-part-${i + 1}`);
+      for (let n = 2; taken.has(candidate) || claimed.has(candidate); n++) candidate = fileName(base, `-part-${i + 1}-${n}`);
+      claimed.add(candidate);
+      return candidate;
+    });
+    const parts = pieces.map((piece, i) => {
+      const { head, next } = frame(String(i + 1), pieces.length);
+      return {
+        name: names[i]!,
+        content: `${i === 0 ? "" : head}${piece}${i + 1 < pieces.length ? next(names[i + 1]!) : ""}\n`,
+      };
+    });
+    if (parts.every((part) => fitsSkillFileBudget(part.content))) {
+      for (const n of claimed) taken.add(n);
+      return parts;
+    }
+  }
+  throw new SkillLayoutError("budget");
+}
+
+export interface SkillLayout {
+  /** SKILL.md: today's flat file, or the index. */
+  skillMd: string;
+  /** Files for `skills/`, empty when SKILL.md is flat. */
+  files: { name: string; content: string }[];
+  /** The skills the index names, in order; empty when flat. */
+  indexed: string[];
+}
+
+/**
+ * What an agent's skills write. Flat, exactly `renderSkillMd`, while the
+ * agent has at most one document skill, a flat file within
+ * SKILL_INDEX_THRESHOLD_LINES lines and SKILL_FILE_MAX_BYTES, and no split
+ * document. Otherwise SKILL.md
+ * is an index: one line per skill (a link inline, a document with its first
+ * sentence and its file), and the built-in guide's own index in its place
+ * when it carries markers, with its per-action files beside the others'. File names are the skill's
+ * slug, numbered when two skills share one, never one a split file took.
+ */
+export function renderSkillLayout(agent: RosterAgent): SkillLayout {
+  try {
+    return indexedOrFlat(agent);
+  } catch (error) {
+    // Never let a layout problem stop an agent: today's flat file, and one
+    // bounded line saying so (the agent, why, the size; never skill text).
+    const skillMd = renderSkillMd(agent);
+    const reason = error instanceof SkillLayoutError ? error.reason : "unexpected";
+    console.warn(
+      `[skills] ${agent.id.slice(0, 64)}: skill index fell back to a flat SKILL.md (${reason}); ${Buffer.byteLength(skillMd)} bytes`,
+    );
+    return { skillMd, files: [], indexed: [] };
+  }
+}
+
+/** Why a layout could not be built; only the reason is ever logged. */
+class SkillLayoutError extends Error {
+  constructor(readonly reason: "budget" | "name") {
+    super(reason === "budget" ? "a part could not fit the skill file budgets" : "a generated file name was not valid");
+  }
+}
+
+function indexedOrFlat(agent: RosterAgent): SkillLayout {
+  const skills = flatSkills(agent);
+  const flat = renderSkillMd(agent);
+  const documents = skills.filter((s) => s.type === "document");
+  // Only the first skill, the built-in guide the server puts first, is ever
+  // split at its markers; a workspace's or persona's own document is one file.
+  const first = skills[0];
+  const split = first?.type === "document" ? splitSkillDocument(first.value) : null;
+  if (
+    documents.length < 2 &&
+    !split &&
+    flat.trimEnd().split("\n").length <= SKILL_INDEX_THRESHOLD_LINES &&
+    Buffer.byteLength(flat) <= SKILL_FILE_MAX_BYTES
+  ) {
+    return { skillMd: flat, files: [], indexed: [] };
+  }
+  // The split's file names are its own, so they are taken first.
+  const taken = new Set<string>([SKILL_FILES_MANIFEST, ...(split?.files.map((f) => f.name) ?? [])]);
+  const files: SkillLayout["files"] = [];
+  const lines = [
+    `# ${agent.label} — skills`,
+    "",
+    "An index of the reference material prepared for you. Each document is its own",
+    `file in \`${SKILL_FILES_DIR}/\` beside this one. Before work a skill covers, read its`,
+    "file in full, for example with `cat`.",
+    "",
+  ];
+  /** The built-in guide's own index, after the other skills' one-line entries. */
+  const guide: string[] = [];
+  /** One line, whatever the stored name or link holds. */
+  const oneLine = (text: string) => text.replace(/\s+/g, " ").trim();
+  for (const skill of skills) {
+    const title = oneLine(skill.name);
+    if (skill.type === "link") {
+      lines.push(`- **${title}**: Link: ${oneLine(skill.value)}`);
+    } else if (skill === first && split) {
+      guide.push("", `## ${title}`, "", split.index);
+      files.unshift(...split.files.flatMap((f) => withinBudget(f.name, f.name.replace(/\.md$/, ""), f.content, taken)));
+    } else {
+      const name = uniqueFileName(skill.name, taken);
+      const summary = skillSummary(skill.value);
+      const body = skill.value.trim();
+      const parts = withinBudget(name, title, `${body.startsWith("# ") ? body : `# ${title}\n\n${body}`}\n`, taken);
+      const paths = parts.map((part) => `\`${SKILL_FILES_DIR}/${part.name}\``).join(", then ");
+      lines.push(`- **${title}**${summary ? ` — covers: ${summary}` : ""} → ${paths}`);
+      files.push(...parts);
+    }
+  }
+  return {
+    skillMd: `${[...lines, ...guide].join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}\n`,
+    files,
+    indexed: skills.map((s) => s.name),
+  };
+}
+
+/** Whether the agent's SKILL.md is an index, with its skills in files beside it. */
+export function hasSkillIndex(agent: RosterAgent): boolean {
+  return renderSkillLayout(agent).indexed.length > 0;
+}