@stringsync/splates 0.0.47 → 0.0.51

package/README.md

@@ -13,6 +13,10 @@ 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.
+A release that keeps its records under `.git/splates` differently moves them
+over as `splates server` starts, or as `splates update` runs, backing them up
+first and putting them back if a step fails; the page then shows what failed,
+with a way to retry or to start an agent that fixes it.
 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`.
@@ -42,9 +46,19 @@ and is absent from the published CLI.
 removes the worktree. A conflict or a failing check goes back to the agent that
 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
+--reporter-outfile="$SPLATES_TEST_REPORT"`) queues a task for each test slower
 than 5 seconds.
 
+**Project notes.** Keep durable conventions, decisions and other project context
+as short Markdown files in `notes/`, one thing per file, edited in place.
+Each starts with frontmatter such as `description: Why releases use explicit exports`
+between `---` lines. `splates notes` prints those descriptions in filename
+order, one per line; a missing directory prints nothing successfully. Read
+the files directly or search them with `rg`. Set `notesDir: "docs/context"`
+in `splates.config.ts` to move the directory, relative to the checkout root
+or to an absolute path. Notes change through tasks, just as code does.
+Keep sensitive information out of them.
+
 **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
@@ -53,7 +67,7 @@ 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,
+makes under `splates server`, at `splates checkpoint` 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
@@ -107,10 +121,10 @@ step checked against GitHub:
 
 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
-where it left off.
+**Questions.** When an agent needs you (a decision, access, a review, or
+merges that keep failing), it writes its questions under `## Blocked` in the
+task's `SPLATES.md`, asks them in its reply and ends its turn, leaving its
+worktree as it is. You answer, and it picks up where it left off.
 
 ## The harness
 
@@ -239,9 +253,26 @@ 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`:
+To have splates make workers when agents queue for want of a slot, name the
+cloud account to make them in as `splates.config.ts`'s `cloud`, in the repo
+`splates server` starts in:
+
+```ts
+import { AwsCloud } from "@stringsync/splates-server/cloud";
+import type { ConfigFile } from "@stringsync/splates-server/config";
+
+export default { cloud: new AwsCloud() } satisfies ConfigFile;
+```
+
+`AwsCloud` comes with splates, signed with the AWS CLI's sign-in or the
+instance role. Another is a class that implements
+`CloudProvider` from `@stringsync/splates-server/cloud`: making, listing and
+deleting tagged machines, snapshots, SSH keys and firewalls through the
+cloud's API, with its machine types and prices. splates makes both the
+workers and the coordinator's box (`splates server deploy`) over it.
+
+For machines that are not a cloud's, give it a `workerProvider` instead, any
+object that implements `WorkerProvider`:
 
 ```ts
 import type { ConfigFile } from "@stringsync/splates-server/config";
@@ -387,6 +418,18 @@ test was run. See [the experiment plan](../../designs/opencode-acp.md) for opt-i
 provider restrictions, and the separate paid-overflow control. Fixture checks
 never establish account entitlement or remaining quota.
 
+### Task cost at API list price
+
+Claude says what each session would cost at API rates, and a task's cost is
+that. Codex says no cost, and OpenCode's is its plan's, so for those two splates
+prices each turn's tokens at the public API list price of the model it ran on,
+from [models.dev](https://models.dev), the catalog OpenCode prices models by.
+It keeps a copy in `~/.splates/prices.json`, fetched again once a day, and
+prices a turn at a model's long-context rate once the turn's context passed it.
+The merged card marks such a cost "at API list price". It is an estimate: a
+turn cut short before the agent said its tokens counts nothing, and OpenCode's
+counts leave out its subagents.
+
 ### OpenCode experiment usage
 
 OpenCode's Usage popover shows the last dispatched requested/confirmed full model
@@ -395,7 +438,9 @@ counts. Missing fields read **Unknown**, including optional cache counts. Report
 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.
+A task's cost on its merged card and the Stats page prices these per-turn tokens
+at each confirmed model's API list price instead, as it does Codex's (see Task
+cost at API list price).
 
 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

package/flags.d.ts

@@ -3,7 +3,7 @@ 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. */
+/** A place in the queue, 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:
@@ -28,10 +28,10 @@ export declare function offeredOf({ ps, fs }: SplatesDeps): Offered;
 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[];
+/** `--task 3,5` as task numbers, refusing anything that is not one. */
+export declare function taskIds(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.
+ * name it. `merge` reads it off the current branch.
  */
 export declare function here({ service, git, ps, project, }: SplatesDeps & Repository): Promise<string | null>;

package/hook.d.ts

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