@aragon-agent/cli 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -9,6 +9,111 @@ were written.
 
 ### Added
 
+- **The composer understands pasting.** Until now it did not have the concept at
+  all: every byte the terminal delivered on stdin was a keystroke, and a
+  clipboard block is thousands of bytes arriving in an unpredictable number of
+  chunks. Three separate failures fell out of that one omission, and on Windows
+  you hit all three at once.
+
+  A carriage return that landed alone in a chunk **sent the half-finished
+  message** — a fifteen-line paste could arrive as a dozen separate messages,
+  interleaved with the agent's replies. A carriage return in the middle of a
+  chunk was inserted into the draft as a literal `\r`, which the terminal obeyed
+  by **overwriting the row it was drawn on**. And a paste that survived both grew
+  the composer to the height of the pasted text, pushing the transcript out of a
+  frame whose row accounting still believed the composer was three rows tall.
+
+  Pasting now works the way it reads:
+
+  - **A paste never submits.** Line breaks become buffer newlines, exactly one
+    per source line break, `CRLF` and lone `CR` alike.
+  - **A short paste appears verbatim.** At or below 6 lines and 400 characters it
+    is inserted as-is, indentation intact, and renders exactly like typed text.
+  - **A large paste collapses to a placeholder** — `[Pasted text #1 +218 lines]`
+    — which occupies one line, carries its own size in its label, deletes as a
+    single unit (one `Backspace`, and `Ctrl+W` / `Ctrl+U` / `Ctrl+K` cannot leave
+    half of one behind), and expands back to the full text the moment you send.
+    The model receives every byte; the composer never has to draw them.
+  - **No pasted byte is executed as a terminal control.** `\r`, `\x1b`, NUL, DEL
+    and the C1 range are stripped from the payload — never from your keystrokes,
+    so `Ctrl+A` and Escape are untouched.
+  - **The composer has a ceiling.** A draft of any length occupies at most 3 / 6 /
+    10 rows depending on terminal height, scrolls internally to keep the caret
+    visible, shows how many rows are hidden above and below, and reports its true
+    height to the layout budget. Four hundred presses of `Shift+Enter` were
+    already able to destroy the frame; they no longer are.
+  - **A submitted message cannot make the transcript unresponsive.** A user entry
+    renders at most 40 rows plus a `... +N more lines` tail. The full text is kept
+    and the exit transcript is uncapped.
+
+  On terminals that support it, detection is **exact**: aragon asks for bracketed
+  paste (`DECSET 2004`) in full-screen mode and reads the markers the terminal
+  wraps your paste in. Where that is unavailable — inline mode, an old Windows
+  console — a heuristic on chunk shape catches the same cases, and it needs no
+  cooperation from the terminal at all. Both feed one code path.
+
+  Turn it off with `--no-paste`, `ARAGON_PASTE=0`, or
+  `aragon config set paste false`; the input path is then byte-for-byte what
+  0.6.2 did.
+
+### Fixed
+
+- **A pasted API key is stored correctly again.** Ink broadcasts each stdin chunk
+  to every mounted input handler, so the settings screen, the question overlay
+  and the plan-review feedback field all see what the composer sees. Without
+  this, a ~100-character key pasted into Settings would have been stored wrapped
+  in invisible framing bytes, masked on screen by the password dots, and would
+  have failed to authenticate on every request afterwards with nothing anywhere
+  explaining why.
+
+- **`--no-mouse` still writes no mouse sequence.** Paste support installs a
+  stdin filter, and `paste` defaults to on, so the filter now exists in sessions
+  that disabled the mouse. Whether the mouse is on is a separate question from
+  whether the stream is wrapped, and the four places that used to conflate them
+  now ask the right one: `aragon --no-mouse` writes no `?1000h`, no `?1006h` and
+  no `?1002h`, leaves your terminal's own click-drag selection alone, and reports
+  `/mouse` as off — while pasting still works.
+
+### Changed
+
+- **Auto-compaction no longer reports compactions that did not happen.** A long
+  unattended run used to print a red `context not compacted #2: nothing_to_drop`
+  card into the transcript. The card was accurate; nobody had asked for it.
+  Auto-compaction evaluates itself at every turn boundary, and a checkpoint that
+  looks at the history and finds nothing worth dropping has changed nothing,
+  called nothing and spent nothing — a smoke alarm announcing "no fire" twice an
+  hour, in error colours, with a machine reason attached.
+
+  A compaction now announces itself **if and only if it commits to doing work**.
+  That is a position in the control flow, not a list of reason strings: everything
+  decided before the first spend is silent, and everything decided after it —
+  including every failure, the truncation fallback, an Esc, and a host fault — is
+  as loud as it ever was. A declined `pressure` checkpoint is now
+  indistinguishable from a turn on which the threshold was never crossed.
+
+  **`/compact` and overflow recovery are unchanged.** A compaction you asked for
+  is owed an answer, and a reactive compaction running after the provider has
+  already refused your request is the one moment the diagnosis matters most. Both
+  still report on every outcome.
+
+  **Quiet, not unrecorded.** Every attempt is still written to the diagnostic log
+  (its `compaction` line gains an `announced` field, so `announced: false` is one
+  grep), still charged to the anti-loop guards, and still counted by
+  `/compact status` — which now reads
+  `This session: 1 compaction (2 checkpoints declined), 94.2k tokens reclaimed`
+  when checkpoints declined, and is byte-identical to before when none did. If
+  declines keep happening, the self-disable notice still says so out loud, once,
+  naming the cause and the remedies. Card numbers are also contiguous again: `#N`
+  counts compactions that ran, not checkpoints that fired.
+
+  **Behaviour change for wrapper scripts.** A declined `pressure` compaction no
+  longer emits a `{ type: 'compaction', subtype: 'start' | 'end' }` pair on the
+  `--output-format json` stream, and no longer prints `[compaction] skipped:` on
+  `-p` stderr. The pairs stay balanced, so only consumers counting *attempts* are
+  affected; the diagnostic log reports those more accurately.
+
+### Added
+
 - **Context compaction, hardened — the trigger now counts the whole history, the
   recent turns can no longer wedge a run, sub-agents get the same protection, and
   a compaction is no longer irreversible.**

