@thedevlabs-io/labd 0.5.0 → 0.6.0

package/AGENTS.md

@@ -246,18 +246,41 @@ 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

@@ -93,6 +93,7 @@ arrived since (`End`, or scrolling back to the bottom, follows again).
 | `/` | 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 |
@@ -192,11 +193,23 @@ 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
@@ -205,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 | |
@@ -223,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.