@velven/cli 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## 0.5.0
+
+Needs the Velven of the same release, which speaks only this version: update to 0.5.0. 0.3.0 and 0.4.0 can no longer
+send a message (every send now carries an id), and no earlier version can publish without an account (each sends the
+claim token in the finish's body too, which Velven now refuses: it takes the token only in the `x-velven-claim`
+header). Publishing with an account is unchanged.
+
+- A message sent while a turn runs joins that turn when the turn is writing code: "Sent to the running turn
+  (<turn>).", then the CLI follows the project until the turn ends, prints "Taken into account." once the running
+  agent has read it, the turn's reply (which says what it did with your words) and how the turn ended (exit 0 when it
+  ended done, 1 otherwise). `--detach` prints the watch command instead. A turn takes up to five such messages, within
+  its own credits and time; a message with a picture, an answer, `--effort`, a plan flag or `--build` never joins a
+  turn, so it waits and keeps them.
+- Otherwise it waits, and the CLI says why: "Queued: the turn is not writing code now, so it runs after the turn.",
+  "the turn is finishing, so it runs next", "five messages already joined this turn", or "it runs after the turn that
+  is running" for `--queue` (always wait), a picture, an answer, `--effort`, a plan flag or `--build`. A message that joined too late to be read is queued
+  the same way ("Could not be taken this turn; queued as the next message.", or, when the project's queue is paused,
+  "queued, but the queue is paused ... Start it: velven create resume").
+- `send` makes an id for each message and, when the send gets no answer (a dropped connection, or an error on Velven's
+  side other than a turn that could not start), sends it once more with the same id: Velven answers what it did with
+  the first, nothing is started or held twice, and the line starts with "(already sent)". The estimate and the message
+  no longer carry `queue`.
+- `--answer <n>` answers Velven's open question with its choice n: the chip's words, or yours when you give some. The CLI
+  keeps the last question it printed, following a turn or a project, in its state file, and forgets it once any
+  message is sent to the project or a stream shows it answered or superseded; with none for the project it stops
+  with exit 2. A question now says `Answer: velven create send --answer 1 (a choice's number), or in your own
+  words.`
+- A failed or stopped turn pauses the messages waiting on its project. `velven create resume` starts them again ("Resumed:
+  2 waiting. The first starts now: velven create watch <turn>", or "Nothing was paused."); `velven create queue` starts
+  with "Paused after a failed turn" (or "a stopped turn") and marks a message sent while a turn ran; `velven create
+  cancel` says when it paused messages, and says a running turn stopped at once (its run was gone) is stopped with
+  the credits it used, never that its credits are back. A send while the queue is paused and a turn runs says so.
+- `velven create queue edit <id> <text>` changes a waiting message (`--build` sends it as Build it), and `velven create
+  queue move <id> <place>` moves one in line (it sends the whole order, and reads the queue again once when it changed
+  meanwhile), paused or not.
+- `velven create versions` lists the project's versions newest first (each turn that saved the game, then 0, the
+  template), marking `head`, `rolled back` and `preview`. `velven create restore <version>` goes back or forward to one,
+  instantly and for no credits: "Went back to version 2 (commit 2222222).", "Already on version 2.", and "Its preview
+  expired; Velven is rebuilding it (no credits)." when it is. An unknown version, a restore while a turn runs and a
+  version whose files are gone exit 4.
+- `velven create watch <project>` follows a project's whole chat: its newest turns under their headers, then each
+  message, question, plan, design, run, tool call, picture, build, playtest, review, commit (once saved, or "Not saved"
+  when its turn failed before the history held it), preview and restore as it lands, each turn's phase and end, the queue and its pause, the newest failure, and "Up to date." once caught up. It
+  reconnects from its place; Ctrl+C ends it with exit 0; `--until-idle` ends it once nothing runs and no message waits to start; `--from <n>` reads
+  what came after event n; `--json` prints each event on its line. `watch <turn>` is as before.
+- `velven create show` says what the project is doing: "Running: coding (turn 4)", "A preview of version 2 is being
+  rebuilt.", a paused queue, and the newest turn's failure with "Try again." when sending it again may work; "Latest
+  commit" names its version. `show --json` carries the project's `summary`.
+- A failed turn's class decides what the CLI suggests: following it prints "Try again: velven create send ... with the
+  same words." when sending it again may work, and `--json` answers carry `failure: { class, retryable }`.
+- Pictures, screenshots and clips are printed as stable Velven links (`/api/v1/create/media/<id>`) that do not expire:
+  they open in the browser you approved the CLI from, signed in (signed out, Velven asks you to sign in first),
+  instead of signed links that lasted 15 minutes. `--json` output carries each picture, screenshot, clip and frame by
+  its media id (`media`, `frame`) only: the events and `show --json` no longer carry `url`, `frame_url`, `clip_url` or
+  `expires_at` for them.
+- `velven create refs` reads how many messages carried each picture from every answer ("sent" for an answer without
+  the count is gone).
+- While a turn runs on the project, `send` prints no estimate: the message joins the turn or waits, holding nothing.
+  A waiting message that was taken out of the queue, or refused as it came to start, prints "Taken out of the queue;
+  it will not run." (a send again of it says the same). A later small change's step is "Making the change".
+- `watch <project>` prints a tool call once it has its note or has ended, a finished run's end after its tool calls and
+  pictures in a chat it reloads, "Build it: ..." only under a plan that ends its turn (never one a Build it turn drafts
+  and builds), and a restore to a later version as "Went forward to version N". `show` prints "Next turn: ..." only
+  after a turn sent with `--effort` or a plan flag.
+
 ## 0.4.0
 
 - `velven create send` lets Velven pick how much to do when you pass neither `--effort` nor `--plan`/`--no-plan`:

package/README.md

@@ -160,14 +160,20 @@ velven create send "a cozy game where you grow a garden on a floating island"
 | Command | What it does |
 | --- | --- |
 | `velven create new [title]` | Start a project. It becomes the current project. Without `--genre` it is an open game: Velven follows your idea (`--genre arcade` holds it to arcade's rules). Without `--engine`, Velven picks 2D (`phaser`) or 3D (`three`) from your idea: 3D unless it is clearly 2D |
-| `velven create send <text>` | Send the current project a message. Velven picks how much to do unless you pass `--effort` or a plan flag. The CLI prints the estimate, asks before sending in a terminal, then follows the turn to its end. `--build` builds now, `--ref <file>` attaches a picture (`--ref ref-3` one the project keeps). Sent while a turn runs on the project, the message waits and runs when that turn ends (followed at once when that turn ended as it was sent; exit 4 with why when Velven refused it) |
+| `velven create send <text>` | Send the current project a message. Velven picks how much to do unless you pass `--effort` or a plan flag. The CLI prints the estimate (none while a turn runs on the project: the message joins it or waits, holding nothing), asks before sending in a terminal, then follows the turn to its end. `--build` builds now, `--ref <file>` attaches a picture (`--ref ref-3` one the project keeps), `--answer <n>` answers Velven's question with its choice n. Sent while a turn runs on the project, the message joins that turn when the turn is writing code, else waits and runs when it ends; `--queue` always waits, as does a message with `--effort`, a plan flag, `--build`, `--ref` or `--answer` |
 | `velven create plan` | A new game's short plan: what the game is, how it plays, its look, what is in it, how it ends. `--project <id>` picks another project |
-| `velven create queue` | The messages waiting behind the running turn, in the order they run, and any Velven could not start with why. `--project <id>` picks another project |
+| `velven create queue` | The messages waiting on the project, in the order they run, whether the queue is paused, and any Velven could not start with why. `--project <id>` picks another project |
+| `velven create queue edit <id> <text>` | Change a waiting message's words (`--build` sends it as Build it), paused or not |
+| `velven create queue move <id> <place>` | Move a waiting message to a place in line (1 runs next), paused or not |
 | `velven create queue rm <id>` | Remove a waiting message before it runs |
+| `velven create resume` | Start the waiting messages again after a failed or stopped turn paused them: the first starts at once when no turn runs |
 | `velven create watch [turn]` | Follow a turn, by default the last one you sent or watched. `--from <n>` starts from that event |
-| `velven create cancel [turn]` | Stop a turn. What it finished is saved, and unused credits come back |
+| `velven create watch <project>` | Follow a project's whole chat: its turns, messages, questions, pictures, previews, queue and versions, as they come. `--from <n>` reads only what came after that event, `--until-idle` ends once nothing runs on the project and no message waits to start |
+| `velven create cancel [turn]` | Stop a turn. What it finished is saved, unused credits come back, and the messages waiting on the project pause until you resume them |
+| `velven create versions` | The project's versions, newest first: each turn that saved the game, then 0, the template. Marks the one the project is on (`head`), the ones a restore left (`rolled back`) and those with a ready preview |
+| `velven create restore <version>` | Go back, or forward, to a version: instant and free (no turn, no credits). When its preview has expired, Velven rebuilds it in the background, also for no credits |
 | `velven create list` | Your projects. `*` marks the current one |
-| `velven create show [project]` | A project, its newest turn and a fresh preview link (it works for 24 hours) |
+| `velven create show [project]` | A project, what it is doing (the running turn's phase, a preview being rebuilt, a paused queue, the newest turn's failure), its newest turn, the version it is on and a fresh preview link (it works for 24 hours); after a turn you sent with `--effort` or a plan flag, the effort and plan mode the next such send keeps |
 | `velven create show --timeline` | The newest turn's timeline as a waterfall (see below). `--turn <id>` picks another turn, `--all` lists every tool call |
 | `velven create refs` | The project's reference pictures: each id, when it was added, its size and how many messages carried it. `--project <id>` picks another project |
 | `velven create refs rm <ref-n>` | Delete a reference picture, sent or not. The messages that carried it keep its number, and the number is never given to another picture |
@@ -184,8 +190,11 @@ velven create send "a cozy game where you grow a garden on a floating island"
   had them.
 - A new game starts with a short conversation: Velven asks what matters most and is still open (2D or 3D, the style,
   at most four questions in all, fewer for a specific idea), then sketches a short plan. A question comes with
-  numbered choices and how to answer it: send a choice, your own words, or `--build "Just build it"`; the style
-  question also takes a picture with `--ref <file>`. The line names the turn's own project, also when you follow it
+  numbered choices and how to answer it: `--answer <n>` sends choice n (its words, or yours when you give some:
+  `velven create send --answer 2 "painted, but darker"`), or send your own words, or `--build "Just build it"`; the
+  style question also takes a picture with `--ref <file>`. The CLI keeps the last question it printed (following a
+  turn or a project) in its state file, so `--answer` needs no id, and forgets it once you send the project any
+  message or a stream shows it answered or superseded; with no question kept for the project it stops with exit 2. The line names the turn's own project, also when you follow it
   with `velven create watch` from another. The plan prints as a card (the title, the pitch, 2D or 3D and the camera,
   how it plays, the look and palette, what is in it, how it ends, a score or not); send a change in words to reshape
   it, or `--build "Build it"` to build it. `velven create plan` prints it again.
@@ -211,23 +220,52 @@ velven create send "a cozy game where you grow a garden on a floating island"
 - `--yes` sends without asking. Outside a terminal, the CLI never asks.
 - `--detach` sends the message and returns at once. Follow the turn later with `velven create watch`.
 - `--project <id>` sends to a project other than the current one.
-- A message sent while a turn runs on the project waits behind it (at most five a project), holding no credits, and
-  starts on its own when that turn ends: the CLI prints "Queued: it runs after the turn that is running." and exits 0.
-  `velven create queue` lists what waits, `velven create queue rm <id>` removes one; cancelling the running turn
-  leaves the queue as it is. Following the turn that ends prints "Your next message is running: velven create watch
-  <turn>" (with "on project <id>" when the message that started waited on another of your projects; one waiting on
-  the same project starts first). A queued message that starts at once but waits for room on Velven says "Turn <id>
-  waits for room on Velven and starts on its own.", as any such send.
+- A message sent while a turn runs on the project joins that turn when the turn is writing code: the CLI prints "Sent
+  to the running turn (<turn>).", then follows the project until the turn ends, printing "Taken into account." once
+  the running agent has read it (from its next step; it keeps to the turn's credits and time), the turn's reply, and
+  how the turn ended (exit 0 when it ended done, 1 otherwise). The reply says what it did with your words. A turn
+  takes up to five such messages, and a message with a picture, an answer, `--effort`, a plan flag or `--build` never
+  joins a turn: those are a turn's own, so it waits and keeps them.
+- Otherwise the message waits behind the turn (at most five a project), holding no credits, and starts on its own when
+  that turn ends; the CLI says why it did not join and exits 0: "Queued: the turn is not writing code now, so it runs
+  after the turn." (it is planning, building, playtesting, saving), "the turn is finishing, so it runs next" (it is
+  past its time or wrapping up), "five messages already joined this turn", or "it runs after the turn that is running"
+  for `--queue`, a picture, an answer, `--effort`, a plan flag or `--build`. A message that joined a turn too late to be read is queued the same way, and
+  following it prints "Could not be taken this turn; queued as the next message." A waiting message you take out of
+  the queue (or that is refused as it comes to start) shows "Taken out of the queue; it will not run." Following the turn that ends prints
+  "Your next message is running: velven create watch <turn>" (with "on project <id>" when the message that started
+  waited on another of your projects; one waiting on the same project starts first). A queued message that starts at
+  once but waits for room on Velven says "Turn <id> waits for room on Velven and starts on its own.", as any such send.
+- A turn that fails or that you stop pauses the messages waiting on its project: they stay in line and nothing starts
+  until you run `velven create resume` (the first starts at once when no turn runs; "Resumed: 2 waiting. The first
+  starts now: velven create watch <turn>"). A message you send while the queue is paused and no turn runs starts at
+  once; one sent while a turn runs joins the paused line ("Queued, but the queue is paused...", a message the running
+turn could not take included: "Could not be taken this turn; queued, but the queue is paused..."). `velven create queue`
+  starts with "Paused after a failed turn" (or "a stopped turn"), `queue edit` and `queue move` change the line paused
+  or not, and removing the last waiting message clears the pause. `velven create cancel` says when it paused messages.
+- Each send carries an id the CLI makes for it. When the send gets no answer (the connection dropped, or Velven
+  answered with an error on its side), the CLI sends it once more with the same id, and Velven answers what it did
+  with the first: nothing is started or held twice, and the CLI prints "(already sent)" before its line.
 
 The CLI says what the turn does as it goes. What the agents write goes to standard output, and their progress goes to
 standard error. When Velven picked the work, it says so in words first ("I'll make the change."; when the day's
 credits kept it from a fuller turn, "I'll make the change. I kept this one quick to save credits."), with the work it
-picked and why on standard error. On a build it prints the plain step it is at ("Designing your game", "Painting the art", "Building the world", "Trying it out", "Polishing", "Finishing up"), and on a first build the design as it is settled ("Designing Petal Drift: ..." with its style and palette) and each picture once it lands ("Painted sky (1024 by 512)" with a link to look at it). You see what each step changed, the live link while the game is being built, each playtest's preview
+picked and why on standard error. On a build it prints the plain step it is at ("Designing your game", "Painting the art", "Building the world", "Trying it out", "Polishing", "Finishing up"; a later small change says "Making the change" for its work), and on a first build the design as it is settled ("Designing Petal Drift: ..." with its style and palette) and each picture once it lands ("Painted sky (1024 by 512)" with a link to look at it). You see what each step changed, the live link while the game is being built, each playtest's preview
 link (the first playable one, before the turn ends), its screenshots and its clip. When the turn ends, it prints the reply (when the turn asked a question, which it already printed with its choices, only what follows it), then, after a turn that ended with a playable game, "Where it could go next:" with two to four short suggestions for this game and the command that sends the first (`velven create send "Add a boss at the end"`; each is an ordinary message), then the preview link and the credits used. A reply may end with one sentence on what the turn took from your pictures, and with "You're running low on credits for today." when what is left would not cover another small change. A turn that stops at
 its credit cap or time limit saves what it finished and ends with exit 0. A failed turn costs nothing. When a new game's
 first build stops before it made the game (it saved nothing, or only its design), the reply ends "Press Build it to try
 again." and the CLI prints `Try again: velven create send --build "Build it"`; "try again" typed after it builds too.
 
+Links to pictures, screenshots and clips are stable Velven links (`https://velven.ai/api/v1/create/media/<id>`) that
+do not expire: open one in the browser you approved the CLI from, where you are signed in (signed out, Velven asks you
+to sign in first, then shows it). A preview link carries its own 24-hour view token, as before.
+
+A turn that fails says why in a sentence, and its class says what to do: a turn that failed for Velven's capacity, the
+model service, the workspace or something unexpected on Velven's side may work when you send the message again (the
+CLI prints `Try again`); one refused for credits or because its build was refused needs a change first. A failed turn
+costs nothing. `--json` answers carry the class as `failure: { class, retryable }` (classes `credits`, `capacity`,
+`model`, `sandbox`, `build`, `unknown`).
+
 When Velven is busy, a turn waits for room and starts on its own. The CLI prints "Still waiting for room on Velven."
 and keeps following it, however long it waits. If the connection drops, the CLI reconnects and carries on where it
 left off. After five failed attempts in a row it stops with exit 1, and the turn goes on: `velven create watch` follows