package/README.md

@@ -413,6 +413,7 @@ signal ends the run (`130` SIGINT, `143` SIGTERM, `129` SIGHUP).
 | `/retry [show\|on\|off\|max <n>]` | API retry: the effective ladder, the on/off switch, the retry count. Takes effect **in the running session**, children included |
 | `/fast [on\|off\|model <id>\|provider <id>\|same\|review <n\|off>\|delegate on\|off]` | Fast model tier: status and this session's totals, the on/off switch, which model, the review cadence |
 | `/compact [status\|on\|off\|threshold <n>\|keep <n>\|history\|show <n>\|<instructions>]` | Context compaction: occupancy and this session's totals, the on/off switch, when it fires, how much it keeps. With free text, compacts now and tells the summarizer what to pay attention to |
+| `/bg [list\|logs <id> [n]\|stop <id\|all>\|status]` | Background services: what is running, its log tail, and how to stop it. `list` is the default |
 | `/update [status\|now\|skip\|off]` | Auto-update: what is running, what is available, where it came from, when it looks again. `now` forces a check past the throttle; `skip` declines the offered version until a newer one appears |
 | `/theme <auto\|warm\|cool\|light>` | Switch the color theme live (persisted) |
 | `/expand [n]` | Expand / collapse the n-th-from-last (default last) tool card |
