@stringsync/splates 0.0.0-stage → 0.0.45

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stringsync LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,309 @@
-# Temporary Holding Version
+# Spinning Plates
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[spinningplates.tech](https://spinningplates.tech) · command: `splates`
+
+Run many coding agents on one repository at once. Each works in its own git
+worktree and lands its change on `main` itself, without pull requests.
+
+```bash
+bunx @stringsync/splates init
+```
+
+Run it in your repository and commit what it writes: the splates skill, which it
+installs with [`skills`](https://skills.sh) from this release's tag into
+`.agents/skills` for Codex and most agents, linked from `.claude/skills` for
+Claude Code, and `skills-lock.json`. `splates update` moves it to a newer release.
+Without splates, `bunx skills add stringsync/splates#v<release> --skill splates`
+installs the same skill. From then on, your agents start each change with
+`splates add` and land it with `splates merge`.
+
+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
+`~/.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.
+
+Contributions are welcome: see [Contributing](CONTRIBUTING.md).
+
+## How it works
+
+At its core, splates is a consistent way to coordinate worktrees. Each change is
+a task with its own branch and worktree, and every agent moves tasks through
+the same few commands, so agents never edit the same checkout and always know
+what the others are doing. There is no daemon and no orchestrator: splates is a
+CLI over git, and any agent in any terminal can use it. `splates --help` lists
+every command. A bare `splates` prints help too; start the web page with
+`splates server`. The `splates dev` namespace belongs only to this repository
+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.
+
+**Heavy jobs.** Hooks (`postCheckout`, `postRewrite`, `preMerge`) run in one
+of the machine's heavy-job slots, two by default (`SPLATES_HEAVY_JOBS` sets
+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.
+
+**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
+where it left off.
+
+## The harness
+
+`splates server` is an optional page for running agents and answering them, on
+http://localhost:4269.
+
+```bash
+bunx @stringsync/splates server
+```
+
+Run it from anywhere: it serves every splates project on this machine. Its
+project picker switches between them, and adds a repository by its path,
+running `splates init` there and asking before it commits what that wrote.
+
+### Parallel agents
+
+Start as many conversations as you like, each in a task of its own.
+
+![Several agents working at once](https://raw.githubusercontent.com/stringsync/splates/main/packages/splates/screenshots/parallel.png)
+
+### Questions and demos
+
+Agents ask as they go instead of guessing. Each question comes with its
+choices, the one the agent would pick, and a screenshot of each when there is
+something to see. Answer in a click.
+
+![Questions with a screenshot per choice](https://raw.githubusercontent.com/stringsync/splates/main/packages/splates/screenshots/questions.png)
+
+When work is ready, the agent hands you a demo: steps to try, what you should
+see, and a checklist to tick off before you merge or ask for changes.
+
+![A demo to try before merging](https://raw.githubusercontent.com/stringsync/splates/main/packages/splates/screenshots/demo.png)
+
+### Annotate any image
+
+Mark up any image, one you upload or one an agent shows you. Draw a box or an
+arrow, pin a note to each, and send it back.
+
+![An agent's screenshot, marked up](https://raw.githubusercontent.com/stringsync/splates/main/packages/splates/screenshots/annotate.png)
+
+### Remote access
+
+To open the page from another machine, put it behind a Cloudflare tunnel and
+Cloudflare Access, which decides who may enter. Set it up once per machine:
+
+```bash
+bunx @stringsync/splates tunnel setup splates.example.com --email me@example.com
+bunx @stringsync/splates creds wait SPLATES_CLOUDFLARE_API_TOKEN
+bunx @stringsync/splates tunnel setup splates.example.com --email me@example.com
+bunx @stringsync/splates server
+```
+
+`tunnel setup` makes, through Cloudflare's API, a tunnel, the DNS record
+routing the host to it, and an Access application letting in only those
+emails, and saves them: the host, team and AUD tag in
+`~/.splates/tunnel.json`, the tunnel's token in the system's secret store (the
+Keychain on macOS). From then on a bare `splates server` runs the tunnel with
+`cloudflared`, no `cloudflared login` needed. Run again, it changes only what
+differs, such as the emails. The first run has no API token yet, so it
+requests one on the Creds page of `splates server`, with how to make it; paste it
+there, and run it again. An account with no Zero Trust organization gets one
+with `--team <name>`, for `<name>.cloudflareaccess.com`. `splates tunnel status`
+shows what is saved, and `splates tunnel remove` deletes it all again: the tunnels
+of the machine and of every slot, their DNS records, the Access applications
+and their policy, and the saved files and tunnel tokens. The API token stays.
+
+To run several at once, as when trying changes to splates from a few worktrees,
+give each its own slot:
+
+```bash
+bunx @stringsync/splates server --slot
+```
+
+`--slot` claims a short animal word for the checkout it runs in, as `fox`, and
+serves it at `https://fox.<zone>`, on the zone `tunnel setup` used, behind the
+same Access policy, so a phone opens each by name. A task's worktree keeps its
+word until the task merges or is removed, which stops its server and gives the
+word back; run again, `--slot` stops the tree's last server first. It refuses
+a splates repository's main tree, which every agent shares. `splates slots list`
+shows who holds each word, and `splates slots prune` frees those no tree owns any
+more, stopping their servers. A word's tunnel and DNS record are made on its first
+claim and kept, and one wildcard Access application covers every slot. A slot
+keeps its own projects, roster and tunnel in `~/.splates/slots/<word>`, apart
+from yours, and starts in a throwaway project there, unless that home
+registers the project it is run in (`SPLATES_HOME=~/.splates/slots/fox splates
+init`). The page shows the slot's emoji beside the project's name.
+
+Or give the tunnel and the Access application by hand, over what is saved:
+
+```bash
+bunx @stringsync/splates server --tunnel splates.example.com \
+  --access-team my-team --access-aud <the application's AUD tag>
+```
+
+`--tunnel` runs `cloudflared tunnel run` against the page for as long as the
+server lives (`--tunnel-name` picks the named tunnel, else cloudflared's own
+config does), and is refused without both Access flags. Requests to that host
+must carry a verified Access token; with one, conversations and terminals
+work too.
+
+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";
+
+const myTunnel: TunnelProvider = {
+	// throw, saying what to do, unless the tunnel can run
+	async ready() {},
+	// carry route.host to route.url until the returned resource is disposed
+	run: ({ host, url, log }) => {
+		const child = Bun.spawn(["my-tunnel", "--host", host, "--to", url]);
+		return { disposeAsync: async () => void child.kill() };
+	},
+};
+
+export default { tunnel: myTunnel } satisfies ConfigFile;
+```
+
+`--tunnel <host>` then runs yours instead of cloudflared. Access is still
+required, since splates verifies Cloudflare Access tokens whatever carries the
+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.
+
+### Task ports
+
+Any port a task's processes listen on, in its worktree or under its agent, is
+found and forwarded as VS Code forwards ports, through the worker that runs
+it. Save a wildcard base host for this machine to open each one anywhere,
+behind the same Access application:
+
+```bash
+bunx @stringsync/splates server --ports-host ports.example.com
+```
+
+`https://<task>-<port>.ports.example.com` then reaches that task's server,
+seen there as `localhost:<port>`, and only with a verified Access token;
+routing `*.ports.example.com` to `splates server`, its DNS and TLS, are yours.
+`--ports-host none` forgets the base. `splates ports [task]` lists each port
+with its remote and local links, as the task's dialog on the page does.
+
+### Stats
+
+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
+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
+with fewer questions as your prompts and setup change. Its Act on cards
+compare each figure with the as long a span before, saying whether it got
+better or worse, and say what to change when one stands out. Fixed rules over
+the counts make those calls, not a model, so the same outcomes always read
+the same.
+
+### Optional OpenCode ACP agent
+
+Open **Settings → Setup** and visit the optional OpenCode steps. Check this
+machine, install if needed, and connect an existing Go/Go Plus account through
+the native masked key prompt. The supported CLI exposes the V2 standalone login,
+auth listing and metadata APIs; unsupported installations show update guidance.
+No key belongs in chat, and splates never reads or exports native credential files.
+
+Refresh the Go catalog, choose exact main and auxiliary models, review the
+configuration, and confirm **Use balance** is off in Console before applying.
+The save updates the running server's roster immediately. Claude/Codex entries,
+custom fields, model descriptions and defaults are preserved.
+
+The final **Check configuration** step rereads the saved recipe, including after
+a server restart, and checks it for the current project's main directory. It
+checks installation, stored authentication, ACP initialize, both model IDs and
+effective agent configuration. It sends no prompt. Project OpenCode configuration
+is disabled only for this launch recipe; global files remain untouched. New
+custom or managed configuration that conflicts with the recipe requires repair.
+
+**New OpenCode conversation** repeats that check, explicitly selects the saved
+main model and opens an empty conversation in the displayed directory. Its first
+message is your decision. Configuration readiness does not establish successful
+inference, entitlement, quota or billing. Console confirmation is your assertion;
+splates cannot verify or change that setting. Revisit/repair returns to the existing
+steps. Disable removes only the wizard-owned roster entry for new conversations;
+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).
+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.
+
+Splates requires the full, case-sensitive model ID returned in ACP settings for
+OpenCode. Missing choices or a different confirmed provider/model stop the turn;
+it never substitutes another provider. Refresh your editable catalog from
+OpenCode's offered models when it changes. In Choosing agents and models,
+choose OpenCode from New, then select the model in the composer (Settings on a
+phone). Go choices show “OpenCode Go” and their full `opencode-go/...` ID; models
+with the same display name remain distinct across providers. ACP config updates
+replace the offered options. A removed selection is shown as unavailable until
+you explicitly choose a replacement; it is never silently changed to the current
+agent default. OpenCode choices do not change Claude/Codex saved settings.
+Usage provenance and comparisons are tracked in #354.
+
+OpenCode owns its native login and tools. Splates neither imports its credentials
+nor exports OS-store secrets to it. Recovery uses advertised resume support, or
+advertised load with history replay suppressed. An imported CLI session still
+replays once. OpenCode recovery uses its original absolute directory; if that
+directory is gone, restore it or explicitly start a new conversation. Unsupported
+recovery reports an error. Without steering support, messages queue for the next
+turn. Client file and terminal capabilities are not advertised.
+
+Compatibility as of 2026-10-17: this integration is verified with synthetic ACP
+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,
+provider restrictions, and the separate paid-overflow control. Fixture checks
+never establish account entitlement or remaining quota.
+
+### OpenCode experiment usage
+
+OpenCode's Usage popover shows the last dispatched requested/confirmed full model
+IDs, measured first-text and elapsed latency, and parent-only per-turn ACP token
+counts. Missing fields read **Unknown**, including optional cache counts. Reported
+USD cost is a cumulative session observation, separate from unknown additional
+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)
+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
+both Scry model roles and avoids opening credential stores; model-dependent rules
+are reported as unchecked. `splates dev test` runs the local fixture suites.
+
+### OpenCode setup wizard (optional)
+
+Open Settings → Set up splates → OpenCode to check installation, explicitly install
+the official CLI with npm, and connect an existing Go/Go Plus account through
+OpenCode's masked native key prompt. Return and choose Check again to inspect
+native credential metadata and negotiate ACP without sending a model prompt.
+Older native login interfaces show recovery instructions. No keys belong in an
+agent conversation. The native controls currently require macOS or Linux.
+
+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)
+for exact files and supported interfaces.

