@thedevlabs-io/labd 0.3.1 → 0.6.0

package/AGENTS.md

@@ -35,7 +35,7 @@ executes tools.
 
 ```
 packages/core/   the agent loop, tools, permission checks, sessions, checkpoints
-packages/tui/    terminal rendering - differential redraw, markdown, cards
+packages/tui/    terminal rendering - the full screen, differential redraw, markdown, cards
 packages/cli/    the binary: config, auth, extensions, and the four run modes
 vendor/labd/     submodule - the labd repo, for @labd/protocol
 test/            vitest; `e2e.test.ts` runs the built binary against a fake server
@@ -176,52 +176,111 @@ Do not "simplify" this into a list. The list version cannot do any of the three.
 
 ## Terminal rules
 
+Two kinds of program live in this repo, and the rules differ by which one you are in.
+
+**The interactive session owns the screen.** `labd` on its own runs
+`modes/screen.ts`: the alternate screen buffer, a scrollable transcript, a
+multi-line composer, popups for `/` and `@`, dialogs for lists, approvals inline.
+This replaced the "print into the scrollback, keep one live box at the bottom"
+model in 0.4.0. That model was principled - the terminal owned the transcript, so
+search and copy came free - and learners did not want it: they wanted an app, not
+a log. `--plain` still runs the old loop for one release and is deprecated. Rules
+for the screen:
+
+- **Full-screen only when stdin AND stdout are TTYs.** Anything else falls
+  through to the printing modes below; a learner must never type blind.
+- **Give the terminal back, whatever happens.** `Screen.leave` runs from the
+  normal exit, the `finally`, the signal handlers and the process `exit` hook, in
+  the reverse order of `enter`, and is idempotent. Raw mode or the alternate
+  screen left on looks like a broken machine.
+- **Frames are whole and drawn differentially with absolute positions.** No
+  relative cursor moves: there is no scrollback to keep in step with.
+- **Pure logic is separate from I/O.** `keys`, `layout`, `transcript`, `editor`,
+  `popup`, `dialog` know nothing about a stream and are tested without one.
+  `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.
+
+**The non-interactive modes own nothing and print.** `labd -p`, `--json`,
+`--mode rpc`, and anything with a piped stdout use `Renderer` and plain writes:
+
 - **Never assume a TTY.** Piped, redirected, or in CI, colour is off and the live
   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. That is what keeps search,
-  selection, and copy-paste working.
+  terminal; only the status line is a live region.
 - **stdout is the answer. Everything else is stderr.** A pipeline must receive
-  only what labd meant as the answer.
+  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.
+
+**Everywhere:**
+
 - **Escape sequences are written as `\u001b` escapes**, never as literal bytes, so
   source files stay greppable ASCII.
+- **Zero runtime dependencies.** No ink, no blessed, no opentui: the TUI is the
+  repo's own `Screen` and differential drawing, so the bundle stays one file and
+  still works as a Node single-executable.
 
 ## Distribution
 
-Three artefacts, one source:
+**The GitHub organisation is private, and public docs must not link to it.**
+Learners cannot reach `github.com/thedevlabs-io/*`, raw.githubusercontent.com,
+or GitHub Release assets. The public channels are npm (`@thedevlabs-io/labd`, bin
+`labd`) and the VS Code Marketplace (`thedevlabs-io.labd`); README.md and every
+user-facing string point at those and nowhere else. This file is for
+contributors with access, so it may name the repositories.
+
+Two bundles, one source, one channel:
 
 - **`dist/labd.js`** - ESM, zero runtime dependencies, what npm's `bin` points at.
-- **`dist/labd.cjs`** - the same code as CommonJS. It exists because Node's
-  single-executable support runs its entry as CJS and refuses an ESM one outright.
-  This is why `bin/labd.ts` must never use top-level await.
-- **`dist/bin/labd-<os>-<arch>`** - a standalone executable, built by injecting the
-  CJS bundle into a copy of the `node` binary. Not cross-compilable, so the release
-  workflow builds one per runner. ~115 MB, ~40 MB compressed: the honest price of
-  "works on a machine with nothing installed".
-
-macOS needs the signing dance in `build-binaries.mjs`, and it is not optional -
-injecting invalidates the signature, and macOS kills an invalidly-signed binary
-rather than running it. The build also RUNS the binary before calling it done,
-because every one of those steps fails by producing something that does not start
-rather than by erroring.
+  `npm install -g @thedevlabs-io/labd` is the install; `npm update -g` the upgrade.
+- **`dist/labd.cjs`** - the same code as CommonJS. Kept because Node's
+  single-executable support runs its entry as CJS and refuses an ESM one, so a
+  standalone build stays possible without a code change. This is why `bin/labd.ts`
+  must never use top-level await; CI runs the CJS bundle to prove it loads.
+
+Standalone binaries, the install scripts and the GitHub Release step were removed
+in 0.4.0: they were only reachable through GitHub, which learners cannot see.
 
 `npm install -g git+ssh://...` cannot work: `dist/` is not committed and npm does
 not fetch submodules for a git dependency. `scripts/prepare.mjs` says so rather
 than letting the install appear to succeed with no binary - which is what it did
 before, reporting "added 1 package" and installing nothing.
 