@@ -437,10 +438,12 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan`. On Windows this needs a console flag Node < 22.17 does not set; aragon sets it at startup — see [Requirements](#requirements) |
 | `Ctrl+P` | The same toggle, over a channel no Windows console can swallow. Use it if `Shift+Tab` does nothing |
 | `Esc` | Abort the run / close an overlay / close a popup |
-| `Ctrl+C` ×2 | Exit (first press warns) |
+| `Esc` ×2 | **Force-stop** a run that did not abort: kills the shell command it is blocked on and returns the view to `idle`. The second press only does anything while the run is *still* running, so in a healthy run it is a no-op |
+| `Ctrl+C` | Stop the background **services** the agent started, when there are any. It does not arm exit |
+| `Ctrl+C` ×2 | Exit (first press warns), once no services are running |
 | `Ctrl+L` | Redraw the frame (clear the screen in inline mode) |
 | `Ctrl+T` | Show / hide thinking (**off by default**). In inline mode it applies to the live entry and everything drawn after it — settled entries are already in your terminal's scrollback and cannot be repainted |
-| `Ctrl+O` | Expand / collapse the most recent tool card — including its diff |
+| `Ctrl+O` | Expand / collapse the most recent tool, team, compaction or **service** card — including a diff or a service's log tail |
 | `PgUp` / `PgDn` | Scroll the transcript a page (full-screen mode) |
 | `Shift+↑` / `Shift+↓` | Scroll the transcript a line (full-screen mode) |
 | Mouse wheel | Scroll the transcript (or the open overlay). On Windows needs Node ≥ 22.17 — see [Requirements](#requirements) |
@@ -450,6 +453,7 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `Ctrl+W`, `Alt+Backspace` | Delete the previous word |
 | `Ctrl+U` / `Ctrl+K` | Kill to line start / end |
 | `Up` / `Down` | Move between draft lines; recall prompt history at the edges |
+| Paste | Inserted as-is up to 6 lines / 400 chars; larger collapses to `[Pasted text #1 +15 lines]`, which deletes as one unit and expands in full when you send. `--no-paste` restores the pre-0.6.3 behaviour |
 | `?` | Open help (empty input) |
 
 In **full-screen mode** the transcript is scrolled by the app itself: `PgUp` /
@@ -908,6 +912,94 @@ delegation tool (see below). `--no-team` removes it again.
 With todo planning on — also the default — one more is added: `todo_write`, the
 planning tool (see above). `--no-todo` removes it again.
 
+With background services on — also the default — two more are added:
+`bash_output` and `bash_kill` (see below), and `bash` itself gains a `background`
+parameter. `bash.background: false` removes all three again.
+
+## Background services
+
+The agent can write a web app; it also has to be able to **run** one. A command
+that never exits on its own — `npm run dev`, `uvicorn main:app`, `vite`,
+`docker compose up`, `tsc --watch` — is not a hung tool, it is a server, and
+running it in the foreground stalls the turn until the tool timeout kills it
+three minutes later.
+
+So those commands are **supervised** instead. `bash` gains one optional
+parameter:
+
+```jsonc
+{ "command": "npm run dev", "background": true }
+```
+
+`true` supervises it, `false` never does, and **omitting it lets the runtime
+decide** from the command itself — a closed allowlist over the leading token and
+the script name (`npm|pnpm|yarn|bun run dev|start|serve|watch|preview`,
+`next dev`, `vite`, `nuxt dev`, `ng serve`, `nodemon`, `tsc --watch`, `uvicorn`,
+`gunicorn`, `flask run`, `manage.py runserver`, `rails server`, `php -S`,
+`cargo watch`, `docker compose up` without `-d`, `tail -f`, `watch `). It never
+fires on a chained command, because a chain's tail is what you actually wanted
+the result of, and `npm run build` and `npm test` are deliberately not on it.
+
+A supervised launch returns as soon as there is something true to say — the
+**first** of ready, exited, or four seconds — so a server that crashes on boot is
+reported in 400 ms with the stack in the result rather than after a three-minute
+stall:
+
+```
+$ npm run dev
+[background] service s1 started (pid 24188)
+[ready] http://localhost:3000  (detected from output after 1.4s)
+[log tail]
+  > next dev
+    - Local:  http://localhost:3000
+Read more with bash_output({ service: "s1" }); stop it with bash_kill({ service: "s1" }).
+```
+
+Readiness is a URL the server printed, or one TCP connect to a port the command
+named — and if that port was **already answering before the launch**, the probe
+is switched off and the card says so, rather than calling somebody else's server
+yours. A process that stays up without listening on anything (`tsc --watch`) is
+reported as `running`, which is the honest third answer.
+
+Each service gets a transcript card and a `svc N` chip in the status bar. Two
+tools read and stop them:
+
+- `bash_output({ service, since? })` — the log tail and the current status.
+  `since` is the cursor the previous call returned, so a watcher can be read
+  incrementally. The tail is a bounded in-memory ring of 200 rows; there are no
+  log files on disk.
+- `bash_kill({ service })` — stop one, or `"all"`.
+
+**Services do not survive the CLI.** Quitting, `Ctrl+C`, `SIGTERM` and a crash
+all reap the tree on a best-effort basis; there is no daemon, no PID file and no
+reattach across launches. A `SIGKILL` of aragon itself is unrecoverable by
+construction, and if a stop cannot confirm the process is gone it says
+`may have left a detached child` rather than claiming success.
+
+From your side there are two keys and one command: `Ctrl+C` stops every live
+service (and does *not* arm exit), `/bg` lists them, and `/bg logs s1` prints a
+tail without going through the model.
+
+### Turning it off
+
+```jsonc
+// ~/.aragon/config.json
+{ "bash": { "background": false } }
+```
+
+`ARAGON_BASH_BACKGROUND=0` does the same for one run;
+`ARAGON_BASH_AUTO_BACKGROUND=0` keeps the tools but stops the classifier firing
+on a command that did not ask. With `background: false` the build behaves exactly
+as it did before this feature existed — no `background` parameter, no extra
+tools, no prompt block, no chip.
+
+Two things are **not** governed by that switch, because they are fixes rather
+than features. `bash` now always settles: it returns when the process exits
+rather than when its output stream closes, so a command that detaches a
+grandchild can no longer leave the turn pending forever, and it is handed a
+closed stdin so a command that prompts fails instead of blocking on a read
+nobody will answer. And `Esc` twice always force-stops, whatever the flag says.
+
 ## Team subagents
 
 The agent can hand parts of a job to short-lived **subagents** that run in
@@ -1647,6 +1739,7 @@ env / `.env` → CLI flags**.
 | `planModeDefault` | `false` | Start every session in plan mode. `--no-plan` still overrides it for a single run. |
 | `planModeMaxAskRounds` | `4` | `ask_user` rounds allowed per user message, clamped to `[1, 10]`. The counter resets on your next message; steering does **not** reset it. |
 | `planModeHumanTimeoutMs` | `1800000` | Ceiling on a single question / plan wait, clamped to `[60000, 7200000]`. Thirty minutes is far outside "went to get coffee", but a ceiling has to exist so an unattended terminal cannot wedge a CI job forever. |
+| `paste` | `true` | Recognise pasted text before Ink's key parser sees it: line breaks become buffer newlines instead of fifteen separate messages, control bytes are stripped instead of overwriting the row they land on, and a paste above 6 lines or 400 characters collapses to a one-line placeholder that expands when you send. `false` treats pasted bytes as keystrokes, which is what 0.6.2 did. |
 | `historyEnabled` | `true` | Record submitted prompts to `prompt-history.jsonl` for `↑` recall. Setting it to `false` stops new writes; it does not delete what is already stored (that is `aragon history clear --yes`) and does not stop reading. See [Prompt history](#prompt-history). |
 | `team.enabled` | `true` | Master switch for team subagents. `false` means the `task` tool is never registered — `/team on` in such a session saves the setting for next launch and says so, rather than advertising a tool that is not there. |
 | `team.maxSubagents` | `5` | Subagents per dispatch, clamped to `[1, 10]`. The 10 is the hard ceiling and is enforced twice — on the config value and again on what the model asks for — so hand-editing this file cannot raise it. |

package/dist/agent/controller.d.ts

@@ -15,6 +15,8 @@ import type { ToolPermission } from '../exec/permission.js';
 import { type ToolOutputListener } from '../tools/tool-output-store.js';
 import type { FilePatch } from '../tools/patch.js';
 import type { TeamEvent, TeamSnapshot } from '../team/types.js';
+import { ProcSupervisor } from '../proc/supervisor.js';
+import type { ProcEventListener, ServiceSnapshot } from '../proc/types.js';
 import { type FastStatus } from '../fast/wiring.js';
 import type { FastEventListener } from '../fast/types.js';
 import type { CompactionEventListener, CompactionSnapshot } from '../compaction/types.js';
@@ -176,6 +178,33 @@ export declare class AgentController {
     private readonly outputListeners;
     private readonly fast;
     private readonly compaction;
+    private readonly procs;
+    /**
+     * The host's notice channel, kept so `prompt()`'s totality has somewhere to
+     * report to (I-8). Every other consumer reads `deps.notify` through a closure
+     * built in the constructor; this one is called from a method, which is why it
+     * needs a field.
+     */
+    private readonly notifyHostFn;
+    /** Whether the SERVICE half is on: tools, prompt block, `background` param. */
+    private readonly bashBackgroundRegistered;
+    /** Release the exit reaper. Called by `dispose()`. */
+    private readonly releaseSignalHook;
+    /**
+     * Bumped by `forceStop()`; captured by `App` when it subscribes to a run.
+     *
+     * THE VIEW AND THE ENGINE DELIBERATELY DISAGREE AFTER A FORCE-STOP (D-10 /
+     * I-7). Rung two dispatches `runEnd` locally so the composer is usable
+     * immediately, but the engine keeps unwinding and keeps EMITTING -
+     * `turn_start`, `tool_call_start`, `turn_end`, `agent_end` - and
+     * `runStart`/`turnStart` would set `status: 'running'` again, bouncing the
+     * view straight back out of the `idle` the user was just given and appending
+     * entries to a transcript they believe is finished. `App` drops every event
+     * whose generation is stale, which is the same shape as `abortRequested`
+     * above and exists for the same reason: the loop legitimately emits after an
+     * abort lands.
+     */
+    private runGen;
     /**
      * Set SYNCHRONOUSLY by `abort()` before `agent.abort()` (§3.5.4a guard 1).
      * Cleared at the next `agent_start`.
@@ -234,7 +263,97 @@ export declare class AgentController {
      * never rejects, so callers must not treat resolution as success.
      */
     prompt(text: string): Promise<void>;
+    /**
+     * Wait for the engine to unwind, bounded.
+     *
+     * BOUNDED BECAUSE THE UNBOUNDED CASE IS THE ONE THIS FEATURE IS ABOUT: a tool
+     * that never settles is exactly why rung two exists, and `Agent.waitForIdle()`
+     * alone would hang here for as long as it hangs there. The budget is the two
+     * graces a wedged `bash` can legitimately spend, plus the executor's own.
+     */
+    private waitForEngineIdle;
+    /** The pre-round body of `prompt`, unchanged apart from being private. */
+    private startPrompt;
     abort(): void;
+    /**
+     * Rung two of the Esc ladder: stop the AGENT, whatever it is blocked on
+     * (§3.6 / G3).
+     *
+     * FOUR STEPS, AND THE FOURTH IS AN ABSENCE.
+     *
+     *   1. `abort()` - everything it does today, unchanged.
+     *   2. `killForeground('force')` - hard-kill every tracked foreground `bash`
+     *      child. THIS is what actually unblocks a wedged `await tool.execute`;
+     *      an abort signal a tool ignores is advisory, and rung two exists for
+     *      precisely the tools that ignore it.
+     *   3. `runGen += 1` - so `App` can drop the events the engine will keep
+     *      emitting while it unwinds (I-7). Without it the view bounces straight
+     *      back out of the `idle` the user was just given.
+     *   4. IT DOES NOT TOUCH BACKGROUND SERVICES. `Esc` interrupts the AGENT;
+     *      `Ctrl+C` stops the SERVICES. That asymmetry is the user's own two
+     *      sentences and it is exactly the kind of thing a later reader will
+     *      "fix" by making this kill everything - which would mean a user who
+     *      pressed Esc twice to stop a runaway turn also lost the dev server they
+     *      had been working against for an hour. It is invariant I-4.
+     *
+     * UNCONDITIONAL ON `bash.background` (P1-6 / D-9). The supervisor is always
+     * constructed; with services off its foreground registry is all there is, and
+     * that is the half this method uses.
+     */
+    forceStop(): void;
+    /**
+     * The current run generation (I-7).
+     *
+     * `App` captures it when it subscribes to a run and drops every engine event
+     * whose generation is stale. Same shape as the `abortRequested` guard the fast
+     * reviewer already uses, and for the same reason: the loop legitimately emits
+     * after an abort lands.
+     */
+    get runGeneration(): number;
+    /** Whether `bash_output` / `bash_kill` are in `this.tools`. Fixed at construction. */
+    isBackgroundRegistered(): boolean;
+    /**
+     * Subscribe to the CLI-local `ProcEvent` stream.
+     *
+     * Returns a live unsubscribe even when services are off, because the
+     * supervisor exists either way - the contract `subscribeTeam` /
+     * `subscribeTodos` / `subscribeFast` / `subscribeToolOutput` already set. With
+     * services off nothing is ever emitted, so an unconditional subscription in
+     * `App` costs one `Set` entry.
+     */
+    subscribeProc(listener: ProcEventListener): () => void;
+    getServiceSnapshot(id: string): ServiceSnapshot | undefined;
+    listServices(): ServiceSnapshot[];
+    /** `starting | ready | running`. Drives the status chip and the Ctrl+C rung. */
+    liveServiceCount(): number;
+    readServiceLog(id: string, since?: number): ReturnType<ProcSupervisor['read']>;
+    /**
+     * Stop one service, or every service when `id` is `'all'`.
+     *
+     * The GRACEFUL ladder (`SIGTERM` -> `SIGKILL` after `stopGraceMs`), because
+     * this path has a live event loop to run it on. `reapServicesSync` is the
+     * other one, and it is the only one an exit path may use.
+     */
+    stopService(id: string): Promise<ServiceSnapshot[]>;
+    /**
+     * Rung one of `Ctrl+C`: stop every live service (§3.6 / G4).
+     *
+     * `force: true` means `reapSync()` SEMANTICS - immediate `SIGKILL`, no
+     * `stopGraceMs` - and is what `doExit` uses, because `doExit` awaits nothing
+     * and must not start (§3.6 step 3). The graceful ladder belongs to `Ctrl+C`,
+     * `bash_kill` and `/bg stop`.
+     */
+    stopAllServices(opts?: {
+        force?: boolean;
+    }): Promise<ServiceSnapshot[]>;
+    /**
+     * The synchronous reaper (I-9).
+     *
+     * Exposed so `doExit` can call it without awaiting anything. It is also what
+     * the signal hook registered in the constructor calls, and it is idempotent -
+     * which it has to be, since a normal quit reaches it twice.
+     */
+    reapServicesSync(): void;
     steer(text: string): void;
     followUp(text: string): void;
     isRunning(): boolean;