package/acp-extensions.d.ts

@@ -0,0 +1,82 @@
+import type * as acp from "@agentclientprotocol/sdk";
+import type { ConversationState } from "./conversation-state.js";
+/**
+ * What every session is opened with. Claude's AskUserQuestion is off, so its
+ * questions go under `## Blocked` and into its reply, as the splates skill asks,
+ * rather than into a form `SPLATES.md` never sees. Other agents ignore it.
+ */
+export declare const SESSION_META: {
+    claudeCode: {
+        options: {
+            disallowedTools: string[];
+        };
+    };
+};
+/** The ACP extension that says a prompt into the turn the agent is running. */
+export declare const STEER = "_session/steering";
+/**
+ * The updates and request, an ACP draft Claude's adapter speaks ahead of the
+ * SDK, that say when a background command starts and ends, and stop one.
+ */
+export declare const ASYNC_TASK_SPAWNED = "async_task_spawned";
+export declare const ASYNC_TASK_STATE = "async_task_state_update";
+export declare const ASYNC_TASK_PROGRESS = "async_task_progress";
+export declare const ASYNC_TASK_STOP = "_session/async_task/stop";
+/** The notification the client hears each of those updates as (see `asyncTasks`). */
+export declare const ASYNC_TASK_UPDATE = "_splates/async_task";
+/**
+ * The messages from an agent, each update on a background command moved to
+ * `ASYNC_TASK_UPDATE`, ahead of the SDK's checks, which would refuse it as a
+ * session update they do not know.
+ */
+export declare function asyncTasks(messages: ReadableStream<acp.AnyMessage>): ReadableStream<acp.AnyMessage>;
+export interface AsyncTaskSpawned {
+    sessionUpdate: typeof ASYNC_TASK_SPAWNED;
+    asyncTaskId: string;
+    name: string;
+    /** `shell` for a command, else a workflow or the like. */
+    taskType: string;
+    description: string;
+    toolCallId?: string;
+    outputFilePath?: string;
+}
+export interface AsyncTaskState {
+    sessionUpdate: typeof ASYNC_TASK_STATE;
+    asyncTaskId: string;
+    state: "running" | "paused" | "completed" | "failed" | "stopped";
+    outputFilePath?: string;
+}
+/** What the agent says as a command goes on: here, only where its output is. */
+export interface AsyncTaskProgress {
+    sessionUpdate: typeof ASYNC_TASK_PROGRESS;
+    asyncTaskId: string;
+    outputFilePath?: string;
+}
+export type AsyncTaskUpdate = AsyncTaskSpawned | AsyncTaskState | AsyncTaskProgress;
+/** Whether an agent says, as it starts, that it takes `STEER`. */
+export declare function steers(initialized: acp.InitializeResponse): boolean;
+/**
+ * The AIR session list: subscribed for a working directory, the agent says
+ * as each of its sessions there starts or ends a turn. Codex says so of a
+ * turn it starts on its own nowhere else.
+ */
+export declare const SESSION_LIST_SUBSCRIBE = "_session/list/subscribe";
+export declare const SESSION_LIST_CHANGES = "_session/list/changes";
+/** Whether an agent says, as it starts, that it takes `SESSION_LIST_SUBSCRIBE`. */
+export declare function listsSessions(initialized: acp.InitializeResponse): boolean;
+/** What a `SESSION_LIST_CHANGES` row says of a session's turn. */
+export interface ListedTurn {
+    running: boolean;
+    /** When its last turn ended, in ms; null before one has. */
+    endedAt: number | null;
+}
+/**
+ * What `params` of `SESSION_LIST_CHANGES` say of `session`'s turn; null when
+ * they hold no row for it, or one that says nothing of its turns, as for a
+ * session no process has open.
+ */
+export declare function listedTurn(params: Record<string, unknown>, session: string): ListedTurn | null;
+/** Whether `update` is the agent's final answer, after which its turn ends. */
+export declare function finalAnswer(update: acp.SessionUpdate): boolean;
+/** Folds an update on a background command into those the agent left. */
+export declare function foldBackground(state: ConversationState, update: AsyncTaskUpdate): void;