@@ -235,6 +273,24 @@ it again.
 
 Ctrl+C stops following the turn, but the turn goes on. The CLI prints how to watch or cancel it, and exits 1.
 
+`velven create watch <project>` (any id that is not a turn number) follows the project's chat instead of one turn:
+the newest turns so far, each under its header ("Turn 3 (done, version 2)"), then every change as it comes, saying
+each thing once. A person's message prints as `> words` with what happened to it while a turn ran; Velven's replies,
+questions with their choices, plans, designs, pictures with their links, commits, previews, playtests, reviews and
+restores ("Went back to version 1") print as they land; the engine's runs, tool calls, changed files and builds go
+to standard error. It also says each turn's phase and end, how many messages wait and whether the queue is paused, the
+newest failure, and "Up to date." once it has caught up. It reconnects from where it left off. Ctrl+C stops watching
+with exit 0: nothing is lost, `watch` again picks up the project as it is. `--until-idle` ends once it has caught up
+and no turn runs, no preview is being rebuilt and no message waits to start (one waiting on a paused queue starts only
+on `velven create resume`, so it does not count).
+
+`velven create versions` lists the project's versions, and `velven create restore <version>` goes to one: "Went back
+to version 2 (commit 2222222).", or "Went forward to …" for a later one. It is instant and costs nothing; the turns after it are marked rolled back and stay
+listed, and restoring one of them goes forward again. The next message builds on the version you went to. A restore
+waits for a running turn to end (exit 4 while one runs), and an expired preview is rebuilt in the background ("Its
+preview expired; Velven is rebuilding it (no credits)."); a message you send meanwhile stops the rebuild and makes its
+own preview.
+
 While it follows a turn, the CLI also says how long things took: a step of a second or more gets a line with its
 parts (`  openWorkspace 10.9 s: sandbox.get 4.1 s, setup 0.1 s, describe 0.4 s`), each tool call's line ends with its
 time, and the engine programmer's last line says how its run went (`Engine programmer done in 3 min 12 s: 14 model
@@ -256,12 +312,12 @@ builds", "quick interview turns", "quick draft turns" for a new game's short pla
 change, the first playable preview and the whole turn, each phase, each job's cost in credits and USD cents and its model time, and the
 single steps worth comparing, longest first. Under a group's heading, "the next message:" says how the message after its turns reacted to them, as Velven's router labelled it (moved on, corrected it, asked for checks), when any was labelled.
 
-With `--json`, `new`, `send`, `list`, `show`, `plan`, `queue`, `credits`, `usage` and `stats` print one JSON object, and `send` prints only the
-finished turn (or the waiting message, `queued`, when it was queued); `show --timeline --json` prints the turn's id and its timeline (`started_at` and the spans). `watch --json`
-is different: it prints each event of the turn as it comes, one JSON object per line (the plan and the brief as they are written included, which text mode leaves out until the last).
+With `--json`, `new`, `send`, `list`, `show`, `plan`, `queue`, `refs`, `versions`, `restore`, `resume`, `credits`, `usage` and `stats` print one JSON object, and `send` prints only the
+finished turn (or the waiting message and why, `queued` and `why`; or for a message that joined a turn, the message, `steer` and the turn as it ended), with `again: true` when Velven had the send already; `show --json` carries the project's `summary`, `show --timeline --json` the turn's id and its timeline (`started_at` and the spans). `watch --json`
+is different: it prints each event of the turn, or of the project, as it comes, one JSON object per line (the plan and the brief as they are written included, which text mode leaves out until the last).
 
-The current project and the last turn are saved in `~/.config/velven/create.json`, one set for each Velven
-`VELVEN_API` points at.
+The current project, the last turn and the last question are saved in `~/.config/velven/create.json`, one set for
+each Velven `VELVEN_API` points at.
 
 ## Without an account
 
@@ -306,7 +362,7 @@ settings.
 | 1 | Failed: the network, a server error, a failed upload, or you cancelled. For `velven create`: a turn that failed or was cancelled, or that you stopped following |
 | 2 | A mistake in the command or in `velven.json`, such as a missing field, or a `thumbnail` or `clip` that breaks one of the rules above (`invalid_media`) |
 | 3 | You're not signed in, or your token was refused, for something that needs an account, such as `--prod` |
-| 4 | Refused by Velven: not your space, too large, too many files, a program, installer or coin miner in the folder (`refused_file`, before anything is uploaded), or not found. For `velven create`: not enough credits, the builder is closed, a turn is already running or you have too many open, or the effort is not available |
+| 4 | Refused by Velven: not your space, too large, too many files, a program, installer or coin miner in the folder (`refused_file`, before anything is uploaded), or not found. For `velven create`: not enough credits, the builder is closed, too many turns open or messages waiting, a restore while a turn runs, an unknown version, or the effort is not available |
 | 5 | Rate limited: try again later |
 | 6 | Not published: Velven refused the version, or with `--wait`, couldn't judge it |