@stringsync/splates 0.0.45 → 0.0.46

package/README.md

@@ -19,7 +19,7 @@ installs the same skill. From then on, your agents start each change with
 
 Spinning Plates was arbor (`@webappwiz/arbor`). In a project that used it, run
 `bunx @stringsync/splates update`: it installs the splates skill in place of arbor's and
-renames `arbor.config.ts` and `arbor.systems.ts`. The next `splates server` moves
+renames `arbor.config.ts`. The next `splates server` moves
 `~/.arbor` and each repository's `.git/arbor` to their new names, leaving links
 behind. For one release, `arbor` still runs splates, and the `ARBOR_*`
 variables, `ARBOR.md` and the `[ARBOR …]` directives are still read.
@@ -40,7 +40,10 @@ and is absent from the published CLI.
 **Merging.** `splates merge` rebases the task onto `main`, runs your checks
 (`preMerge` in `splates.config.ts`) on the result, fast-forwards `main`, and
 removes the worktree. A conflict or a failing check goes back to the agent that
-made the change, which fixes it and merges again.
+made the change, which fixes it and merges again. A check that writes a JUnit
+XML report to `$SPLATES_TEST_REPORT` (`bun test --reporter=junit
+--reporter-outfile="$SPLATES_TEST_REPORT"`) gets a todo for each test slower
+than 5 seconds.
 
 **Heavy jobs.** Hooks (`postCheckout`, `postRewrite`, `preMerge`) run in one
 of the machine's heavy-job slots, two by default (`SPLATES_HEAVY_JOBS` sets
@@ -48,6 +51,62 @@ how many), so several agents testing at once queue rather than run the
 machine out of memory. `splates heavy -- <command>` runs anything else as
 heavy, such as a test suite an agent runs mid-task, in a slot too.
 