-## Sub-agents - deliberately outside
-
-There is no `spawn_agent` tool, and adding one would be a permission mistake. Such
-a tool has to decide what mode the children run in: inherit the parent's and one
-approval becomes N unattended writes; give children their own and the model has
-been handed the setting it is specifically not allowed to influence.
-
-`--mode rpc` already makes every labd process a driveable agent, so orchestration
-lives in a script the operator writes - where the children's mode is set by a
-person, each child asks that script for approval over the wire, and there is no RPC
-method for changing a mode. `examples/orchestrate.mjs` is the reference, and
-`test/rpc-e2e.test.ts` runs two children at once to prove it.
+## Helpers - inside the permission model, not beside it
+
+This section used to be "Sub-agents - deliberately outside", and its argument was
+right about the design it rejected: a `spawn_agent` tool whose children ran in the
+parent's mode would turn one approval into N unattended writes, and children with a
+mode of their own would hand the model the one setting it must not touch. The
+helpers labd has now avoid both, because **there is no approval to spawn and no
+mode for a helper to have**:
+
+- Spawning changes nothing, so it asks nothing. What a helper then DOES is checked
+  call by call: every write and command goes through `executeCall`
+  (`packages/core/src/calls.ts`) - the same code the turn's own calls go through -
+  and `needsApproval` against the learner's mode. So `auto` still asks about every
+  command a helper wants to run, and `ask` about every write.
+- Its cards join the turn's line: one at a time, marked "from a helper", and once
+  the turn is stopped nothing still waiting is asked.
+- **Unattended means declined, for helpers too.** `labd -p` has no one to ask, so a
+  helper's write is refused and the run exits 2. `e2e.test.ts` proves it.
+- One level: a helper is offered every tool but `spawn_agent` and refuses it if
+  called. At most `MAX_SUBAGENTS` at once; the rest are refused with a reason.
+- It shares the turn's ToolContext, so its writes are in the turn's checkpoint
+  and `/undo` puts them back with the rest.
+- It writes nothing to the session but the parent's call and its report, and is
+  never handed to memory on its own.
+- The helper's brief, the report bound and when to use one are the protocol's
+  (`subAgentBrief`, `SUBAGENT_REPORT_CHARS`, the prompt's "Helpers" section), not
+  this repo's.
+
+`test/helpers.test.ts` pins these against the real tools and checkpoint store.
+
+**Orchestration across processes is still outside, and still the right tool for
+it.** `--mode rpc` makes every labd process a driveable agent, where each child's
+mode is set by the person who wrote the script and each child asks that script for
+approval. `examples/orchestrate.mjs` is the reference; `test/rpc-e2e.test.ts` runs
+two children at once. An RPC host is told which helper is asking on `labd/approve`.
 
 ## Branches - promotion is by pull request, always
 

package/README.md

@@ -3,80 +3,49 @@
 labd in your terminal — the Dev Labs assistant, in the project you're standing in.
 
 ```
-$ labd
-[o_o] labd in labd-cli on develop
-  labd changes files on its own - every answer can be put back in one go - and still asks before running a command.
-
-> why is session.test.ts failing?
-
-  ● Read   test/session.test.ts
-  ? Run a command
-    to see which of the eleven cases fails
-
-    npx vitest run test/session.test.ts
-
-    On auto, commands still ask - a command can do anything your shell can, and put back isn't one of them.
-    run this command? [y/N]
+ [o_o] labd  ·  labd-cli  develop  ·  session 3f9a12c0                          auto
+ ─────────────────────────────────────────────────────────────────────────────────
+ > why is session.test.ts failing?
+
+   ● Read   test/session.test.ts
+   ? Run a command
+     to see which of the eleven cases fails
+
+     npx vitest run test/session.test.ts
+
+     On auto, commands still ask - a command can do anything your shell can, and
+     put back isn't one of them.
+     y to allow  ·  n or esc to decline
+ ╭───────────────────────────────────────────────────────────────────────────────╮
+ │ > ask labd something  -  / for commands  -  @ to tag a file                   │
+ ╰───────────────────────────────────────────────────────────────────────────────╯
+  y allow · n decline · ctrl+c stop                              context 12% · credits 82%
 ```
 
-This is the same assistant as the [VS Code extension](https://github.com/thedevlabs-io/labd)
-and the one docked in the learning portal — same server, same prompt, same memory,
-same permission model. Ask something in your editor, follow up in your terminal.
+This is the same assistant as the labd VS Code extension (Marketplace:
+`thedevlabs-io.labd`) and the one docked in the learning portal at
+[learn.thedevlabs.io](https://learn.thedevlabs.io) — same server, same prompt,
+same memory, same permission model. Ask something in your editor, follow up in
+your terminal.
 
 ## Install
 
-**macOS / Linux** — a standalone executable. Nothing else needs to be installed:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/thedevlabs-io/labd-cli/production/install.sh | sh
-```
-
-**Windows** — same, in PowerShell:
-
-```powershell
-irm https://raw.githubusercontent.com/thedevlabs-io/labd-cli/production/install.ps1 | iex
-```
-
-**With npm**, if you already have Node 22+:
+You need Node 22 or newer. Then:
 
 ```bash
 npm install -g @thedevlabs-io/labd
-```
-
-Then connect:
-
-```bash
 labd login                      # approve a short code in your browser
 ```
 
-<details>
-<summary>Other ways, and what each is for</summary>
-
-| how | when |
-|---|---|
-| `install.sh` / `install.ps1` | a machine with nothing on it. Downloads a ~40 MB archive containing a single executable with the Node runtime inside it. |
-| `npm install -g @thedevlabs-io/labd` | you have Node. Smaller download, and `npm update -g @thedevlabs-io/labd` upgrades it. |
-| `npm pack` → share the `.tgz` | an air-gapped machine, or pinning an exact build. `npm install -g thedevlabs-io-labd-0.3.1.tgz`. |
-| copy `dist/labd.js` | you built from source. It has **zero runtime dependencies**, so that one file plus Node 22+ is a working install anywhere. |
-| clone + `npm link` | working on labd itself. |
-
-`npm install -g git+ssh://…` does **not** work, and says so rather than half-installing: `dist/` is not committed, and npm does not fetch the git submodule that the build needs.
-
-While this repository is private, the install scripts need a credential to read release assets. They use the GitHub CLI when it is signed in, or `GH_TOKEN` if you set one, and explain that rather than failing with a 404.
-
-**Building from source:**
+To upgrade:
 
 ```bash
-git clone git@github.com:thedevlabs-io/labd-cli.git
-cd labd-cli
-git submodule update --init     # the protocol lives in the labd repo
-npm install
-npm run build                   # dist/labd.js  (and dist/labd.cjs, for binaries)
-npm link                        # puts `labd` on your PATH
-npm run build:binary            # optional: a standalone executable for this platform
+npm update -g @thedevlabs-io/labd
 ```
 
-</details>
+The package is one bundled file with zero runtime dependencies, so that is the
+whole install. There are no standalone binaries and no `curl | sh` installer: npm
+is the one public channel.
 
 ## Using it
 
@@ -101,14 +70,53 @@ labd -c                         # pick up the most recent session here
 | `-e`, `--extension <path>` | load an extension file (repeatable; `/reload` keeps it) |
 | `--no-extensions` | load none, now and on `/reload` |
 | `--no-color` / `--color` | force colour off or on |
+| `--no-mouse` | leave the mouse to the terminal, for native text selection |
+| `--plain` | the older print-style session (deprecated; removed in 0.5) |
 | `-v`, `--version` | |
 
 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).
 
-Inside a session: `@path` tags a file into your question, Tab completes both those
-and `/commands`, ctrl-c stops an answer without leaving.
+### Inside a session
+
+`labd` on its own opens a full-screen session: a header, a scrollable transcript,
+a box to type in at the bottom, and a footer with the keys that apply right now
+and how full the conversation is. The transcript follows the answer as it
+streams; scroll up and it stops following and tells you how many lines have
+arrived since (`End`, or scrolling back to the bottom, follows again).
+
+| key | |
+|---|---|
+| `enter` | send |
+| `shift+enter`, `ctrl+j`, or a line ending in `\` | new line in the box (it grows to 8 rows) |
+| `/` | a list of commands appears above the box; `↑↓` moves, `tab`/`enter` accepts, `esc` closes |
+| `@` | the same, for files in the project — `@src/index.ts` tags the file into the question |
+| `tab` | complete the command or path being typed |
+| `shift+tab` | next mode: `ask`, `auto`, `agent` - the same as `/mode`, and it says what the new mode does |
+| `pgup` / `pgdn`, mouse wheel | scroll the transcript |
+| `home` / `end` | top / bottom of the transcript (with an empty box; otherwise they move within the line) |
+| `↑` / `↓` | earlier questions, when the caret is on the first / last line |
+| `esc` | close a list or dialog; otherwise jump back to the bottom |
+| `y` / `n` | answer an approval card. Nothing else answers it, and `enter` never does |
+| `ctrl+c` | stop the answer; else clear the box; else press it again within 2 s to quit |
+| `ctrl+d` | quit |
+| `ctrl+n`, `ctrl+o` | new session, earlier sessions |
+| `ctrl+l` | redraw |
+
+`/help`, `/sessions` and `/tree` open a dialog you can type into to narrow the
+list; `enter` picks — a session to resume, or a point in this session to continue
+from. Approvals are never dialogs: the card is drawn inline in the transcript
+with its context, and `y` is the only key that allows it.
+
+Two flags for the screen. `--no-mouse` leaves the mouse to the terminal (the
+session takes it for wheel scrolling, and native text selection needs it
+released); `mouse: false` in a settings file does the same. `--plain` runs the
+older print-style session, where answers land in the terminal's scrollback and
+only the box is redrawn — kept for one release for terminals that cannot cope
+with the alternate screen, and deprecated. `sidebar: true`, or `/sidebar`, adds
+a panel with the project, branch, mode and recent steps when there are 120 or
+more columns.
 
 | command | |
 |---|---|
@@ -118,7 +126,9 @@ and `/commands`, ctrl-c stops an answer without leaving.
 | `/redo` | reapply what `/undo` put back |
 | `/tree` | every point in this session; branch from any of them |
 | `/resume <id>` | continue from a point in `/tree` |
-| `/sessions`, `/session` | earlier sessions here; where this one is stored |
+| `/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 |
 | `/trust` | let this project load its own extensions |
 | `/reload` | reload extensions and the file list |
@@ -173,20 +183,33 @@ 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), and
-`serverUrl` — honoured from a project file only once that project is trusted.
-`mode` is read from the global file only.
+(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.
 
 `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,
 `FORCE_COLOR` turns it on (`FORCE_COLOR=0` off) and wins over everything else, and
 `LABD_NO_MOTION` skips the opening animation.
 
-## Sub-agents and orchestration
+## Helpers and orchestration
 
-labd has no `spawn_agent` tool, and that is a decision rather than a gap. It does
-have `--mode rpc`, which makes every labd process a driveable agent on
-stdin/stdout — so an orchestrator is a script that spawns several of them:
+**Helpers.** labd can hand a self-contained piece of a job to a helper - another
+labd with the same tools, working from a brief labd writes, whose report comes
+back into the answer. Several can run at once, up to three. A helper is not a way
+around your settings:
+
+- a helper has no mode of its own. Its writes and commands ask you exactly when
+  labd's would, one card at a time, marked **from a helper**;
+- under `labd -p` nothing can be approved, so a helper's changes are declined and
+  the run exits 2;
+- what a helper changed is part of the answer, so `/undo` puts it back too;
+- a helper cannot start helpers of its own.
+
+**Orchestration.** `--mode rpc` makes every labd process a driveable agent on
+stdin/stdout, so an orchestrator is a script that spawns several of them, each
+with a mode you choose:
 
 ```bash
 node examples/orchestrate.mjs "what does this file do?" src/a.ts src/b.ts src/c.ts
@@ -195,14 +218,6 @@ node examples/orchestrate.mjs "what does this file do?" src/a.ts src/b.ts src/c.
 [`examples/orchestrate.mjs`](examples/orchestrate.mjs) is ~140 lines: spawn, send
 `labd/prompt`, read the notification stream, run three at a time.
 
-**Why not a tool inside labd.** A `spawn_agent` tool has to decide what mode the
-children run in, and every answer is bad. Inherit the parent's mode and one
-approval becomes N unattended writes. Give children their own mode and the model
-has been handed the one setting it is specifically not allowed to influence.
-Outside, the mode of each child is set by whoever wrote the script, each child
-asks *that script* for approval over the wire, and the orchestrator is code you
-can read. (Pi reaches the same conclusion and suggests tmux.)
-
 The protocol is small:
 
 | you send | |
@@ -213,9 +228,9 @@ The protocol is small:
 | 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/tool` `{name, status, input, detail, preview, output}` | each tool step; `preview` is the diff or the command, `output` what came back |
-| `labd/command_output` `{line}` | a running command's own output, as it happens |
-| `labd/approve` `{call, preview}` | **a request to you** — answer `{approved: true\|false}` |
+| `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 |
 
 Closing stdin ends the session: any turn in flight finishes, the conversation is
 handed over for memory, and the process exits 0.
@@ -256,7 +271,7 @@ in `~/.labd/extensions`.
 ## Development
 
 ```bash
-npm run build      # bundle to dist/labd.js
+npm run build      # bundle to dist/labd.js (and dist/labd.cjs)
 npm test           # vitest (build first — the e2e suite spawns the binary)
 npm run check      # typecheck + tests
 ```