@stringsync/splates 0.0.0-stage → 0.0.45

package/handed-out.d.ts

@@ -0,0 +1,79 @@
+import { type Resource } from "webappwiz/disposable";
+import type { Logger } from "webappwiz/log";
+import { Duration, type Timer, type WallClock } from "webappwiz/time";
+import type { Conversations } from "./conversations.js";
+import { Everywhere } from "./everywhere.js";
+import { type SeenLaneTodos } from "./lane-todos.js";
+import type { LaneRecord } from "./lanes.js";
+import type { TodoState } from "./todo.js";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * How often every handed-out agent is checked again, for a task that landed
+ * or went with no word to its conversation, as from another tree.
+ */
+export declare const SWEEP: Duration;
+/**
+ * Keeps the conversation that handed tasks out, a lane's orchestrator with
+ * `splates add --agent` or a relaying agent with `splates handoff --relay`, up
+ * to date on the agents it handed them to, so it never waits on one that
+ * has gone quiet, a restart included. An agent that is not at work, with its
+ * task still under way and not escalated, gets nothing more done unless that
+ * one acts, so that one is told `[SPLATES IDLE <task>]`, unless it has heard of
+ * the task since the agent last said anything, or, for one that answers to
+ * the person, the person took it in hand. An agent that answers to the one
+ * that handed it out is archived with that one once its task is gone, off the
+ * list. Each is checked as its turn ends, once the conversations' changes
+ * settle, as the project opens, and every `SWEEP`.
+ *
+ * A conversation idle `HEARTBEAT_IDLE` since its last turn, with an agent
+ * that answers to it still at work, is told `[SPLATES HEARTBEAT]`, so it checks
+ * on them rather than wait out a long task with no word to the person. Any
+ * turn it takes before then puts the next one off again. A lane's
+ * orchestrator gets none: its agents talk to the person themselves.
+ *
+ * A lane's orchestrator is told `[SPLATES TODO DONE #N]` as a todo in a lane
+ * it works leaves the list, and `[SPLATES TODO OPEN #N]` as one comes back
+ * open, however that came about, so the todos drive the lane rather than its
+ * agents reporting back. What changed while `splates server` was down is told
+ * once it is back.
+ *
+ * A lane's orchestrator whose lanes are all done, however their last todos
+ * landed, that sits idle on a Working or Waiting report, as though they were
+ * not, is told `[SPLATES LANES DONE]`, once since it last started lanes, so it
+ * ends on its Finished report.
+ */
+export declare class HandedOut implements Resource {
+    #private;
+    private readonly service;
+    private readonly conversations;
+    private readonly everywhere;
+    private readonly lanes;
+    private readonly todos;
+    private readonly seen;
+    private readonly log;
+    private readonly timer;
+    private readonly clock;
+    private constructor();
+    /** Watches `conversations`, checking each handed-out agent at once. */
+    static watch({ service, conversations, everywhere, lanes, todos, seen, log, timer, clock, }: {
+        service: WorktreeService;
+        conversations: Conversations;
+        /**
+         * Every project's conversations, where the one that handed out a task
+         * here may be; this project's alone by default.
+         */
+        everywhere?: Everywhere;
+        /** The lanes on the board, a lane gone from it once it is done. */
+        lanes: () => Promise<LaneRecord[]>;
+        /** Every todo on the list. */
+        todos: () => Promise<TodoState[]>;
+        /** The lane todos as last seen, kept past a restart. */
+        seen: SeenLaneTodos;
+        log: Logger;
+        timer?: Timer;
+        clock?: WallClock;
+    }): HandedOut;
+    /** Checks every handed-out agent again. */
+    sweep(): Promise<void>;
+    dispose(): void;
+}

package/handoff.d.ts

