@thedevlabs-io/labd 0.3.1

package/AGENTS.md

@@ -0,0 +1,264 @@
+# AGENTS.md - labd-cli
+
+Guidance for AI coding agents (and humans) working in this repository. This is
+the single source of truth for the project's conventions; `CLAUDE.md` imports
+this file so Claude Code and other tools share one set of rules.
+
+## What this is
+
+**labd-cli** is labd in a terminal - the third front door to the same assistant
+that lives in the learning portal and in the VS Code extension.
+
+The word "same" is load-bearing. This is **not** a second assistant that happens
+to look similar. It talks to the same server at `agent.thedevlabs.io`, over the
+same protocol, with the same prompt, the same memory, the same credit ledger, and
+the same permission model. A learner who asks labd something in their editor and
+then asks a follow-up in their terminal is talking to one assistant.
+
+That is why the interesting constraint in this repo is what it must NOT contain:
+
+- **no system prompt.** It lives in `@labd/protocol`, and the server builds it.
+- **no model choice, and no way to learn which model answered.** The protocol has
+  no model field; upstream errors are summarised by the server, never forwarded.
+- **no second definition of the permission matrix.** `needsApproval` comes from
+  the protocol. `ask` / `auto` / `agent` mean exactly what they mean in the editor.
+- **no second definition of what commands are refused.** `classifyCommand` comes
+  from the protocol too.
+
+If you are about to add assistant *behaviour* here - how it teaches, what it
+refuses, what it is told about the project - stop. It belongs in the
+[labd](https://github.com/thedevlabs-io/labd) repo, in `packages/protocol`, where
+both other surfaces get it too. This repo gathers context, renders a terminal, and
+executes tools.
+
+## Layout
+
+```
+packages/core/   the agent loop, tools, permission checks, sessions, checkpoints
+packages/tui/    terminal rendering - 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
+```
+
+The core/tui split is not tidiness. `packages/core` has no idea a terminal exists,
+which is what lets the interactive session, `labd -p`, and RPC mode drive one loop -
+and what makes the safety-critical parts testable without a screen.
+
+## The protocol comes from a submodule
+
+`@labd/protocol` is a private workspace package in the labd repo, so it is
+consumed here as a git submodule pinned to a commit:
+
+```bash
+git submodule update --init      # after cloning
+```
+
+Why a submodule rather than a copy: the protocol defines the permission matrix,
+the command denylist, and the path normalisation this CLI enforces. A copy would
+drift, and the way it would drift is by disagreeing with the editor about what
+labd is allowed to do. Bumping the pin is how this repo picks up a protocol change,
+and it should be its own commit so a promotion says plainly that the contract moved.
+
+**CI needs a credential for it.** The labd repo is private and the automatic
+`GITHUB_TOKEN` is scoped to one repository, so CI cannot clone the submodule with
+it - the failure reads as "Repository not found", which looks like a broken
+submodule rather than a missing secret. The workflow therefore fetches it in its
+own step and fails with an explanation. Add either a fine-grained PAT with read
+access to `thedevlabs-io/labd` as the repository secret `SUBMODULE_TOKEN`, or a
+deploy key on that repo with its private key as the secret.
+
+## The terminal is a different PLACE, not a second editor
+
+`surface: 'cli'` exists for one reason. The editor's prompt says labd can see "the
+lines they have on screen", their selection, and the errors the editor reports.
+None of that is true in a terminal, and a CLI reporting `surface: 'vscode'` would
+get a model confidently reasoning about a screen that is not there.
+
+So the CLI's honest context is the **project**: its name, the branch and recent
+commits, the conventions files, the names of any skills. Everything else labd reads
+on purpose, with a tool, and says which file it read. Resist adding anything
+screen-shaped - "the last file you edited" is a guess dressed as context.
+
+The RULES for gathering it are the protocol's, not ours: which files are secrets
+(`SECRETISH`), which directories are off limits, which conventions files to read
+and how much of them, what a skill looks like, how a branch is described. This
+repo keeps only the filesystem half - opening the files - so the editor and the
+terminal cannot tell the model two different stories about the same project.
+
+When a session ends - `/quit`, the end of `labd -p`, an RPC host closing stdin -
+the conversation is handed to `/v1/conversations/close` with tool results
+stubbed, exactly as the editor does when a chat is left. That call is what makes
+"same memory" true here; do not make it optional.
+
+## Permissions - the reason this repo exists
+
+pi.dev, the closest thing to prior art for a minimal terminal harness, is explicit
+that it has **no permission system**: it runs with the invoking user's rights and
+tells you to containerise it. That is a reasonable stance for a tool used by the
+person who wrote it. labd is used by learners in repositories they did not write,
+so the permission model is a feature rather than an omission, and these rules hold:
+
+| mode | changes files | runs a command |
+|---|---|---|
+| `ask` | asks | asks |
+| `auto` (default) | applies | asks |
+| `agent` | applies | runs |
+
+"Changes files" is all four writes: `edit_file`, `create_file`, `move_file`, and
+`delete_file`. Each is snapshotted, so `/undo` puts the whole turn back.
+
+`auto` is the default because `ask` made a real piece of work - reorganise this,
+rename that and fix the callers - into thirty approvals, which is a reason to give
+up halfway rather than a safety property. One exception, in `unattendedMode`: a
+run with nobody watching (`labd -p`, `--mode rpc`) falls back to `ask` unless a
+mode was actually chosen in a settings file or on the command line. A script has
+no one to show a diff to.
+
+- **The mode decides who clicks; it never decides what labd will do.**
+  `classifyCommand` refuses `sudo`, deploys, publishes, `git push`, disk wipes,
+  backgrounding, anything that never exits, anything that hides what it runs, and
+  anything naming a credentials file - in **all three** modes, `agent` included.
+- **The mode is never sent to the server.** Not in `ChatRequest`, not in the
+  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 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.
+- **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
+  no route to the model and would need its own approval rule, which is a second
+  definition of the permission matrix. An extension tool is therefore a protocol
+  change, and belongs in labd first. `registerCommand` cannot shadow a built-in,
+  because `/mode` and `/undo` have to mean what the learner expects.
+- **Unattended means declined.** `labd -p` has no way to ask, so every call that
+  needs approval is refused and the exit code is 2. There is deliberately no
+  `--yes`: the way to let an automated run write is to choose a mode in a settings
+  file, which is a decision with a record, not a flag buried in a shell script.
+
+## Writes land on disk, so checkpoints are not optional
+
+The extension edits an unsaved buffer, so a wrong edit costs one keystroke. There
+is no buffer here. Four rules follow, and `checkpoints.ts` explains each at the
+point it applies:
+
+- capture happens immediately before the write, off the text about to be replaced;
+- **capture can never fail a write** - an unsnapshotted file is recorded as such
+  and refused later, rather than blocking the edit;
+- conflicts are decided by **content hash**, never mtime, and a file the learner
+  edited since is left alone with a reason;
+- a restore is itself reversible, because an undo that cannot be undone is a trap.
+
+`run_command` is the exception nothing covers: a command's side effects are on disk
+before it exits. Say so rather than implying otherwise - the tool description tells
+the model to prefer `edit_file`, and the approval card tells the learner.
+
+## Sessions are trees
+
+Borrowed from pi, and worth keeping. Every node has an `id` and a `parentId`; the
+conversation is the path from the root to `head`. Branching moves the head and
+keeps both branches in one append-only JSONL file. Three things fall out of it:
+retrying an answer without losing the first, compaction that is lossy on the wire
+and lossless on disk, and a crash costing at most the last line.
+
+Do not "simplify" this into a list. The list version cannot do any of the three.
+
+## Terminal rules
+
+- **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.
+- **stdout is the answer. Everything else is stderr.** A pipeline must receive
+  only what labd meant as the answer.
+- **Escape sequences are written as `\u001b` escapes**, never as literal bytes, so
+  source files stay greppable ASCII.
+
+## Distribution
+
+Three artefacts, one source:
+
+- **`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 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.
+
+## Branches - promotion is by pull request, always
+
+`develop` → `staging` → `production`, one step at a time, and **every step is a
+pull request** - the same rule as the other Dev Labs repos, for the same reason:
+the PR is the record of what shipped and when, and it is the only place a bad
+promotion gets caught before it is live.
+
+Never push directly to `staging` or `production`, and never move them with
+`git branch -f` or a force push. `.githooks/pre-push` refuses the direct push;
+turn it on once per clone:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+## Testing
+
+`npm test` runs vitest. `npm run check` runs the typecheck too.
+
+What is worth testing here is not "does it answer" - that needs a model - but the
+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
+  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.
+- **checkpoints** (`tools.test.ts`): a conflicting edit is refused, a created file
+  is deleted rather than blanked, a capture failure never blocks a write.
+- **framing** (`rpc.test.ts`): splitting on `\n` only. There is a test that
+  demonstrates why `node:readline` is wrong here; if someone switches to it, that
+  test explains the bug.
+- **the whole binary** (`e2e.test.ts`): a fake agent server, a real subprocess.
+  This is where "the mode never reaches the wire" and "unattended declines" are
+  actually proven.
+
+`e2e.test.ts` needs `npm run build` first.

package/README.md

@@ -0,0 +1,276 @@
+# labd-cli
+
+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]
+```
+
+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.
+
+## 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+:
+
+```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:**
+
+```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
+```
+
+</details>
+
+## Using it
+
+```bash
+labd                            # a session in the current project
+labd "why is this test failing" # one question, then exit
+labd -p "..." | pbcopy          # print mode, for pipes and scripts
+cat build.log | labd -p "why?"  # piped input joins the question
+labd --mode rpc                 # JSON-RPC over stdio, to embed it
+labd -c                         # pick up the most recent session here
+```
+
+| flag | |
+|---|---|
+| `-p`, `--print` | answer and exit instead of starting a session |
+| `--json` | newline-delimited JSON events instead of prose (implies `-p`) |
+| `--mode <ask\|auto\|agent>` | the permission mode for this run; `--mode rpc` is the transport |
+| `--think <low\|medium\|high>` | reasoning effort to ask for (the server decides what it honours) |
+| `--resume <id>` | continue an earlier session; an id that matches nothing is an error, not a new session |
+| `-c`, `--continue` | continue the most recent session in this project |
+| `-C`, `--cwd <dir>` | run as though started in `<dir>` |
+| `-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 |
+| `-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.
+
+| command | |
+|---|---|
+| `/mode [ask\|auto\|agent]` | how much labd does without asking |
+| `/think [low\|medium\|high]` | how hard it thinks (a request — the server decides) |
+| `/undo` | put back the files the last answer changed |
+| `/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 |
+| `/usage` | what's left of this month's allowance |
+| `/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 |
+
+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
+leaves, so no file contents travel for that.
+
+## The three modes
+
+| mode | changes files | runs a command |
+|---|---|---|
+| `ask` | asks first | asks first |
+| `auto` (default) | on its own | asks first |
+| `agent` | on its own | on its own |
+
+Changing a file means any of the four: editing one, creating one, moving one, or
+deleting one. `auto` splits where it does because the two columns are not equally
+reversible: every write is snapshotted and `/undo` puts the whole turn back, while
+a command has already happened.
+
+`labd -p` and `--mode rpc` are the exception. With nobody watching they ask -
+which unattended means refusing - unless you have actually chosen a mode.
+
+**Some things are refused in every mode, `agent` included** — anything needing
+`sudo`, deploying, publishing, `git push`, wiping a disk, backgrounding a process,
+anything that never exits, and anything that reads a credentials file. The mode
+decides who clicks; it never decides what labd is willing to do.
+
+Two more rules worth knowing before you point this at a repository you didn't write:
+
+- **A project can't set the mode.** `.labd/settings.json` may set a timeout; `mode`
+  comes from your global settings or the command line only. Otherwise cloning a
+  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.
+
+## Files it keeps
+
+| path | |
+|---|---|
+| `~/.labd/auth.json` | your token, mode `0600`, never in the project |
+| `~/.labd/settings.json` | global settings, including `mode` |
+| `~/.labd/sessions/` | JSONL session trees, bucketed by project |
+| `~/.labd/checkpoints/` | snapshots, so `/undo` works |
+| `.labd/settings.json` | per-project settings (not `mode`) |
+| `.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.
+
+`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
+
+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:
+
+```bash
+node examples/orchestrate.mjs "what does this file do?" src/a.ts src/b.ts src/c.ts
+```
+
+[`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 | |
+|---|---|
+| `labd/prompt` `{question}` | run a turn; resolves with `{text, wrote, ran}`. A second prompt sent before the first resolves is queued behind it |
+| `labd/session` | id, file, node count, head |
+| `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/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}` |
+
+Closing stdin ends the session: any turn in flight finishes, the conversation is
+handed over for memory, and the process exits 0.
+
+Two things to get right, both of which have tests in this repo:
+
+- **Split records on `\n` and nothing else.** Not `readline`: it also splits on
+  U+2028 and U+2029, which occur inside real JSON strings, and it will cut a valid
+  record in half.
+- **Answer `labd/approve`.** Ignore it and the child refuses after two minutes,
+  which is the safe direction but a slow one. There is deliberately no RPC method
+  for *changing* the mode: a host that could raise it would be a host that turns
+  approvals off for the person who launched labd.
+
+## Extensions
+
+A module that gets an API object, and can add slash commands and watch what labd
+does:
+
+```js
+// ~/.labd/extensions/branches.mjs
+export default function (labd) {
+  labd.registerCommand('branches', {
+    describe: 'list local branches',
+    run: async () => execSync('git branch', { cwd: labd.root }).toString(),
+  });
+
+  labd.on('tool', (step) => { /* observe; handlers cannot veto */ });
+  labd.on('turn', ({ question }) => {});
+}
+```
+
+A command can't shadow a built-in (`/mode` has to mean `/mode`). Extensions
+cannot add **tools** the model can call: the tool list is the protocol's, shared
+with the editor, so a new tool is a change to the labd repo rather than to a file
+in `~/.labd/extensions`.
+
+## Development
+
+```bash
+npm run build      # bundle to dist/labd.js
+npm test           # vitest (build first — the e2e suite spawns the binary)
+npm run check      # typecheck + tests
+```
+
+Conventions, and the reasoning behind the permission model, are in
+[AGENTS.md](AGENTS.md). Promotion is `develop` → `staging` → `production`, one
+pull request per step; turn the guard on with
+`git config core.hooksPath .githooks`.
+
+## Prior art
+
+The shape of this owes a lot to [pi](https://pi.dev) (`earendil-works/pi`) — the
+layered packages, sessions as trees, the print/RPC/SDK modes, and the framing
+detail that stdio JSONL must be split on `\n` and nothing else. Where labd-cli
+differs is the thing pi deliberately leaves out: pi has no permission system and
+tells you to containerise it, which is right for a tool you built for yourself and
+wrong for one a learner points at a repository they just cloned.