@thedevlabs-io/labd 0.6.1 → 0.8.0

package/AGENTS.md

@@ -123,18 +123,23 @@ no one to show a diff to.
   prompt. A setting that governs how much we check the model's work is exactly the
   lever an instruction smuggled into a file would reach for. `e2e.test.ts` asserts
   it never appears on the wire.
-- **A project cannot set the mode.** `.labd/settings.json` may set a timeout or a
-  server URL; `mode` is read from the GLOBAL settings and the command line only.
+- **A project cannot set the mode.** `.labd/settings.json` may set a timeout;
+  `mode` is read from the GLOBAL settings and the command line only.
   A repository that could set `mode: "agent"` would be a repository that runs
   commands on the machine of anyone who clones it and types `labd`. See
   `config.ts`, and the test that pins it.
 - **A project cannot load its own code until trusted.** `.labd/extensions` needs
   `labd trust` first. `git clone && labd` must not run a stranger's extension.
-- **A project cannot redirect the token until trusted.** `serverUrl` in
-  `.labd/settings.json` is honoured only for a trusted project; otherwise it is
-  ignored and the banner says so. The bearer token goes wherever that URL points,
-  so a checked-in URL is a checked-in token exfiltration for anyone who clones and
-  types `labd`. Same threat class as project extensions, same gate.
+- **A project cannot redirect the token, turn checkpoints off or raise the
+  effort, trusted or not.** `serverUrl`, `checkpoints` and `effort` in
+  `.labd/settings.json` are ignored and the banner says so. The bearer token goes
+  wherever that URL points, so a checked-in URL is a checked-in token
+  exfiltration for anyone who types `labd`; `checkpoints: false` takes away
+  `/undo`; `effort: high` spends the learner's allowance faster. `labd trust`
+  only lets the project's extensions run. That is a policy line rather than a
+  wall (a trusted extension runs in-process and could read `~/.labd` itself),
+  but it keeps a settings file from doing any of this silently. The VS Code
+  extension holds the same rule for its settings.
 - **Extensions add commands and observers, never tools.** The tool list is the
   protocol's: the server offers the model exactly the capabilities this client
   declares, from one schema both surfaces share. A `registerTool` here would have
@@ -200,6 +205,14 @@ for the screen:
   `Screen` owns the terminal; `modes/screen.ts` is the state machine between them.
 - **The mouse is taken by default, for wheel scrolling, and `--no-mouse` gives
   it back** - native text selection needs the terminal to have it.
+- **Out of allowance, the box takes commands only.** At 0% a letter typed on an
+  empty box is dropped, which is what frees `o` to open the top-up page. `o` is
+  never taken while the learner can type: once the box holds a `/`, every key
+  types. A dropped letter asks the server again (at most every 10 s), and a
+  timer asks just after `resetsAt`, so a reset spent on the portal or the turn
+  of the month never leaves the box stuck. A refusal locks the box whatever the
+  clock says, until the next reading from the server. The browser is opened only for a URL `safeTopUpUrl` allows
+  (`packages/cli/src/browser.ts`).
 
 **The non-interactive modes own nothing and print.** `labd -p`, `--json`,
 `--mode rpc`, and anything with a piped stdout use `Renderer` and plain writes:
@@ -208,6 +221,8 @@ for the screen:
   region is a no-op. Escape codes in a log file are worse than plain text.
 - **The scrollback is not ours.** Finished output is printed and belongs to the
   terminal; only the status line is a live region.
+- **The exit code means something.** `labd -p` exits 0 answered, 1 failed, 2
+  needed an approval nobody could give, 3 this month's allowance is spent.
 - **stdout is the answer. Everything else is stderr.** A pipeline must receive
   only what labd meant as the answer. The interactive session keeps this for
   what it prints on the way out - the "session saved" line goes to stderr.
@@ -307,7 +322,7 @@ properties that would fail silently:
 - **containment** (`paths.test.ts`): traversal, absolute paths, symlinks out of the
   tree, decorated paths. Every path labd touches is model output.
 - **the permission properties** (`permissions.test.ts`): a project cannot set the
-  mode or the server URL, an untrusted project cannot load code, an extension
+  mode, the server URL, checkpoints or effort, an untrusted project cannot load code, an extension
   cannot shadow a built-in command, `agent` does not widen the denylist.
 - **the session tree** (`session.test.ts`): branching, non-destructive compaction,
   a truncated last line.

package/README.md

@@ -74,9 +74,17 @@ labd -c                         # pick up the most recent session here
 | `--plain` | the older print-style session (deprecated; removed in 0.5) |
 | `-v`, `--version` | |
 
+`labd -p` exits with a code a script can act on:
+
+| code | |
+|---|---|
+| `0` | answered |
+| `1` | failed |
+| `2` | a change needed approval, and nobody was there to give it |
+| `3` | this month's labd allowance is spent; the server's message, with the top-up link, is on stderr |
+
 Subcommands: `login`, `logout` (revokes the token server-side too), `sessions`