+**Pushing.** With `remote: "origin"` in `splates.config.ts`, each task's
+branch goes to that remote as `splates/<task>`: after every commit an agent
+makes under `splates server`, at `splates checkpoint`, escalation and handoff,
+and it is deleted once the task merges or is removed. `splates checkpoint`
+commits uncommitted work first, as a `WIP: checkpoint` commit squashed before
+merging. A branch that tracks `SPLATES.md` is never pushed or merged. With the
+GitHub App's id and private key kept as the creds `SPLATES_GITHUB_APP_ID` and
+`SPLATES_GITHUB_APP_KEY`, pushes to github.com use an hour-long token the App
+mints for that repository's contents alone; otherwise, the machine's own git
+credentials. Without `remote`, nothing is pushed.
+
+With `remote`, `main` is the remote's: `splates merge` fetches it, rebases
+onto it, runs the checks, pushes the tested `splates/<task>`, and asks
+`splates server`, the coordinator, to move `main` there. The coordinator alone
+pushes `main`, with its machine's own git credentials, and only when the
+remote's `main` is still the commit the checks ran on; then it fast-forwards
+its own `main` checkout. A merge refuses while the local `main` holds commits
+the remote lacks, until they are pushed. Protect `main` with a ruleset that
+lets only the coordinator's identity update it, and every tag with one, so the
+App's tokens, which workers push with, reach `splates/*` alone.
+
+Setup's GitHub pushing area walks through it for the project it is opened
+from (`splates setup` in its repository, or the page on that project), each
+step checked against GitHub:
+
+1. `github-app`: [make a GitHub App](https://github.com/settings/apps/new)
+   with Webhook off and Repository permissions **Contents: Read and write**
+   alone, and keep its App ID and a private key it generates as the device
+   creds above.
+2. `github-install`: install it on the project's repository alone.
+3. `github-ruleset`: in the repository's **Settings → Rules → Rulesets**,
+   two active rulesets that restrict creations, updates and deletions, with
+   only **Repository admin** allowed to bypass them, the role of the account
+   the coordinator pushes `main` with: a branch ruleset on **All branches**
+   but `splates/*`, and a tag ruleset on **All tags**, since the App's
+   Contents permission would let a token push or move a release tag. GitHub
+   has no token that pushes branches but not tags. Or, with your own `gh`
+   sign-in, once for each body:
+
+   ```sh
+   gh api --method POST repos/<owner>/<repo>/rulesets --input - <<'JSON'
+   {"name":"splates","target":"branch","enforcement":"active",
+    "conditions":{"ref_name":{"include":["~ALL"],"exclude":["refs/heads/splates/*"]}},
+    "rules":[{"type":"creation"},{"type":"update"},{"type":"deletion"}],
+    "bypass_actors":[{"actor_id":5,"actor_type":"RepositoryRole","bypass_mode":"always"}]}
+   JSON
+   gh api --method POST repos/<owner>/<repo>/rulesets --input - <<'JSON'
+   {"name":"splates-tags","target":"tag","enforcement":"active",
+    "conditions":{"ref_name":{"include":["~ALL"],"exclude":[]}},
+    "rules":[{"type":"creation"},{"type":"update"},{"type":"deletion"}],
+    "bypass_actors":[{"actor_id":5,"actor_type":"RepositoryRole","bypass_mode":"always"}]}
+   JSON
+   ```
+
+4. `github-push`: add `remote: "origin"` to `splates.config.ts` and merge it.
+
 **Escalating.** When an agent needs you (a decision, access, a review, or
 merges that keep failing), it runs `splates escalate`: it stops, leaves its
 worktree as it is, and writes down its questions. You answer, and it picks up
@@ -156,8 +215,8 @@ To use another tunnel, give `splates.config.ts` a `tunnel`, any object that
 implements `TunnelProvider`:
 
 ```ts
-import type { ConfigFile } from "@stringsync/splates/config";
-import type { TunnelProvider } from "@stringsync/splates/tunnel-provider";
+import type { ConfigFile } from "@stringsync/splates-server/config";
+import type { TunnelProvider } from "@stringsync/splates-server/tunnel";
 
 const myTunnel: TunnelProvider = {
 	// throw, saying what to do, unless the tunnel can run
@@ -178,6 +237,59 @@ traffic, and `--tunnel-name` is refused beside a provider of your own. One
 that is not ready, or fails to start, is logged and skipped: the page keeps
 serving on this machine.
 
+### Worker providers
+
+To have splates make workers when agents queue for want of a slot, give
+`splates.config.ts`, in the repo `splates server` starts in, a
+`workerProvider`, any object that implements `WorkerProvider`:
+
+```ts
+import type { ConfigFile } from "@stringsync/splates-server/config";
+import type { WorkerProvider } from "@stringsync/splates-server/workers";
+
+const myCloud: WorkerProvider = {
+	// the machines it makes, with what each costs you per hour
+	types: async () => [
+		{ name: "small", platform: "linux", slots: 4, dollarsPerHour: 0.05 },
+	],
+	// build an image by running recipe.script as root on a fresh machine
+	snapshot: async (recipe) => ({ id: "img-1", version: recipe.version, builtAt: Date.now() }),
+	// boot spec.snapshot and run spec.boot on it, as the `splates` user
+	create: async (spec) => ({ id: spec.id, type: spec.type }),
+	destroy: async (id) => {},
+	// the machines it made that still exist
+	list: async () => [],
+};
+
+export default { workerProvider: myCloud } satisfies ConfigFile;
+```
+
+A made worker boots from a snapshot splates asks for when there is none, and
+again when splates's version changes or the snapshot is a week old; it holds
+bun, git, the browser and splates, and no credentials. Its boot command spends
+a single-use join token, dialing the page at its tunnel host, so the server
+needs a tunnel. Placement makes one only once agents other agents started are
+queued, and only as far as the worker budget allows; none is kept warm.
+`splates worker add --provider [--type <name>]` makes one by hand, past the
+rate cap, and `splates worker remove` destroys its machine.
+
+The worker budget is in dollars, at each type's list price, so every figure is
+an estimate: a rate cap on what the made workers running at once cost an hour
+($0.25/h by default), and limits on what they cost in a day ($5) and a month
+($75), from the start of each in local time. Past the rate cap no worker is
+made, and the queue says which limit holds it, as `rate cap $0.25/h reached`.
+Once a day's or month's limit is spent, made workers take nothing new, their
+agents are asked to stop at a checkpoint, and each is destroyed once its last
+agent ends. Each limit warns at 80%, 90% and 100%, once in its window, by Web
+Push and on the page's header. Agents' own API spend is not counted here.
+
+```bash
+bunx @stringsync/splates budget show
+bunx @stringsync/splates budget set day 10        # or `default`
+bunx @stringsync/splates budget raise hour 0.1 --for 1d
+bunx @stringsync/splates budget end 1             # a raise, by its number
+```
+
 ### Task ports
 
 Any port a task's processes listen on, in its worktree or under its agent, is
@@ -200,7 +312,7 @@ with its remote and local links, as the task's dialog on the page does.
 As each task merges or is removed, splates writes down how it went in
 `~/.splates/outcomes.jsonl`: how many times it came to you with questions or for
 a review, how many merges failed and why, how many of the agent's picks you
-overturned or took with words added, how long it waited on you, the systems it touched, why it was
+overturned or took with words added, how long it waited on you, why it was
 removed, and the agent and model behind it. The Stats page sums it over the
 last 6 hours, day, 3 days or 7 days, cut into bars of half an hour to six
 hours, or over all time a bar a week, by model, project and system, so you can tell whether tasks are landing
@@ -241,7 +353,7 @@ existing conversations and native authentication remain.
 #### Advanced manual reference
 
 Manual roster editing remains available for custom launches; use the supported
-V2 recipe and inspection commands in [the setup contracts](design/opencode-acp.md#374-readiness-and-completion).
+V2 recipe and inspection commands in [the setup contracts](../../designs/opencode-acp.md#374-readiness-and-completion).
 A plain `opencode acp` entry or custom command does not establish wizard readiness.
 Custom commands are never replaced or removed automatically. Avoid the older V1
 `small_model`/provider recipe: it does not pin every V2 auxiliary/custom agent.
@@ -271,7 +383,7 @@ fixtures, not a recorded OpenCode executable. `opencode` was absent from the
 implementation environment's PATH, so no executable version or live login was
 verified and no minimum supported version is claimed. Production acceptance
 requires recording a version and sanitized handshake separately; no paid smoke
-test was run. See [the experiment plan](design/opencode-acp.md) for opt-in setup,
+test was run. See [the experiment plan](../../designs/opencode-acp.md) for opt-in setup,
 provider restrictions, and the separate paid-overflow control. Fixture checks
 never establish account entitlement or remaining quota.
 
@@ -285,7 +397,7 @@ charges; it is not a subscription invoice. Quota and mixed-model remaining
 allowance stay unknown: consult OpenCode Console and keep **Use balance** disabled.
 Legacy task cost/token aggregates exclude these differently scoped observations.
 
-See [the manual comparison recipe](design/opencode-acp.md#354-implementation-and-manual-comparison-record)
+See [the manual comparison recipe](../../designs/opencode-acp.md#354-implementation-and-manual-comparison-record)
 for identical baseline files, a results worksheet, provenance and the authorization
 gate. Fixtures need no production login. Live executable compatibility remains
 unverified and no real comparison was run. `splates dev fix --code-only` disables
@@ -305,5 +417,5 @@ Installation/connection is the first part of this wizard. Model selection and
 configuration (#373), then final conversation readiness (#374), remain separate
 lane steps. Until those land, this step does not add an agent roster entry. A
 stored credential and ACP handshake do not verify subscription access, billing,
-model availability or inference. See the [setup contract](design/opencode-acp.md#372-setup-wizard-contract-lane-53-step-1)
+model availability or inference. See the [setup contract](../../designs/opencode-acp.md#372-setup-wizard-contract-lane-53-step-1)
 for exact files and supported interfaces.

package/artifact.d.ts

@@ -1,30 +1,3 @@
-import { type Logger } from "webappwiz/log";
-import type { Fs, Ps } from "webappwiz/system";
-import { type ArtifactVersion } from "./artifacts.js";
-import type { WorktreeService } from "./worktree-service.js";
-/** What `fetch` is used for here, so a test can stand in for it. */
-type Send = (url: string, init: RequestInit) => Promise<Response>;
-export interface ArtifactDeps {
-    service: WorktreeService;
-    log: Logger;
-    fs: Fs;
-    ps: Ps;
-    send?: Send;
-}
-/**
- * Keeps `file` as the next version of the artifact of that name in the
- * conversation `id`, through the `splates server` serving this repository when
- * the agent has one in its env, so the page hears of it, else straight into
- * the conversation's log.
- */
-export declare function addArtifact(deps: ArtifactDeps, id: string, file: {
-    name: string;
-    bytes: Uint8Array;
-}): Promise<ArtifactVersion>;
-/** Marks the artifact `name` of conversation `id` removed; answers the version that was current. */
-export declare function removeArtifact(deps: ArtifactDeps, id: string, name: string): Promise<number>;
-/** Prints what the conversation `id` holds, or, given a `name`, that artifact's versions. */
-export declare function listArtifacts(deps: ArtifactDeps, id: string, name?: string): Promise<void>;
-/** The media type `name`'s extension says, else plain bytes. */
-export declare function mimeTypeOf(name: string): string;
-export {};
+import type { SplatesDeps } from "@stringsync/splates-server/server";
+/** `splates artifact`, which the root cli mounts after `splates attach`. */
+export declare const splatesArtifact: import("webappwiz/cmd").Cli<SplatesDeps, SplatesDeps>;

package/budget.d.ts

@@ -0,0 +1,3 @@
+import type { SplatesDeps } from "@stringsync/splates-server/server";
+/** `splates budget`, which the root cli mounts beside `splates worker`. */
+export declare const splatesBudget: import("webappwiz/cmd").Cli<SplatesDeps, SplatesDeps>;

package/coordinator.d.ts

@@ -0,0 +1,3 @@
+import { type SplatesDeps } from "@stringsync/splates-server/server";
+/** `splates coordinator`, which the root cli mounts after `splates budget`. */
+export declare const splatesCoordinator: import("webappwiz/cmd").Cli<SplatesDeps, SplatesDeps>;

package/creds.d.ts

@@ -1,123 +1,3 @@
-import { Credentials, type SecretStore } from "webappwiz/creds";
-import { type Fs, type Lock } from "webappwiz/system";
-import { Duration } from "webappwiz/time";
-import { z } from "zod";
-/** Where a cred is kept: for this project alone, or every project on this device. */
-export declare const SCOPES: readonly ["project", "device"];
-export type Scope = (typeof SCOPES)[number];
-/** How long `wait` gives a request before handing the wait back to its caller. */
-export declare const DEFAULT_TIMEOUT: Duration;
-/** The two stores a cred can be kept in, the system's unless a test says otherwise. */
-export interface SecretStores {
-    /** The store of the project whose main tree is at `root`. */
-    project(root: string): Promise<SecretStore>;
-    device: SecretStore;
-}
-/** The operating system's own stores, shared with `wiz creds`. */
-export declare const SYSTEM_STORES: SecretStores;
-declare const REQUEST: z.ZodObject<{
-    name: z.ZodString;
-    scope: z.ZodEnum<{
-        device: "device";
-        project: "project";
-    }>;
-    purpose: z.ZodDefault<z.ZodString>;
-    instructions: z.ZodString;
-    task: z.ZodNullable<z.ZodString>;
-    status: z.ZodEnum<{
-        dismissed: "dismissed";
-        open: "open";
-        saved: "saved";
-    }>;
-    requestedAt: z.ZodString;
-}, z.core.$strip>;
-/** A cred an agent asked a person for, with what for and how to get it. */
-export type CredRequest = z.infer<typeof REQUEST>;
-/** A cred a store keeps, by name; never its value. */
-export interface KeptCred {
-    name: string;
-    scope: Scope;
-    /** The tool that saved it, when one said so; null when a person did. */
-    savedBy: string | null;
-}
-/**
- * A project's creds: the requests agents make for them, which `splates server`
- * shows on its Creds page for a person to fill, and the two stores they are
- * kept in, the project's and the device's, as `wiz creds` keeps them. A value
- * goes into a store and never comes out through here but to code reading it
- * through `credentials`, so no agent, page or log ever holds it.
- */
-export declare class Creds {
-    #private;
-    /** The record of requests, `.git/splates/creds.json`. */
-    readonly file: string;
-    /** Held while the record is read and written back. */
-    private readonly lock;
-    private readonly stores;
-    constructor(
-    /** The record of requests, `.git/splates/creds.json`. */
-    file: string, 
-    /** Held while the record is read and written back. */
-    lock: Lock, stores: Record<Scope, SecretStore>, opts?: {
-        fs?: Fs;
-    });
-    /** The project's creds, kept in `stores`. */
-    static open(splatesDir: string, root: string, lock: Lock, stores: SecretStores, opts?: {
-        fs?: Fs;
-    }): Promise<Creds>;
-    /**
-     * Where code reads a cred's value: the project's store, then the device's.
-     * Never the environment, so a stray export is not what splates reads.
-     */
-    get credentials(): Credentials;
-    /** Every request, open or not, the latest first. */
-    requests(): Promise<CredRequest[]>;
-    /**
-     * Asks a person for `name`, saying what for, kept in `scope`'s store once they save it.
-     * Asks nothing, returning null, when that store already keeps it, unless
-     * `replace` says the value kept there does not work, and then a purpose or
-     * instructions left off are those of the last request for `name`.
-     */
-    request(name: string, { scope, purpose, instructions, task, replace, }: {
-        scope: Scope;
-        purpose: string;
-        instructions: string;
-        task: string | null;
-        replace?: boolean;
-    }): Promise<CredRequest | null>;
-    /**
-     * Blocks until a person fills or dismisses the request for `name`,
-     * returning what became of it; gives up with `timeout`.
-     */
-    wait(name: string, { timeout, poll, }?: {
-        timeout?: Duration;
-        poll?: Duration;
-    }): Promise<"saved" | "dismissed">;
-    /**
-     * Keeps `value` as `name`, filling its request if one is open, in the
-     * request's scope, else in `scope`. `by` names the tool saving it, for
-     * the page to say; a person's own save says nothing.
-     */
-    save(name: string, value: string, { scope, by }?: {
-        scope?: Scope;
-        by?: string | null;
-    }): Promise<Scope>;
-    /** Turns down the open request for `name`, so its agent stops waiting. */
-    dismiss(name: string): Promise<void>;
-    /** Deletes `name` from `scope`'s store; whether there was one. */
-    remove(name: string, scope: Scope): Promise<boolean>;
-    /**
-     * Copies each cred kept under arbor's `ARBOR_*` name to its `SPLATES_*`
-     * one in the same store, unless that is kept already. The old one stays,
-     * for an arbor still running, and any record naming it, to read.
-     */
-    copyLegacy(): Promise<void>;
-    /** Every cred either store keeps, the project's first, by name. */
-    kept(): Promise<KeptCred[]>;
-    /** What a person calls `scope`'s store, as in "the macOS Keychain". */
-    label(scope: Scope): string;
-    private has;
-    private read;
-    private change;
-}
-export {};
+import type { SplatesDeps } from "@stringsync/splates-server/server";
+/** `splates creds`, which the root cli mounts after `splates lane`. */
+export declare const splatesCreds: import("webappwiz/cmd").Cli<SplatesDeps, SplatesDeps>;

package/flags.d.ts

@@ -0,0 +1,37 @@
+import { type AgentPick, Offered, type RosterAgent } from "@stringsync/splates-server/models";
+import type { Repository } from "@stringsync/splates-server/records";
+import type { SplatesDeps } from "@stringsync/splates-server/server";
+import { SavedTunnel } from "@stringsync/splates-server/tunnel";
+import { z } from "zod";
+/** A place in the todo list, 1 at the top; absent leaves it to the command. */
+export declare const position: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+/**
+ * The agent `--agent`, `--model` and `--effort` name off the roster:
+ * undefined when none is given, null for `--agent none`.
+ */
+export declare function assigneeIn(deps: SplatesDeps, agent: string, model: string, effort: string): Promise<AgentPick | null | undefined>;
+/**
+ * `agent` on `model` off `agents`, at the thinking level `effort` names
+ * among those it offers, each left out when empty.
+ */
+export declare function pickIn(deps: SplatesDeps, agents: RosterAgent[], agent: string, model: string, effort: string, data?: Record<string, unknown>): Promise<AgentPick>;
+/**
+ * `{ effort }` for the thinking level `effort` names among those `agent`
+ * offered when last started, or nothing when it is empty.
+ */
+export declare function effortIn(deps: SplatesDeps, agent: string, effort: string, data?: Record<string, unknown>): Promise<{
+    effort?: string;
+}>;
+/** The settings each agent offered when last started, from any project. */
+export declare function offeredOf({ ps, fs }: SplatesDeps): Offered;
+/** The tunnel each slot's home may have saved, for every word of the pool. */
+export declare function slotTunnelsOf({ ps, fs, secrets, }: SplatesDeps): SavedTunnel[];
+/** `--lane 3`, `new` or `none` as a lane; absent leaves it to the command. */
+export declare function laneIn(raw: string): number | "new" | null | undefined;
+/** `--todo 3,5` as ids, refusing anything that is not one. */
+export declare function todoIds(raw: string): number[];
+/**
+ * Which task a command that takes no task name is about, so the journal can
+ * name it. `merge` and `escalate` read it off the current branch.
+ */
+export declare function here({ service, git, ps, project, }: SplatesDeps & Repository): Promise<string | null>;