package/add.d.ts

@@ -0,0 +1,53 @@
+import { type Logger } from "webappwiz/log";
+import type { Fs, HeavyCap } from "webappwiz/system";
+import type { Config } from "./config.js";
+import { type RosterAgent } from "./roster.js";
+import type { Shell } from "./shell.js";
+import type { Todos } from "./todos.js";
+import type { Dispatched } from "./worktree.js";
+import type { WorktreeService } from "./worktree-service.js";
+export interface AddOptions {
+    /** Branch the task starts from and merges onto. Defaults to the trunk. */
+    base?: string;
+    /**
+     * The todos this task takes up: their words seed the plan's Goal, and
+     * nobody else can take them while the task lives.
+     */
+    todos?: number[];
+    /**
+     * One or two lines on what done means, written under `## Goal` ahead of
+     * whatever the todos seed it with.
+     */
+    goal?: string;
+    /**
+     * Runs once the worktree exists and before its record makes the task live,
+     * so whatever it tells of the task is in place before anyone can see it.
+     */
+    onTree?: () => Promise<void>;
+    /**
+     * The agent to hand the task to, which `splates server` starts in its tree once
+     * the tree is ready; its id must be one of `agents`.
+     */
+    dispatch?: Dispatched;
+    /** The roster's agents, which `dispatch` must name one of, and its model. */
+    agents?: RosterAgent[];
+    /**
+     * Added from another project, as `splates --project` does: the task goes
+     * to an agent of its own, so `dispatch` is a must.
+     */
+    away?: boolean;
+    /**
+     * Hands the task out though the agent adding it has as many out to
+     * agents as `config.agentsPerAgent` allows, as only the person may ask.
+     */
+    overCapacity?: boolean;
+}
+export declare function add({ service, shell, config, log, fs, todos, heavy, }: {
+    service: WorktreeService;
+    shell: Shell;
+    config: Config;
+    log: Logger;
+    fs: Fs;
+    todos: Todos;
+    heavy: HeavyCap;
+}, task: string, { base, todos: ids, goal: asked, onTree, dispatch, agents, away, overCapacity, }?: AddOptions): Promise<void>;