@@ -0,0 +1,23 @@
+import { type Logger } from "webappwiz/log";
+import { type AgentPick, type RosterAgent } from "./roster.js";
+import type { Dispatched } from "./worktree.js";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * Hands a task under way to another agent, which `splates server` starts in its
+ * tree, told `[SPLATES HANDOFF <task>]`, to carry on from where its `SPLATES.md`
+ * says it stands. The new agent answers to the person, as the old one did:
+ * the task's caller goes, so nobody else tells it anything or hears from it,
+ * but for a lane's orchestrator that started the old one, which goes on
+ * hearing when it stops.
+ * With `relay`, for an agent that hands on work it judged another model fits
+ * better, the new agent answers to this conversation instead, as to a lane's
+ * orchestrator: it reports back here, and is told what the person says.
+ * Only the conversation working the task hands it off; one that answers to an
+ * orchestrator escalates instead, for the orchestrator to decide.
+ */
+export declare function handoff({ service, log }: {
+    service: WorktreeService;
+    log: Logger;
+}, task: string, to: Omit<Dispatched, "conversation" | "pending" | "handoff" | "relay">, agents: RosterAgent[], { relay }?: {
+    relay?: boolean;
+}): Promise<AgentPick>;

package/heavy-run.d.ts

@@ -0,0 +1,12 @@
+import type { Logger } from "webappwiz/log";
+import type { Fs, HeavyCap, Ps } from "webappwiz/system";
+/**
+ * Runs `argv` in one of the machine's heavy-job slots, waiting for one to
+ * come free first, and says how it exited. What an agent runs itself (a full
+ * test run, an install) passes through splates no other way.
+ */
+export declare function runHeavy(ctx: {
+    fs: Fs;
+    ps: Ps;
+    log: Logger;
+}, argv: string[], heavy?: HeavyCap): Promise<number>;

package/heavy.d.ts

@@ -0,0 +1,28 @@
+import type { Logger } from "webappwiz/log";
+import { type Fs, HeavyJobs, type Ps } from "webappwiz/system";
+/**
+ * How many heavy jobs run at once on a machine when `SPLATES_HEAVY_JOBS` says
+ * nothing. One `splates dev test` takes about 7 cores and 7.3 GB, so two
+ * bound the spike near 15 GB on a 64 GB Mac running two dozen sessions.
+ */
+export declare const HEAVY_JOBS_DEFAULT = 2;
+/** Sets the cap for the machine, read by every splates that takes a slot. */
+export declare const HEAVY_JOBS = "SPLATES_HEAVY_JOBS";
+/**
+ * What runs in a slot finds this in its environment: a heavy job it starts,
+ * such as the test run of a `preMerge` hook, runs in that slot too.
+ */
+export declare const HEAVY_HELD = "SPLATES_HEAVY";
+/**
+ * This machine's heavy-job slots, under the home `splates server --slot` names its
+ * servers' machine by, else `SPLATES_HOME`, so every server on one machine
+ * shares one cap; capped by `SPLATES_HEAVY_JOBS`. `splates dev test` takes one
+ * here too.
+ */
+export declare function heavyJobsOfMachine({ fs, ps, log, }: {
+    fs: Fs;
+    ps: Ps;
+    log: Logger;
+}): HeavyJobs;
+/** The cap `SPLATES_HEAVY_JOBS` names, or the default for none or nonsense. */
+export declare function capOf(value: string | undefined): number;

package/heavy.js

@@ -0,0 +1,16 @@
+import {
+  HEAVY_JOBS_DEFAULT2,
+  HEAVY_JOBS2,
+  HEAVY_HELD2,
+  heavyJobsOfMachine2,
+  capOf2
+} from "./index-xmfmy729.js";
+import"./index-43pq33n4.js";
+import"./index-k73tsw5g.js";
+export {
+  HEAVY_HELD2 as HEAVY_HELD,
+  HEAVY_JOBS2 as HEAVY_JOBS,
+  HEAVY_JOBS_DEFAULT2 as HEAVY_JOBS_DEFAULT,
+  capOf2 as capOf,
+  heavyJobsOfMachine2 as heavyJobsOfMachine
+};

package/held.d.ts

@@ -0,0 +1,22 @@
+import type { ProcessEntry } from "webappwiz/system";
+/** A command a restart would kill: where it runs, and what it runs. */
+export interface Held {
+    /** The agent that left it running, or `terminal` for a page's shell. */
+    where: string;
+    command: string;
+}
+/**
+ * What a restart would kill, from the process table: the job in front in
+ * each of the page's `shells`, and each command an idle agent in `agents`
+ * left running, in a shell under the agent leading a process group of its
+ * own, as an agent runs each command. Its MCP servers, and the shells and
+ * browsers they start in the agent's group, are not commands it ran, so they
+ * hold nothing.
+ */
+export declare function heldBy(table: ProcessEntry[], { shells, agents, }: {
+    shells: number[];
+    agents: {
+        name: string;
+        pid: number;
+    }[];
+}): Held[];