-(earlier sessions here), `trust` (let this project load its own extensions and
-name its own server).
+(earlier sessions here), `trust` (let this project load its own extensions).
 
 ### Inside a session
 
@@ -129,11 +137,29 @@ more columns.
 | `/sessions`, `/session` | earlier sessions here (a dialog; `enter` resumes); where this one is stored |
 | `/new` | start a fresh session; the current one stays saved |
 | `/sidebar`, `/clear` | show or hide the side panel; clear the screen |
-| `/usage` | what's left of this month's allowance |
+| `/usage` | what's left of this month's allowance, when it resets, any saved resets, the top-up link, and a heatmap of your activity |
+| `/topup` | open the page to top up or use a saved reset, in your browser |
 | `/trust` | let this project load its own extensions |
 | `/reload` | reload extensions and the file list |
 | `/quit` | leave - the session is saved, and `labd --resume <id>` continues it |
 
+### Running low, and running out
+
+The footer shows what is left of this month's allowance. At 15% or less it
+turns yellow and reads `10% left · /topup`; at 0 it turns red and reads
+`out of labd · /topup`, and the box takes commands only. Type `/` for
+one, or press `o` on the empty box to open the top-up page in your browser. A
+question refused for a spent allowance gets a card with the server's message,
+the day it resets, any resets you have saved, and the link. Once you have
+topped up or spent a reset, type anything and labd checks again (at most every
+10 seconds). What you type then is not kept; only the check is. The box also
+opens by itself when the month turns.
+
+Saved resets are spent on the portal, not in the terminal: `/topup` and `o`
+only open the page. labd opens a browser only for its own portal's
+`/settings/labd` page, and prints the link to open by hand if it cannot start
+one.
+
 When you leave, the conversation is handed to the server to be distilled into
 memory, exactly as the editor does when you start a new chat - which is what
 makes "same memory" true in the terminal. Tool results are stripped before it
@@ -167,9 +193,11 @@ Two more rules worth knowing before you point this at a repository you didn't wr
   repo and typing `labd` would be running whatever it decided to allow itself.
 - **A project can't load its own code until you say so.** `.labd/extensions` needs
   `labd trust` in that directory first.
-- **A project can't point your token at another server until you say so.** A
-  `serverUrl` in `.labd/settings.json` is ignored - and the banner says so - until
-  the project is trusted.
+- **A project can't point your token at another server, turn checkpoints off,
+  or raise the effort.** A `serverUrl`, `checkpoints` or `effort` in
+  `.labd/settings.json` is ignored, and the banner says so. Set them in
+  `~/.labd/settings.json` (or `LABD_SERVER_URL` for the server, `--think` for the effort). `labd trust`
+  does not change this.
 
 ## Files it keeps
 
@@ -183,10 +211,9 @@ Two more rules worth knowing before you point this at a repository you didn't wr
 | `.labd/extensions/` | per-project extensions, loaded once trusted |
 
 `settings.json` keys, global or per project: `timeout` as `commandTimeoutSeconds`
-(5–600), `effort` (`low`/`medium`/`high`), `checkpoints` (`true` by default),
-`mouse` (`true`; the full-screen session takes the mouse for scrolling), `sidebar`
-(`false`), and `serverUrl` — honoured from a project file only once that project
-is trusted. `mode` is read from the global file only.
+(5 to 600), `mouse` (`true`; the full-screen session takes the mouse for
+scrolling) and `sidebar` (`false`). Global file only: `mode`, `serverUrl`,
+`checkpoints` (`true` by default) and `effort` (`low`/`medium`/`high`).
 
 `LABD_HOME`, `LABD_SERVER_URL`, and `LABD_TOKEN` override the corresponding thing;
 the last is how you run labd in CI without pairing. `NO_COLOR` turns colour off,
@@ -227,7 +254,7 @@ The protocol is small:
 | `labd/capabilities` | mode, root, methods |
 | labd sends | |
 | `labd/ready` | first, on start: protocol, framing, session id, mode, root |
-| `labd/text`, `labd/status`, `labd/done`, `labd/error` | notifications as the turn runs |
+| `labd/text`, `labd/status`, `labd/done`, `labd/error` | notifications as the turn runs; `labd/error` carries `code` when the server gave one, and `credits` with `no_credits` |
 | `labd/tool` `{name, status, input, detail, preview, output, helper?}` | each tool step; `preview` is the diff or the command, `output` what came back, `helper` `{id, label}` when a helper made the call |
 | `labd/command_output` `{line, key?}` | a running command's own output, as it happens; `key` names a helper's call |
 | `labd/approve` `{call, preview, helper?}` | **a request to you** - answer `{approved: true\|false}`; `helper` names the helper asking |