package/adherence.d.ts

@@ -0,0 +1,49 @@
+import type { Fs } from "webappwiz/system";
+import type { ConversationState } from "./conversation-state.js";
+import type { Outcomes } from "./outcomes.js";
+import { type Transcript } from "./skill-checks.js";
+/**
+ * How closely `splates server`'s conversations follow the splates skill, across
+ * projects, in `~/.splates/adherence.jsonl`: a line each time a turn ends and
+ * changes how a conversation's checks went, the last one standing for it. It
+ * outlives the conversations' logs, which go as archived ones are pruned.
+ */
+export declare class Adherence {
+    /** `~/.splates/adherence.jsonl`, or a test's own. */
+    readonly path: string;
+    private readonly fs;
+    /** Where the commits a conversation merged are kept; null to judge without them. */
+    private readonly outcomes;
+    /** The scores last written for each conversation, so a turn that changes none writes nothing. */
+    private readonly written;
+    constructor(
+    /** `~/.splates/adherence.jsonl`, or a test's own. */
+    path: string, fs: Fs, 
+    /** Where the commits a conversation merged are kept; null to judge without them. */
+    outcomes: Outcomes | null);
+    /** Judges `state` as it stands, and keeps the result when it changed. */
+    judge(state: ConversationState, project: string, at: string): Promise<void>;
+    /** Each conversation's checks as last judged. */
+    list(): Promise<Judged[]>;
+    /** What `state` merged, read from the outcomes only once it has merged anything. */
+    private endOf;
+}
+/** How each check went over one conversation: the places it applied, passed and failed. */
+export type Scores = Record<string, {
+    passed: number;
+    failed: number;
+}>;
+/** A conversation's checks as last judged, a line of `~/.splates/adherence.jsonl`. */
+export interface Judged {
+    conversation: string;
+    /** The main tree of the repository it ran in. */
+    project: string;
+    agent: string;
+    /** The splates skill version it started on; null when unknown. */
+    skill: string | null;
+    /** When it was judged, as an ISO timestamp. */
+    at: string;
+    scores: Scores;
+}
+/** A conversation as `skill-checks` reads it: what it said and ran, in order. */
+export declare function condense(state: ConversationState): Transcript;

package/age.d.ts

@@ -0,0 +1,2 @@
+/** How long ago an ISO timestamp was, at the coarsest unit that still reads. */
+export declare function age(since: string): string;