package/index-0tfvy823.js

@@ -0,0 +1,272 @@
+// skill-checks.ts
+function judge2(transcript, end) {
+  return Object.fromEntries(CHECKS2.map((check) => [check.id, check.judge(transcript, end)]));
+}
+var CHECKS2 = [
+  {
+    id: "plan-first",
+    rule: "Writes SPLATES.md before the first edit",
+    judge: ({ beats }) => added(beats).flatMap(({ at, task }, index, all) => {
+      const until = all[index + 1]?.at ?? beats.length;
+      const span = beats.slice(at + 1, until);
+      const edit = span.findIndex((each) => each.kind === "edit" && each.paths.some((path) => !isPlan(path)));
+      if (edit === -1) {
+        return [];
+      }
+      const planned = span.slice(0, edit).some(writesPlan);
+      return [
+        {
+          ok: planned,
+          why: planned ? `${task}: SPLATES.md came first` : `${task}: edited before writing SPLATES.md`
+        }
+      ];
+    })
+  },
+  {
+    id: "report-title",
+    rule: "Titles a task's report by how it ended",
+    judge: ({ beats }) => endings(beats).map(({ verb, review, report }) => {
+      const title = titleOf(report);
+      const form = review ? TITLES.review : TITLES[verb];
+      return {
+        ok: form.test(title),
+        why: `${review ? "review" : verb}: ${title ? `"${title}"` : "no report"}`
+      };
+    })
+  },
+  {
+    id: "numbered-questions",
+    rule: "Asks two or more questions as a numbered list",
+    judge: ({ beats }) => turns(beats).flatMap(({ report }) => {
+      const asked = questionLines(report);
+      if (asked.length < 2) {
+        return [];
+      }
+      const loose = asked.filter((line) => !NUMBERED.test(line));
+      return [
+        {
+          ok: loose.length === 0,
+          why: loose.length === 0 ? `${asked.length} questions, all numbered` : `not numbered: "${loose[0]?.trim()}"`
+        }
+      ];
+    })
+  },
+  {
+    id: "next-todo",
+    rule: "Proposes the next todo after a merge or remove",
+    judge: ({ beats, handed }) => handed ? [] : endings(beats).filter(({ verb, output }) => verb === "remove" || verb === "merge" && PROPOSED.test(output)).map(({ verb, report }) => {
+      const ok = TODO_HEADING.test(report);
+      return {
+        ok,
+        why: `${verb}: ${ok ? "proposed one" : "proposed none"}`
+      };
+    })
+  },
+  {
+    id: "squashed",
+    rule: "Lands one commit with no attribution",
+    judge: (_, { landed }) => landed.map(({ task, commits }) => {
+      const attributed = commits.find((message) => ATTRIBUTION.some((pattern) => pattern.test(message)));
+      return {
+        ok: commits.length === 1 && attributed === undefined,
+        why: commits.length !== 1 ? `${task}: landed ${commits.length} commits` : attributed === undefined ? `${task}: one plain commit` : `${task}: attributed`
+      };
+    })
+  },
+  {
+    id: "setup-read-first",
+    rule: "Reads a setup step before acting on it",
+    judge: ({ beats }) => setups(beats).flatMap(({ step, span }) => {
+      const first = span.find((beat) => beat.kind === "edit" || beat.kind === "run" && splatesCalls2(beat.command).length > 0);
+      if (first === undefined) {
+        return [];
+      }
+      const ok = checks(first, step);
+      return [
+        {
+          ok,
+          why: ok ? `${step}: read it first` : `${step}: acted before reading it`
+        }
+      ];
+    })
+  },
+  {
+    id: "setup-checked",
+    rule: "Checks a setup step after each change",
+    judge: ({ beats }) => setups(beats).flatMap(({ step, span }) => turns(span).flatMap(({ beats: turn }) => {
+      const last = turn.findLastIndex(acts);
+      if (last === -1) {
+        return [];
+      }
+      const ok = turn.slice(last + 1).some((beat) => checks(beat, step));
+      return [
+        {
+          ok,
+          why: ok ? `${step}: checked after the last change` : `${step}: changed without checking after`
+        }
+      ];
+    }))
+  },
+  {
+    id: "setup-one-step",
+    rule: "Stays on the setup step it was asked about",
+    judge: ({ beats }) => setups(beats).map(({ step, span }) => {
+      const next = span.findIndex((beat, at) => at > 0 && beat.kind === "user");
+      const other = (next === -1 ? span : span.slice(0, next)).flatMap((beat) => beat.kind === "run" ? splatesCalls2(beat.command) : []).flatMap(({ verb, args }) => verb === "setup" ? args.filter((arg) => !arg.startsWith("-") && arg !== step) : [])[0];
+      return {
+        ok: other === undefined,
+        why: other === undefined ? `${step}: kept to it` : `${step}: went on to ${other} unasked`
+      };
+    })
+  }
+];
+var SETUP = /^\s*\[(?:SPLATES|ARBOR) SETUP ([^\]\s]+)\]/;
+function setups(beats) {
+  const asks = beats.flatMap((beat, at) => {
+    const step = beat.kind === "user" ? SETUP.exec(beat.text)?.[1] : undefined;
+    return step === undefined ? [] : [{ at, step }];
+  });
+  return asks.map(({ at, step }, index) => ({
+    step,
+    span: beats.slice(at, asks[index + 1]?.at ?? beats.length)
+  }));
+}
+function checks(beat, step) {
+  return beat.kind === "run" && splatesCalls2(beat.command).some(({ verb, args }) => verb === "setup" && args.includes(step));
+}
+function acts(beat) {
+  if (beat.kind === "edit") {
+    return true;
+  }
+  return beat.kind === "run" && splatesCalls2(beat.command).some(({ verb, args }) => verb !== "setup" && !(verb === "creds" && ["wait", "list"].includes(args[0] ?? "")));
+}
+var TITLES = {
+  merge: /^## ✅ Merged \S+ onto \S+$/,
+  remove: /^## 🛑 Removed \S+: .*[^.!?:]$/,
+  escalate: /^## ⚠️? Escalated \S+: .*[^.!?:]$/,
+  review: /^## 🔍 Ready to merge \S+ onto \S+$/
+};
+var TODO_HEADING = /^### 📝 .+ \[#\d+\]\s*$/m;
+var PROPOSED = /splates add <task> --todo \d+/;
+var NUMBERED = /^\s*\d+\.\s/;
+var ATTRIBUTION = [/^co-authored-by:/im, /generated (with|by)/i, /🤖/u];
+var SPLATES = /(?:^|[;&|(\n])\s*(?:[A-Z_][A-Z0-9_]*=\S*\s+)*(?:(?:bunx|npx)\s+)?(?:\S*\/)?splates(?:@\S+)?\s+([a-z]+)([^;&|\n]*)/g;
+function splatesCalls2(command) {
+  return [...command.matchAll(SPLATES)].map((match) => ({
+    verb: match[1],
+    args: words(match[2])
+  }));
+}
+function words(text) {
+  return [...text.matchAll(/'([^']*)'|"((?:\\.|[^"\\])*)"|(\S+)/g)].map((match) => match[1] ?? match[2] ?? match[3] ?? "");
+}
+var DONE = /^(added|merged|removed|escalated) (?!todo \d)(\S+)/gm;
+var VERBS = {
+  added: "add",
+  merged: "merge",
+  removed: "remove",
+  escalated: "escalate"
+};
+var COLOR = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+function events(beats) {
+  return beats.flatMap((beat, at) => {
+    if (beat.kind !== "run" || /\bSPLATES_HOME=/.test(beat.command)) {
+      return [];
+    }
+    const calls = splatesCalls2(beat.command);
+    const output = beat.output.replace(COLOR, "");
+    return [...output.matchAll(DONE)].flatMap((match) => {
+      const verb = VERBS[match[1]];
+      const task = match[2];
+      const call = calls.find((each) => each.verb === verb);
+      if (call === undefined) {
+        return [];
+      }
+      const named = calls.find((each) => each.verb === verb && each.args.includes(task));
+      const args = (named ?? call).args;
+      const base = args[args.indexOf("--base") + 1];
+      return [
+        {
+          at,
+          verb,
+          task,
+          own: !args.includes("--agent") && !(args.includes("--base") && base?.startsWith("task/")),
+          review: args.includes("--review"),
+          output
+        }
+      ];
+    });
+  });
+}
+function added(beats) {
+  return events(beats).filter((each) => each.verb === "add" && each.own);
+}
+function turns(beats) {
+  const found = [];
+  beats.forEach((beat, at) => {
+    if (beat.kind === "user" || found.length === 0) {
+      found.push({ from: at, beats: [], report: "" });
+    }
+    found.at(-1)?.beats.push(beat);
+  });
+  for (const turn of found) {
+    turn.report = said(turn.beats);
+  }
+  return found;
+}
+function said(beats) {
+  const last = beats.findLast((beat) => beat.kind === "say");
+  return last?.kind === "say" ? last.text : "";
+}
+function endings(beats) {
+  const all = events(beats);
+  return turns(beats).flatMap(({ from, beats: turn }) => {
+    const to = from + turn.length;
+    const inTurn = all.filter((each) => each.at >= from && each.at < to);
+    return inTurn.flatMap((each, index) => {
+      if (each.verb === "add") {
+        return [];
+      }
+      const next = inTurn[index + 1];
+      if (next !== undefined && next.verb !== "add") {
+        return [];
+      }
+      const until = next?.at ?? to;
+      return [
+        {
+          ...each,
+          verb: each.verb,
+          report: said(beats.slice(each.at + 1, until))
+        }
+      ];
+    });
+  });
+}
+function titleOf(report) {
+  return report.trim().split(`
+`)[0]?.trim() ?? "";
+}
+function questionLines(text) {
+  let fenced = false;
+  return text.split(`
+`).filter((line) => {
+    if (/^\s*(```|~~~)/.test(line)) {
+      fenced = !fenced;
+      return false;
+    }
+    const trimmed = line.trim().replace(/\**$/, "");
+    return !fenced && trimmed.endsWith("?") && !trimmed.startsWith("#") && !trimmed.startsWith(">");
+  });
+}
+function isPlan(path) {
+  return path === "SPLATES.md" || path.endsWith("/SPLATES.md");
+}
+var WRITES = />>?[^;&|\n]*SPLATES\.md|\btee\b[^;&|\n]*SPLATES\.md|\s-i\b|\.write(_text)?\(|open\([^)]*,\s*['"][wa]/;
+function writesPlan(beat) {
+  if (beat.kind === "edit") {
+    return beat.paths.some(isPlan);
+  }
+  return beat.kind === "run" && beat.command.includes("SPLATES.md") && WRITES.test(beat.command);
+}
+
+export { judge2, CHECKS2, splatesCalls2 };

package/index-43pq33n4.js

@@ -0,0 +1,157 @@
+import {
+  LEGACY_DIR,
+  unmigrated
+} from "./index-k73tsw5g.js";
+import {
+  fail
+} from "./index-kaa44k7q.js";
+
+// roster.ts
+import { homedir } from "node:os";
+import { z } from "zod";
+class Roster2 {
+  path;
+  deps;
+  constructor(path, deps) {
+    this.path = path;
+    this.deps = deps;
+  }
+  async seed() {
+    if (await this.deps.fs.exists(this.path)) {
+      return false;
+    }
+    await this.deps.fs.mkdir(this.path.slice(0, this.path.lastIndexOf("/")));
+    const tmp = `${this.path}.${crypto.randomUUID()}.tmp`;
+    await this.deps.fs.write(tmp, `${JSON.stringify({ format: FORMAT, agents: DEFAULT_AGENTS }, null, "\t")}
+`);
+    await this.deps.fs.rename(tmp, this.path);
+    return true;
+  }
+  async agents() {
+    const raw = await this.deps.fs.read(this.path).catch(() => null);
+    if (raw === null) {
+      return DEFAULT_AGENTS;
+    }
+    let json;
+    try {
+      json = JSON.parse(raw);
+    } catch {
+      fail("usage", `${this.path} is not JSON: fix or delete it`, {
+        path: this.path
+      });
+    }
+    const format = json?.format;
+    if (typeof format === "number" && format > FORMAT) {
+      fail("outdated", [
+        `${this.path} is in format ${format}, written by a newer splates; this one understands up to ${FORMAT}, so it leaves it alone.`,
+        "Run `bunx @stringsync/splates@latest` instead."
+      ].join(`
+`), { path: this.path, format, understood: FORMAT });
+    }
+    const parsed = schema.safeParse(json);
+    if (!parsed.success) {
+      const issue = parsed.error.issues[0];
+      fail("usage", `${this.path} is not a roster: ${issue?.path.join(".") || "the file"}: ${issue?.message}. Fix it, or delete it for the defaults`, { path: this.path });
+    }
+    const agents = parsed.data.agents;
+    const twice = agents.find((agent, i) => agents.findIndex((each) => each.id === agent.id) !== i);
+    if (twice !== undefined) {
+      fail("usage", `${this.path} lists agent '${twice.id}' twice: give each its own id`, { path: this.path, agent: twice.id });
+    }
+    return agents;
+  }
+}
+var FORMAT = 1;
+var schema = z.object({
+  format: z.number().int().positive().optional(),
+  agents: z.array(z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    argv: z.array(z.string()).min(1),
+    models: z.array(z.object({
+      id: z.string().min(1),
+      name: z.string().min(1),
+      strengths: z.string(),
+      cost: z.string()
+    }))
+  }))
+});
+var DEFAULT_AGENTS = [
+  {
+    id: "claude",
+    name: "Claude",
+    argv: ["bunx", "@agentclientprotocol/claude-agent-acp"],
+    models: [
+      {
+        id: "fable",
+        name: "Fable 5.1",
+        strengths: "the toughest and longest-running work",
+        cost: "highest"
+      },
+      {
+        id: "opus",
+        name: "Opus 5.5",
+        strengths: "complex work and everyday tasks; Claude's default",
+        cost: "high"
+      },
+      {
+        id: "sonnet",
+        name: "Sonnet 5.5",
+        strengths: "simpler, well-specified tasks",
+        cost: "medium"
+      },
+      {
+        id: "haiku",
+        name: "Haiku 5.5",
+        strengths: "quick answers and mechanical edits",
+        cost: "low"
+      }
+    ]
+  },
+  {
+    id: "codex",
+    name: "Codex",
+    argv: ["bunx", "@agentclientprotocol/codex-acp"],
+    models: [
+      {
+        id: "gpt-6-astra",
+        name: "6 Astra",
+        strengths: "Codex's default, for complex work",
+        cost: "high"
+      },
+      {
+        id: "gpt-6-luna",
+        name: "6 Luna",
+        strengths: "easier tasks, fast",
+        cost: "low"
+      }
+    ]
+  }
+];
+function modelsOf(agent) {
+  return "models" in agent ? agent.models : [];
+}
+function pickLabel(pick) {
+  return pick.model === undefined ? pick.agent : `${pick.agent} (${pick.model})`;
+}
+function pickAgent(agents, agent, model, data = {}) {
+  const found = agents.find((each) => each.id === agent);
+  if (found === undefined) {
+    fail("usage", `no agent '${agent}' on the roster: use one of ${agents.map((each) => each.id).join(", ")} (\`splates agents\` lists them; ~/.splates/agents.json keeps them)`, { ...data, agent });
+  }
+  if (model === undefined || found.models.length === 0) {
+    return model === undefined ? { agent } : { agent, model };
+  }
+  const wanted = model.toLowerCase();
+  const picked = found.models.find((each) => each.id === model || agent !== "opencode" && !model.includes("/") && !each.id.includes("/") && (each.id.toLowerCase() === wanted || each.name.toLowerCase() === wanted));
+  if (picked === undefined) {
+    fail("usage", `${found.name} has no model '${model}' on the roster: use one of ${found.models.map((each) => each.id).join(", ")}`, { ...data, agent, model });
+  }
+  return { agent, model: picked.id };
+}
+function splatesHome(ps) {
+  const home = ps.env("HOME") ?? homedir();
+  return ps.env("SPLATES_HOME") ?? unmigrated(`${home}/.splates`, `${home}/.${LEGACY_DIR}`);
+}
+
+export { Roster2, DEFAULT_AGENTS, modelsOf, pickLabel, pickAgent, splatesHome };