@foldrun/core 0.4.0 → 0.6.0

package/dist/src/flow-patterns.js

@@ -0,0 +1,568 @@
+// Orchestration patterns as markdown edits.
+//
+// Each pattern a person can reach for — chain a step, run one in parallel,
+// route on a verdict, fan out, loop until a critic approves, gate on a
+// human, ask a question first, wait, rescue a failure — is a small, exact
+// change to a flow file. So is each change to an agent's team: a sub-agent
+// delegated to (`subagents:`), a colleague consulted (`agents:`), permission
+// to ask a person mid-step (`ask` in `tools:`). This module is those edits,
+// once, for every surface that makes them: the dashboard's flow canvas today,
+// the CLI's verbs next.
+//
+// Every edit is line-level surgery. Flow edits compose core's own rewrites
+// where one exists (addFlowStep, reorderFlowSteps), so every surface writes
+// the same file for the same gesture; what has no rewrite yet — an option
+// updateFlowStep does not manage (ask:, wait:, on-fail:, each: rows/items),
+// the `!` marker — is done here one step's lines at a time and re-parsed: an
+// edit the parser then flags on that step is refused, never written. Agent
+// edits touch only the frontmatter lines they name, so comments, key order
+// and the prose survive byte for byte — never a YAML re-dump.
+//
+// Pure: string in, string out. The caller reads and writes the file.
+import { parseFlow, addFlowStep, reorderFlowSteps, parseWait, assertSafeName } from "./store.js";
+import { joinGroup, splitToRail } from "./arrange.js";
+import { lintFlow } from "./flow-lint.js";
+import { toLF, asRaw } from "./eol.js";
+import { removalImpact, stepLabel } from "./step-removal.js";
+// ---------- flow files ----------
+/** A flow's steps as groups of indices into its parsed steps — what
+ *  reorderFlowSteps and the arrange helpers take. */
+export function flowGroups(steps) {
+    const map = new Map();
+    steps.forEach((s, i) => map.set(s.group, [...(map.get(s.group) ?? []), i]));
+    return [...map.entries()].sort((a, b) => a[0] - b[0]).map(([, v]) => v);
+}
+/** The step options a pattern writes. Everything else in a step stays the
+ *  author's (and updateFlowStep's) business. */
+export const PATTERN_OPTION_KEYS = [
+    "ask", "wait", "on-fail", "each", "max", "loop", "until", "verify", "case", "else", "when", "retry", "approve",
+];
+const OPTION_RE = /^(\s+)([a-z_-]+):(.*)$/;
+const MARKER_RE = /^(\s*\d+)([?!])?(\.?\s+\[\[)/;
+function stepAt(raw, index) {
+    const s = parseFlow("flow.md", raw).steps[index];
+    if (!s)
+        throw new Error(`no step ${index}`);
+    return s;
+}
+/** [first, end) of step `index`'s lines in raw.split("\n"): its step line
+ *  through the line before the next step (or the end of the file). */
+function stepSpan(raw, index) {
+    const steps = parseFlow("flow.md", raw).steps;
+    const s = steps[index];
+    if (!s?.line)
+        throw new Error(`no step ${index}`);
+    const first = s.line - 1;
+    const lines = raw.split("\n");
+    const later = steps.map((t) => (t.line ?? 0) - 1).filter((l) => l > first);
+    const end = later.length ? Math.min(...later) : lines.length;
+    return { lines, first, end };
+}
+const oneLine = (v) => v.replace(/[\r\n]+/g, " ").trim();
+/** Check a value before it is written, in the words the parser would use. */
+function checkOption(key, value) {
+    const n = Number(value);
+    switch (key) {
+        case "loop":
+            if (!Number.isInteger(n) || n < 1 || n > 5)
+                throw new Error("loop: is a whole number of extra cycles, 1 to 5");
+            break;
+        case "max":
+            if (!Number.isInteger(n) || n < 1 || n > 20)
+                throw new Error("max: is a whole number of items, 1 to 20");
+            break;
+        case "retry":
+            if (!Number.isInteger(n) || n < 0 || n > 5)
+                throw new Error("retry: is a whole number of extra attempts, at most 5");
+            break;
+        case "wait":
+            if (!/^event$/i.test(value) && parseWait(value) === undefined)
+                throw new Error("wait: is event, or a duration: 90s, 30m, 4h, 3d");
+            break;
+        case "each":
+            if (!/^(lines|items|rows of \S.*)$/.test(value))
+                throw new Error("each: is lines, items, or rows of <path>");
+            break;
+        case "on-fail":
+            assertSafeName(value.replace(/^\[\[|\]\]$/g, ""), "on-fail agent");
+            break;
+    }
+}
+/**
+ * Set (or clear, with null or "") options on one step. An option already
+ * there is rewritten on its own line, where it was; a new one goes after the
+ * step's run of indented lines, at the indent its siblings use — never after
+ * prose below the step.
+ */
+function setStepOptionsLF(raw, index, set) {
+    const before = stepAt(raw, index).problems?.length ?? 0;
+    const { lines, first, end } = stepSpan(raw, index);
+    const block = lines.slice(first, end);
+    const indent = block.slice(1).map((l) => l.match(OPTION_RE)?.[1]).find(Boolean) ?? "   ";
+    const keyOf = (l) => {
+        const k = l.match(OPTION_RE)?.[2];
+        return k === "onfail" ? "on-fail" : k;
+    };
+    for (const [key, given] of Object.entries(set)) {
+        if (!PATTERN_OPTION_KEYS.includes(key))
+            throw new Error(`a pattern does not write ${key}:`);
+        const at = block.findIndex((l, i) => i > 0 && keyOf(l) === key);
+        if (given === null || given === undefined || oneLine(given) === "") {
+            if (at !== -1)
+                block.splice(at, 1);
+            continue;
+        }
+        let value = oneLine(given);
+        if (key === "on-fail")
+            value = `[[${value.replace(/^\[\[|\]\]$/g, "")}]]`;
+        checkOption(key, value);
+        const line = `${indent}${key}: ${value}`;
+        if (at !== -1)
+            block[at] = line;
+        else {
+            let last = 0;
+            while (last + 1 < block.length && /^\s+\S/.test(block[last + 1]))
+                last++;
+            block.splice(last + 1, 0, line);
+        }
+    }
+    const out = [...lines.slice(0, first), ...block, ...lines.slice(end)].join("\n");
+    const after = stepAt(out, index).problems ?? [];
+    if (after.length > before)
+        throw new Error(after[after.length - 1]);
+    return out;
+}
+/** Turn the approval gate on or off: `!` on the step line where it can go;
+ *  an optional step (`?`) already has its one marker, so it gets
+ *  `approve: true` instead. Off removes either spelling. */
+function setStepApproveLF(raw, index, on) {
+    const { lines, first } = stepSpan(raw, index);
+    const m = lines[first].match(MARKER_RE);
+    if (!m)
+        throw new Error(`step ${index} is not a step line`);
+    const marker = m[2] ?? "";
+    if (on) {
+        if (stepAt(raw, index).approve)
+            return raw;
+        if (marker === "?")
+            return setStepOptionsLF(raw, index, { approve: "true" });
+        lines[first] = lines[first].replace(MARKER_RE, "$1!$3");
+        return lines.join("\n");
+    }
+    let out = raw;
+    if (marker === "!") {
+        lines[first] = lines[first].replace(MARKER_RE, "$1$3");
+        out = lines.join("\n");
+    }
+    return setStepOptionsLF(out, index, { approve: null });
+}
+/** A new step, placed; the file, the new step's index and its column. */
+function insertFlowStepLF(raw, o) {
+    let text = addFlowStep(raw, { target: o.target, subflow: o.subflow, instruction: o.instruction });
+    const steps = parseFlow("flow.md", text).steps;
+    const added = steps.length - 1;
+    let groups = flowGroups(steps);
+    if ("column" in o.at) {
+        const anchor = groups[o.at.column]?.[0];
+        if (anchor === undefined || anchor === added)
+            throw new Error(`no step ${o.at.column + 1} to run beside`);
+        groups = joinGroup(groups, added, anchor);
+    }
+    else {
+        groups = splitToRail(groups, added, o.at.rail);
+    }
+    text = reorderFlowSteps(text, groups);
+    const index = groups.flat().indexOf(added);
+    const column = groups.findIndex((g) => g.includes(added));
+    if (o.options && Object.keys(o.options).length)
+        text = setStepOptionsLF(text, index, o.options);
+    return { text, index, column };
+}
+/** The problems that make `check` fail, as a multiset of messages: the
+ *  parser's own per-step ones and the lint's error-level ones. */
+function errorsOf(raw) {
+    const flow = parseFlow("flow.md", raw);
+    return [
+        ...flow.steps.flatMap((s) => s.problems ?? []),
+        ...lintFlow(flow).filter((w) => w.level === "error").map((w) => w.message.replace(/step \d+/g, "step")),
+    ];
+}
+/**
+ * What else changes when step `index` goes — said before it goes. The rule
+ * lives in step-removal.ts, which imports no parser, so the canvas can say
+ * it in the browser from the steps it already has.
+ */
+function removeStepImpactLF(raw, index) {
+    return removalImpact(parseFlow("flow.md", raw).steps, index);
+}
+/**
+ * Delete step `index` (its index in the parsed steps): its step line and the
+ * indented option lines under it, nothing else — prose after the step stays.
+ * When that empties its group, the groups after it renumber so there is no
+ * gap. The agent's file is not touched. Refused when the result would give
+ * `check` an error it did not have (a `case:` step left first, with nothing
+ * to route on).
+ */
+function removeStepLF(raw, index) {
+    const steps = parseFlow("flow.md", raw).steps;
+    if (!Number.isInteger(index) || !steps[index])
+        throw new Error(`no step ${index + 1}`);
+    const emptied = flowGroups(steps).some((g) => g.length === 1 && g[0] === index);
+    const { lines, owned } = stepBlockLines(raw, index);
+    const drop = new Set(owned);
+    let out = lines.filter((_, i) => !drop.has(i)).join("\n");
+    if (emptied && steps.length > 1)
+        out = reorderFlowSteps(out, flowGroups(parseFlow("flow.md", out).steps));
+    assertNoNewErrors(raw, out, `removing ${stepLabel(steps, index)}`);
+    return out;
+}
+/** Throw when `out` has a `check` error `raw` did not — counted as a
+ *  multiset, so a second copy of an existing error is a new one. */
+function assertNoNewErrors(raw, out, what) {
+    const had = new Map();
+    for (const e of errorsOf(raw))
+        had.set(e, (had.get(e) ?? 0) + 1);
+    for (const e of errorsOf(out)) {
+        const n = had.get(e) ?? 0;
+        if (n)
+            had.set(e, n - 1);
+        else
+            throw new Error(`${what} would leave the flow with an error: ${e}`);
+    }
+}
+/** The lines of step `index`, by index into raw.split("\n"): its step line,
+ *  the indented lines directly under it, and every later option line the
+ *  parser still gives this step — an option after a blank line or a note
+ *  is the step's too (with the deeper-indented lines of a `schema:` block
+ *  under it). Never the prose or blank lines around them. */
+function stepBlockLines(raw, index) {
+    const { lines, first, end } = stepSpan(raw, index);
+    const owned = [first];
+    let i = first + 1;
+    while (i < end && /^\s+\S/.test(lines[i]))
+        owned.push(i++);
+    for (; i < end; i++) {
+        const opt = lines[i].match(OPTION_RE);
+        if (!opt)
+            continue;
+        owned.push(i);
+        const depth = opt[1].length;
+        while (i + 1 < end && (lines[i + 1].match(/^(\s*)\S/)?.[1].length ?? 0) > depth)
+            owned.push(++i);
+    }
+    return { lines, owned };
+}
+/** Step `index` as markdown — what the canvas copies to the clipboard and
+ *  pasteSteps reads back: the step line (group number, `?`/`!` marker,
+ *  link, instruction) and its indented options. */
+function stepSourceLF(raw, index) {
+    const { lines, owned } = stepBlockLines(raw, index);
+    return owned.map((i) => lines[i].replace(/\r$/, "")).join("\n");
+}
+/**
+ * Duplicate step `index`: the copy — step line with its marker, every
+ * indented option — goes directly under the original with the same group
+ * number, so it runs in parallel with it. Nothing else moves. Refused when
+ * `check` would gain an error.
+ */
+function duplicateStepLF(raw, index) {
+    const steps = parseFlow("flow.md", raw).steps;
+    if (!Number.isInteger(index) || !steps[index])
+        throw new Error(`no step ${index + 1}`);
+    const { lines, owned } = stepBlockLines(raw, index);
+    const end = owned[owned.length - 1] + 1;
+    const out = [...lines.slice(0, end), ...owned.map((i) => lines[i]), ...lines.slice(end)].join("\n");
+    assertNoNewErrors(raw, out, `duplicating ${stepLabel(steps, index)}`);
+    return out;
+}
+const PASTE_STEP_RE = /^\s*(\d+)([?!])?(\.?\s+\[\[.*)$/;
+/** Copied step markdown → blocks, each with the group number it was
+ *  copied with. Blank lines between blocks are fine; anything else that is
+ *  neither a step line nor an indented line under one is refused. */
+function pastedBlocks(text) {
+    const blocks = [];
+    for (const rawLine of text.replace(/\r\n?/g, "\n").split("\n")) {
+        const line = rawLine.replace(/\s+$/, "");
+        if (!line.trim())
+            continue;
+        const m = line.match(PASTE_STEP_RE);
+        if (m) {
+            blocks.push({ group: Number(m[1]), lines: [`${m[1]}${m[2] ?? ""}${m[3]}`] });
+        }
+        else if (/^\s+\S/.test(line) && blocks.length) {
+            blocks[blocks.length - 1].lines.push(line);
+        }
+        else {
+            throw new Error(`not a copied step: "${line.trim().slice(0, 60)}" — paste step lines and their indented options`);
+        }
+    }
+    if (!blocks.length)
+        throw new Error("nothing to paste — no step line (\"1. [[agent]] — …\")");
+    return blocks;
+}
+/**
+ * Paste copied steps (stepSource output, one block or several) into a flow.
+ * Steps copied with the same group number stay parallel with each other.
+ * `{ rail }` places the pasted groups as their own consecutive groups there
+ * (0 is before every group); `{ column }` puts every pasted step in that
+ * existing group. Groups renumber; prose stays where it was. Returns the
+ * file and the pasted steps' indices in it. Refused when the paste does not
+ * parse as those steps, or when `check` would gain an error.
+ */
+function pasteStepsLF(raw, text, at) {
+    const blocks = pastedBlocks(text);
+    const before = parseFlow("flow.md", raw).steps;
+    const top = before.reduce((m, s) => Math.max(m, s.group), 0);
+    // Pasted groups get numbers above every existing one, so they sort last
+    // and their indices are the tail of the parse; reorderFlowSteps then puts
+    // them where they belong and renumbers everything.
+    const order = [...new Set(blocks.map((b) => b.group))].sort((a, b) => a - b);
+    const renumbered = blocks.map((b) => {
+        const g = top + 1 + order.indexOf(b.group);
+        return [b.lines[0].replace(/^\d+/, String(g)), ...b.lines.slice(1)];
+    });
+    const added = renumbered.flat();
+    let merged;
+    if (before.length) {
+        // Above the first step line: whatever prose trails the last step stays
+        // with it instead of following the pasted ones.
+        const lines = raw.split("\n");
+        const first = Math.min(...before.map((s) => (s.line ?? 1) - 1));
+        merged = [...lines.slice(0, first), ...added, ...lines.slice(first)].join("\n");
+    }
+    else {
+        merged = `${raw.replace(/\s+$/, "")}\n\n${added.join("\n")}\n`;
+    }
+    const steps = parseFlow("flow.md", merged).steps;
+    if (steps.length !== before.length + blocks.length) {
+        throw new Error(`the paste parsed as ${steps.length - before.length} steps, not ${blocks.length}`);
+    }
+    const pasted = steps.map((_, i) => i).slice(before.length);
+    const groups = flowGroups(steps);
+    const old = groups.filter((g) => g.every((i) => i < before.length));
+    const fresh = groups.filter((g) => g.some((i) => i >= before.length));
+    let next;
+    if ("column" in at) {
+        if (!old[at.column])
+            throw new Error(`no step ${at.column + 1} to run beside`);
+        next = old.map((g, k) => (k === at.column ? [...g, ...pasted] : g));
+    }
+    else {
+        if (!Number.isInteger(at.rail) || at.rail < 0 || at.rail > old.length)
+            throw new Error(`no place ${at.rail} — 0 to ${old.length}`);
+        next = [...old.slice(0, at.rail), ...fresh, ...old.slice(at.rail)];
+    }
+    const out = reorderFlowSteps(merged, next);
+    assertNoNewErrors(raw, out, "pasting");
+    const flat = next.flat();
+    return { text: out, indices: pasted.map((i) => flat.indexOf(i)).sort((a, b) => a - b) };
+}
+/** One pattern, applied to a flow file. */
+function applyPatternEditLF(raw, edit) {
+    switch (edit.op) {
+        case "insert":
+            return insertFlowStepLF(raw, edit).text;
+        case "router": {
+            const cases = (edit.cases ?? []).filter((c) => oneLine(c.value ?? "") && c.target);
+            if (!cases.length)
+                throw new Error("a router needs at least one case: and its agent");
+            const head = insertFlowStepLF(raw, { target: edit.router, instruction: edit.instruction, at: { rail: edit.rail } });
+            let text = head.text;
+            const branches = [
+                ...cases.map((c) => ({ target: c.target, options: { case: oneLine(c.value) } })),
+                ...(edit.else ? [{ target: edit.else, options: { else: "true" } }] : []),
+            ];
+            branches.forEach((b, k) => {
+                text = insertFlowStepLF(text, {
+                    target: b.target,
+                    at: k === 0 ? { rail: head.column + 1 } : { column: head.column + 1 },
+                    options: b.options,
+                }).text;
+            });
+            return text;
+        }
+        case "options":
+            return setStepOptionsLF(raw, edit.step, edit.set);
+        case "approve":
+            return setStepApproveLF(raw, edit.step, edit.on);
+        case "remove":
+            return removeStepLF(raw, edit.step);
+        case "duplicate":
+            return duplicateStepLF(raw, edit.step);
+        case "paste":
+            return pasteStepsLF(raw, edit.text, edit.at).text;
+        default:
+            throw new Error(`unknown pattern edit ${edit.op}`);
+    }
+}
+// The flow edits work on LF text: the parser and every line rule here read
+// "\n"-separated lines, and a CRLF line's trailing "\r" defeats them (an
+// option line never matched, so setting it again added a second copy). So
+// each edit takes a CRLF file as LF and gives it back as CRLF.
+export const setStepOptions = (raw, index, set) => asRaw(raw, setStepOptionsLF(toLF(raw), index, set));
+export const setStepApprove = (raw, index, on) => asRaw(raw, setStepApproveLF(toLF(raw), index, on));
+export function insertFlowStep(...[raw, o]) {
+    const r = insertFlowStepLF(toLF(raw), o);
+    return { ...r, text: asRaw(raw, r.text) };
+}
+export const removeStepImpact = (raw, index) => removeStepImpactLF(toLF(raw), index);
+export const removeStep = (raw, index) => asRaw(raw, removeStepLF(toLF(raw), index));
+export const stepSource = (raw, index) => stepSourceLF(toLF(raw), index);
+export const duplicateStep = (raw, index) => asRaw(raw, duplicateStepLF(toLF(raw), index));
+export function pasteSteps(...[raw, text, at]) {
+    const r = pasteStepsLF(toLF(raw), text, at);
+    return { ...r, text: asRaw(raw, r.text) };
+}
+export const applyPatternEdit = (raw, edit) => asRaw(raw, applyPatternEditLF(toLF(raw), edit));
+// ---------- agent files ----------
+/** The frontmatter list fields an agent's team lives in: whom it delegates
+ *  to, whom it consults, and what it may do (`ask` among them). */
+export const TEAM_LIST_KEYS = ["subagents", "agents", "tools"];
+function eolOf(raw) {
+    return raw.includes("\r\n") ? "\r\n" : "\n";
+}
+function frontBounds(lines) {
+    if (lines[0]?.trim() !== "---")
+        return null;
+    for (let i = 1; i < lines.length; i++)
+        if (lines[i].trim() === "---")
+            return { close: i };
+    return null;
+}
+/** A list item as the parser reads it: quotes and [[ ]] stripped. */
+function itemName(raw) {
+    return raw.trim().replace(/^["']|["']$/g, "").replace(/^\[\[|\]\]$/g, "").trim();
+}
+function splitComment(value) {
+    const m = value.match(/^(.*?)(\s+#.*)$/);
+    return m ? { value: m[1], comment: m[2] } : { value, comment: "" };
+}
+function keyLine(lines, close, key) {
+    const re = new RegExp(`^${key.replace(/[-]/g, "\\-")}:(.*)$`);
+    for (let i = 1; i < close; i++) {
+        const m = lines[i].match(re);
+        if (m)
+            return { index: i, rest: m[1] };
+    }
+    return null;
+}
+/** Block-style item lines under a key: `  - name`, until anything else. */
+function blockItems(lines, from, close) {
+    const items = [];
+    for (let i = from + 1; i < close; i++) {
+        const l = lines[i];
+        if (/^\s*-(\s|$)/.test(l))
+            items.push(i);
+        else if (/^\s*(#.*)?$/.test(l))
+            continue; // blank or comment inside the block
+        else
+            break;
+    }
+    return items;
+}
+const blockItemName = (line) => itemName(line.replace(/^\s*-\s*/, "").replace(/\s+#.*$/, ""));
+/** The names a frontmatter list holds, read the way the file says them. */
+export function frontmatterList(raw, key) {
+    const lines = raw.split(eolOf(raw));
+    const b = frontBounds(lines);
+    if (!b)
+        return [];
+    const k = keyLine(lines, b.close, key);
+    if (!k)
+        return [];
+    const v = splitComment(k.rest).value.trim();
+    if (v.startsWith("["))
+        return v.replace(/^\[|\]$/g, "").split(",").map(itemName).filter(Boolean);
+    if (v)
+        return [itemName(v)];
+    return blockItems(lines, k.index, b.close).map((i) => blockItemName(lines[i])).filter(Boolean);
+}
+/**
+ * Add `name` to, or remove it from, the list under `key`, touching only the
+ * lines that list is on. Flow style (`key: [a, b]`) stays flow style, block
+ * style stays block style, a trailing `# comment` stays put, and the other
+ * items keep their spelling. A list emptied by a removal is written
+ * `key: []` rather than deleted: the file still says "none", which for
+ * `tools:` is not the same as saying nothing.
+ */
+export function editFrontmatterList(raw, key, name, action) {
+    const eol = eolOf(raw);
+    const lines = raw.split(eol);
+    const b = frontBounds(lines);
+    if (!b)
+        return action === "remove" ? raw : ["---", `${key}: [${name}]`, "---", ...lines].join(eol);
+    const has = frontmatterList(raw, key).includes(name);
+    if ((action === "add") === has)
+        return raw;
+    const k = keyLine(lines, b.close, key);
+    if (!k) {
+        lines.splice(b.close, 0, `${key}: [${name}]`);
+        return lines.join(eol);
+    }
+    const { value, comment } = splitComment(k.rest);
+    const v = value.trim();
+    if (v) {
+        // Flow style, or a lone scalar (read as a one-item list): that one line.
+        const tokens = v.startsWith("[") ? v.replace(/^\[|\]$/g, "").split(",").map((t) => t.trim()).filter(Boolean) : [v];
+        const next = action === "add" ? [...tokens, name] : tokens.filter((t) => itemName(t) !== name);
+        lines[k.index] = `${key}: [${next.join(", ")}]${comment}`;
+        return lines.join(eol);
+    }
+    const items = blockItems(lines, k.index, b.close);
+    if (action === "add") {
+        const indent = items.length ? lines[items[0]].match(/^(\s*)-/)[1] : "  ";
+        lines.splice(items.length ? items[items.length - 1] + 1 : k.index + 1, 0, `${indent}- ${name}`);
+        return lines.join(eol);
+    }
+    const drop = items.filter((i) => blockItemName(lines[i]) === name);
+    for (const i of [...drop].reverse())
+        lines.splice(i, 1);
+    if (drop.length === items.length)
+        lines[k.index] = `${key}: []${comment}`;
+    return lines.join(eol);
+}
+const YAML_WORDS = /^(true|false|yes|no|on|off|null|~|y|n)$/i;
+/** A YAML scalar for a one-line value: plain when plain reads back as the
+ *  same string, double-quoted (JSON is valid YAML) when it would not. */
+export function yamlScalar(value) {
+    const v = oneLine(value);
+    // Plain in block context may hold anything but ": " and " #", once it
+    // starts with a letter; YAML's words for true/false/null are not strings.
+    const plain = /^[A-Za-z(]/.test(v) && !/:(\s|$)|\s#|\t/.test(v) && !YAML_WORDS.test(v);
+    return plain ? v : JSON.stringify(v);
+}
+/** Set one scalar key — `description:`, `model:`. Replaces its line (and the
+ *  indented lines of a `>`/`|` block under it); absent, it goes right after
+ *  `name:`, or last. */
+export function setFrontmatterScalar(raw, key, value) {
+    const eol = eolOf(raw);
+    const lines = raw.split(eol);
+    const b = frontBounds(lines);
+    const line = `${key}: ${yamlScalar(value)}`;
+    if (!b)
+        return ["---", line, "---", ...lines].join(eol);
+    const k = keyLine(lines, b.close, key);
+    if (k) {
+        const { value: v, comment } = splitComment(k.rest);
+        let end = k.index + 1;
+        if (/^\s*[|>][-+]?\d*\s*$/.test(v) || !v.trim()) {
+            while (end < b.close && /^\s+\S/.test(lines[end]))
+                end++;
+        }
+        lines.splice(k.index, end - k.index, `${line}${comment}`);
+        return lines.join(eol);
+    }
+    const name = keyLine(lines, b.close, "name");
+    lines.splice(name ? name.index + 1 : b.close, 0, line);
+    return lines.join(eol);
+}
+/** A new agent file: the template with the answers to "what is it for"
+ *  and "which model" written into it, the rest as the template wrote it. */
+export function newAgentFile(template, o) {
+    let out = template;
+    if (o.description?.trim())
+        out = setFrontmatterScalar(out, "description", o.description);
+    if (o.model?.trim())
+        out = setFrontmatterScalar(out, "model", o.model);
+    return out;
+}

package/dist/src/gitrepo.d.ts

@@ -35,6 +35,24 @@ export interface RefInfo {
     at: string;
 }
 export declare function listRefs(tenant: string, scope: string, kind: "heads" | "tags"): RefInfo[];
+/**
+ * The commit a restore means by `to`, on main's history:
+ *
+ *   a sha or a prefix of one      that commit
+ *   a branch or tag name          where it points
+ *   an ISO date or time           the last commit on main at or before it
+ *   "3d", "12h", "90m", "2w"      the same, that long ago
+ *
+ * Null when nothing matches — before the first commit, or a name that is
+ * not there. Throws on a `to` that cannot be any of these, so a typo is a
+ * 400 rather than a silent "nothing found".
+ */
+export declare function resolveRestorePoint(tenant: string, scope: string, to: string, now?: number): {
+    sha: string;
+    at: string;
+    by: string;
+    message: string;
+} | null;
 /** The files at a commit, for a browser or a deploy. */
 export declare function listTree(tenant: string, scope: string, ref?: string): {
     path: string;

package/dist/src/gitrepo.js

@@ -207,6 +207,55 @@ export function listRefs(tenant, scope, kind) {
         return { name, sha, subject, at };
     });
 }
+/**
+ * The commit a restore means by `to`, on main's history:
+ *
+ *   a sha or a prefix of one      that commit
+ *   a branch or tag name          where it points
+ *   an ISO date or time           the last commit on main at or before it
+ *   "3d", "12h", "90m", "2w"      the same, that long ago
+ *
+ * Null when nothing matches — before the first commit, or a name that is
+ * not there. Throws on a `to` that cannot be any of these, so a typo is a
+ * 400 rather than a silent "nothing found".
+ */
+export function resolveRestorePoint(tenant, scope, to, now = Date.now()) {
+    const t = to.trim();
+    if (!t || t.startsWith("-"))
+        throw Object.assign(new Error(`not a revision or a time: ${to}`), { status: 400 });
+    if (!headSha(tenant, scope))
+        return null;
+    const dir = repoDir(tenant, scope);
+    let sha = null;
+    const rel = /^(\d+)\s*(m|h|d|w)$/.exec(t);
+    const moment = rel
+        ? now - Number(rel[1]) * { m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 }[rel[2]]
+        : /^\d{4}-\d{2}-\d{2}/.test(t)
+            ? Date.parse(t)
+            : null;
+    if (moment !== null) {
+        if (Number.isNaN(moment))
+            throw Object.assign(new Error(`not a date: ${to}`), { status: 400 });
+        sha = git(dir, ["log", "-1", "--format=%H", `--until=@${Math.floor(moment / 1000)}`, "refs/heads/main"]).trim() || null;
+    }
+    else {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._/-]{0,120}$/.test(t))
+            throw Object.assign(new Error(`not a revision or a time: ${to}`), { status: 400 });
+        for (const ref of [/^[0-9a-f]{4,40}$/.test(t) ? `${t}^{commit}` : null, `refs/heads/${t}^{commit}`, `refs/tags/${t}^{commit}`]) {
+            if (!ref)
+                continue;
+            const r = spawnSync("git", ["--git-dir", dir, "rev-parse", "--verify", "--quiet", ref]);
+            if (r.status === 0) {
+                sha = r.stdout.toString().trim();
+                break;
+            }
+        }
+    }
+    if (!sha)
+        return null;
+    const [at, by, ...msg] = git(dir, ["log", "-1", `--format=%cI${SEP}%ae${SEP}%s`, sha]).trim().split(SEP);
+    return { sha, at, by: by.endsWith("@foldrun") ? by.replace(/@foldrun$/, "") : by, message: msg.join(SEP) };
+}
 /** The files at a commit, for a browser or a deploy. */
 export function listTree(tenant, scope, ref = "refs/heads/main") {
     if (!headSha(tenant, scope, ref))

package/dist/src/host-env.js

@@ -19,6 +19,11 @@
 const EXACT = new Set([
     "PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LANGUAGE",
     "TZ", "TERM", "SHELL", "USER", "LOGNAME",
+    // Where Claude Code / the Agent SDK keeps its config and session
+    // transcripts — the same kind of thing as HOME (a path, not a secret), and
+    // without it an operator cannot keep them out of the host user's
+    // ~/.claude: the box's deploy tests set it to the job's temp (2026-10-02).
+    "CLAUDE_CONFIG_DIR",
     // The host's way to the network is the child's way to the network.
     "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy",
     "SSL_CERT_FILE", "SSL_CERT_DIR",

package/dist/src/kinds.js

@@ -62,7 +62,7 @@ name: ${name}
 description: What this agent is for, in one line.
 model: fast
 effort: high
-tools: [files]
+tools: [write]
 ---
 
 # ${name}