@aragon-agent/cli 0.6.3 → 0.6.4

package/dist/cli.js

@@ -44,7 +44,7 @@ import { decideRenderMode } from './ui/layout/frame.js';
 import { createFrameDiffer } from './ui/frame-differ.js';
 import { wrapStdoutForFrames } from './ui/stdout-frame-writer.js';
 import { setFrameStatsProvider } from './commands/perf.js';
-import { tryCreateMouseFilter } from './input/stdin-mouse-filter.js';
+import { tryCreateStdinFilter } from './input/stdin-filter.js';
 import { enterAltScreen, writeExitTranscript } from './ui/screen.js';
 import { supportsWindowsVtInput } from './ui/win-vt-input.js';
 import { forceWindowsVtInput } from './ui/win-vt-force.js';
@@ -113,6 +113,11 @@ function toFlags(opts) {
         // on `CliFlags`, AND a line here; `config.test.ts` is the regression pin that
         // exists because `--no-mouse` shipped inert once already.
         mouseSelect: opts.mouseSelect,
+        // Site three of three for `--paste` / `--no-paste` -- TEN features, one
+        // trap. A flag needs the `.option()` declaration below, a field on
+        // `CliFlags`, AND a line here; `config.test.ts` is the regression pin that
+        // exists because `--no-mouse` shipped inert once already.
+        paste: opts.paste,
         skills: opts.skills,
         skill: opts.skill,
         skillsYes: opts.skillsYes,
@@ -416,7 +421,7 @@ function runInteractive(flags, extras = {}) {
     // before it reaches this process, so `\x1b[?1000h` is a pure no-op and the
     // filter has nothing to filter. Gating `wantMouse` — rather than the three
     // things downstream of it — is what keeps the three in agreement: the
-    // `?1000h` write (`enterAltScreen(..., { mouse: filter !== null })`), the
+    // `?1000h` write (`enterAltScreen(..., { mouse: mouseOn })`), the
     // filter itself, and the `mouseSource` prop that decides whether the user is
     // advised about a mode that is not running. Wiring any of them separately
     // re-opens the gap where the app claims a capability it does not have.
@@ -434,10 +439,36 @@ function runInteractive(flags, extras = {}) {
         !!process.stdout.isTTY &&
         !!process.stdin.isTTY &&
         vtInputSupported;
-    const mouseFilter = wantMouse
-        ? tryCreateMouseFilter(process.stdin, (reason) => logger.warn('cli', 'mouse_filter_failed', { reason }))
+    // --- Paste handling (tui-paste-handling section 5.1.1 / D-13 / D-17). ----
+    //
+    // THE GATE IS WIDER THAN THE MOUSE'S, AND `paste` DEFAULTS TO TRUE. Paste
+    // needs no `vtInputSupported` and no full-screen: Tier 2 is a heuristic on
+    // chunk shape and needs no terminal cooperation at all, which is exactly why
+    // it exists for the consoles that never deliver `\x1b[200~` (R-11).
+    //
+    // WHAT THIS WIDENING BREAKS IF IT IS NOT PAIRED WITH `mouseOn` BELOW (P0-1).
+    // `filter !== null` used to be the answer to FIVE questions, only one of which
+    // is really about the stream. With paste able to build a filter on its own,
+    // `aragon --no-mouse` would get a non-null handle and every one of those five
+    // would flip true: `?1000h`/`?1006h`/`?1002h` written, terminal selection taken
+    // away (the ONLY reason anyone passes `--no-mouse`), and a startup notice
+    // advising the user about a mode they just disabled.
+    const wantPaste = config.paste && !!process.stdin.isTTY;
+    const pasteBridge = { notify: null };
+    const filter = wantMouse || wantPaste
+        ? tryCreateStdinFilter(process.stdin, { mouse: wantMouse, paste: wantPaste }, (reason) => logger.warn('cli', 'stdin_filter_failed', { reason }), pasteBridge)
         : null;
-    const disposeMouse = () => mouseFilter?.dispose();
+    /**
+     * THE ONE EXPRESSION EVERY MOUSE SITE READS (I-11 / D-17).
+     *
+     * `filter !== null` now answers exactly one question -- "is a stream wrapped?"
+     * -- and the only site allowed to keep reading it is the `stdin` handed to
+     * `render()`.
+     */
+    const mouseOn = wantMouse && filter !== null;
+    /** Same discipline for DEC 2004: already decided here, never re-derived. */
+    const pasteOn = wantPaste && filter !== null;
+    const disposeStdinFilter = () => filter?.dispose();
     // --- Drag-select (tui-selection-and-scroll-follow §4.4). ------------------
     //
     // ONE EXPRESSION, READ BY FOUR THINGS, and that is the same discipline
@@ -446,7 +477,7 @@ function runInteractive(flags, extras = {}) {
     // disagree about whether drag-select is running. With it false the session is
     // byte-identical to a pre-feature build — no extra escape on the wire (AC-8),
     // no controller, no `decorate`, no mirror.
-    const wantSelect = mouseFilter !== null && config.mouseSelect;
+    const wantSelect = mouseOn && config.mouseSelect;
     const selectionBridge = {
         controller: null,
         onCopied: null,
@@ -526,11 +557,21 @@ function runInteractive(flags, extras = {}) {
         }));
     };
     if (mode === 'fullscreen') {
-        // `mouse` here means "a filter is installed", NOT "the user wants mouse
-        // support" — see `AltScreenOptions`. `screen.ts` must never derive it for
-        // itself, or a later refactor re-opens the gap I-8 closes. `motion` carries
-        // the same discipline for `?1002h`: already decided, never re-derived.
-        screen = enterAltScreen(process.stdout, { mouse: mouseFilter !== null, motion: wantSelect });
+        // `mouse` here means "a mouse-parsing filter is installed", NOT "the user
+        // wants mouse support" — see `AltScreenOptions`. `screen.ts` must never
+        // derive it for itself, or a later refactor re-opens the gap I-8 closes.
+        // `motion` carries the same discipline for `?1002h`, and `bracketedPaste`
+        // for `?2004h`: all three are already decided, none is re-derived.
+        //
+        // IT IS `mouseOn`, NOT `filter !== null` (P0-1). A `--no-mouse` session with
+        // paste at its default `true` still builds a filter, and passing the handle
+        // here would write `?1000h` at a user who disabled the mouse precisely to
+        // keep their terminal's own selection.
+        screen = enterAltScreen(process.stdout, {
+            mouse: mouseOn,
+            motion: wantSelect,
+            bracketedPaste: pasteOn && mode === 'fullscreen',
+        });
         const restore = () => screen?.restore();
         // Four idempotent restore paths (§4.4). The signal hook is NOT redundant:
         //   - `waitUntilExit().then()` is a microtask and may never be reached when
@@ -613,10 +654,10 @@ function runInteractive(flags, extras = {}) {
     // than inside `screen.ts`'s closure because `App` needs to READ it and the
     // handle's own flag is private (it has to be — `restore()` reads it, and
     // exposing a setter would be a second way to get the two out of step).
-    let mouseCaptured = mouseFilter !== null;
-    if (wantSelect && mouseFilter) {
+    let mouseCaptured = mouseOn;
+    if (wantSelect && filter) {
         selectionBridge.controller = createSelectionController({
-            source: mouseFilter.source,
+            source: filter.source,
             // The frame writer is absent under `--no-diff-render`, where there is no
             // cache to repaint from at all; the controller then falls back to asking
             // `App` for a React redraw on every drag flush, which is slower and
@@ -656,7 +697,7 @@ function runInteractive(flags, extras = {}) {
     const terminalBridge = mode === 'fullscreen' || writeForeign
         ? {
             mouseSelect: wantSelect,
-            ...(mouseFilter
+            ...(mouseOn
                 ? {
                     setMouseCapture: (on) => {
                         screen?.setMouseCapture(on);
@@ -682,13 +723,21 @@ function runInteractive(flags, extras = {}) {
         !!process.stdin.isTTY &&
         !process.env.CI &&
         config.update.mode !== 'off';
-    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay, mouseSource: mouseFilter?.source, 
+    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay, 
+        // `mouseOn`, NOT the handle (I-11). `App.tsx:186-188` documents this
+        // prop's contract as "absent under `--no-mouse`, inline, or non-TTY", and
+        // it feeds `enabled: !!mouseSource` on a wheel subscription that would
+        // otherwise be a channel no event can ever arrive on.
+        mouseSource: mouseOn && filter ? filter.source : undefined, 
         // Present ONLY when this console swallows `CSI Z` and mouse reports.
         // Passed in rather than probed inside `App` so that every test renders
         // the same tree on every machine — reading `process.versions.node` from
         // a component would make the notice appear or vanish according to which
         // Node the developer happened to have installed.
-        vtInputWarning: vtInputSupported ? undefined : { nodeVersion: process.versions.node }, updateBridge: updateEligible ? updateBridge : undefined, terminal: terminalBridge }), 
+        vtInputWarning: vtInputSupported ? undefined : { nodeVersion: process.versions.node }, updateBridge: updateEligible ? updateBridge : undefined, 
+        // Absent when nothing can refuse a paste, so a `--no-paste` tree is
+        // byte-identical to a build without this feature.
+        pasteBridge: pasteOn ? pasteBridge : undefined, terminal: terminalBridge }), 
     // Full-screen owns console.* itself (I-4): Ink's patchConsole writes
     // straight to stdout and permanently shifts the fixed frame's accounting.
     {
@@ -696,7 +745,7 @@ function runInteractive(flags, extras = {}) {
         patchConsole: mode === 'inline',
         // I-5: with mouse support off the REAL stdin is handed over unwrapped, so
         // every existing path is provably unchanged.
-        stdin: mouseFilter?.stdin ?? process.stdin,
+        stdin: filter?.stdin ?? process.stdin,
         // SPREAD, not `frameWriter?.stdout ?? process.stdout`. This call passed no
         // `stdout` at all before, and Ink defaults it to `process.stdout`; omitting
         // the key entirely when the writer is off keeps the options object the same
@@ -757,12 +806,12 @@ function runInteractive(flags, extras = {}) {
         .waitUntilExit()
         .then(() => {
         screen?.restore();
-        // BEFORE `disposeMouse()`, which clears the listener set it subscribed to,
+        // BEFORE `disposeStdinFilter()`, which clears the listener set it subscribed to,
         // and after `restore()` for the reason that call records: the terminal must
         // stop reporting first, and anything already in flight is still consumed by
         // a live filter.
         disposeSelection();
-        disposeMouse();
+        disposeStdinFilter();
         // BOTH BRANCHES, the same discipline `controller.dispose()` and
         // `updateService?.dispose()` already follow. It drops the `'resize'`
         // listener of I-8 and detaches the `/perf` provider so a later `/perf` in a
@@ -786,12 +835,12 @@ function runInteractive(flags, extras = {}) {
     })
         .catch(() => {
         screen?.restore();
-        // BEFORE `disposeMouse()`, which clears the listener set it subscribed to,
+        // BEFORE `disposeStdinFilter()`, which clears the listener set it subscribed to,
         // and after `restore()` for the reason that call records: the terminal must
         // stop reporting first, and anything already in flight is still consumed by
         // a live filter.
         disposeSelection();
-        disposeMouse();
+        disposeStdinFilter();
         disposeFrameWriter();
         controller.dispose();
         updateService?.dispose();
@@ -911,6 +960,10 @@ const CONFIG_SET_KEYS = new Set([
     // records: a key listed here but absent there writes nothing and still prints
     // `Set mouseSelect = false`.
     'mouseSelect',
+    // Listed here AND cased in the switch below, for the reason the note above
+    // `mouse` records: a key present here but absent there falls through every
+    // case, writes nothing, and still prints `Set paste = false`.
+    'paste',
     'scrollResumeMs',
     'historyEnabled',
     'planModeDefault',
@@ -1109,6 +1162,9 @@ function runConfigSet(key, value) {
         case 'mouseSelect':
             patch.mouseSelect = value === 'true' || value === '1';
             break;
+        case 'paste':
+            patch.paste = value === 'true' || value === '1';
+            break;
         // Clamped rather than rejected, for the same reason `planModeDefault` below
         // records: hardening only the READ path leaves a bad value on disk that
         // reverts to the default on every launch, which presents as "my setting
@@ -1381,6 +1437,12 @@ function buildProgram() {
         // `false` on every run that passes no flag at all.
         .option('--mouse-select', 'Drag with the mouse to select text; releasing copies it')
         .option('--no-mouse-select', 'Keep wheel scrolling, but leave drag-select off')
+        // Positive form FIRST, same tri-state reason as `--mouse-select` above:
+        // `paste` is persisted and defaults to `true`, so a lone `--no-paste` would
+        // make commander default `opts.paste` to `true` -- indistinguishable from
+        // silence, and silently overriding a stored `false` on every run.
+        .option('--paste', 'Collapse large pastes into a placeholder (the default)')
+        .option('--no-paste', 'Treat pasted bytes as keystrokes (pre-0.6.3 behavior)')
         // Declaring `--fullscreen` BEFORE `--no-fullscreen` keeps the default
         // `undefined` instead of `true`, which is what makes the tri-state work:
         // "no opinion" must stay distinguishable from "force it".

package/dist/commands/builtins.js

@@ -7,7 +7,7 @@ import { existsSync, statSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 import { resolveOutputTokens } from '@aragon-agent/core';
 import { clampThinkingLevel, clampTheme, isAdapterProvider, isThemeName, parseMaxTokensInput, ADAPTER_PROVIDERS, DEFAULT_MAX_TOKENS, HARD_MAX_RETRIES, LEGACY_DARK_THEME, THEME_NAMES, THINKING_LEVELS, } from '../config/schema.js';
-import { computeCost, formatCost, formatTokens } from '../agent/usage.js';
+import { computeCost, formatCost, formatDuration, formatTokens } from '../agent/usage.js';
 import { TODO_FOLLOW_LIMITS } from '../todo/limits.js';
 import { buildContinuationMessage } from '../todo/follow-through.js';
 import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
@@ -1048,6 +1048,95 @@ const COMMANDS = [
     // render layer, and threading `ui/render-cache.js` into this file would make
     // every other command's import graph pull the renderer in with it.
     perfCommand,
+    {
+        name: 'bg',
+        description: 'Background services: list | logs <id> [n] | stop <id|all> | status',
+        /**
+         * THE USER'S HANDLE ON WHAT THE AGENT LEFT RUNNING (§5.3).
+         *
+         * It is the LIVE view, and that is why it exists at all: the transcript
+         * records EVENTS about a service (D-11) — a card printed into `<Static>`
+         * cannot be rewritten — so "what is running right now" lives here, in the
+         * status chip, and in `bash_output`. Without this command a user whose
+         * server card scrolled away an hour ago has no way to name it.
+         */
+        run: async (ctx) => {
+            const arg = ctx.args.trim();
+            const [verb = 'list', value, count] = arg.split(/\s+/);
+            const controller = ctx.controller;
+            if (!controller.isBackgroundRegistered()) {
+                ctx.notify('info', 'Background services are off for this session (bash.background).');
+                return;
+            }
+            const services = controller.listServices();
+            if (verb === 'status') {
+                const live = controller.liveServiceCount();
+                ctx.notify('info', live === 0
+                    ? 'No background services running.'
+                    : `${live} background service${live === 1 ? '' : 's'} running.`);
+                return;
+            }
+            if (verb === 'logs') {
+                if (!value) {
+                    ctx.notify('warn', 'Usage: /bg logs <id> [n]');
+                    return;
+                }
+                const service = controller.getServiceSnapshot(value);
+                if (!service) {
+                    ctx.notify('warn', `No service "${value}".`);
+                    return;
+                }
+                const page = controller.readServiceLog(value);
+                const n = count ? Number.parseInt(count, 10) : DEFAULT_BG_LOG_ROWS;
+                const rows = page?.rows ?? [];
+                const take = Number.isFinite(n) && n > 0 ? n : DEFAULT_BG_LOG_ROWS;
+                const shown = rows.slice(-take);
+                ctx.notify('info', shown.length === 0
+                    ? `service ${service.id}: no output yet.`
+                    : `service ${service.id} (last ${shown.length} rows)\n${shown.join('\n')}`);
+                return;
+            }
+            if (verb === 'stop') {
+                if (!value) {
+                    ctx.notify('warn', 'Usage: /bg stop <id|all>');
+                    return;
+                }
+                // AWAITED, unlike `doExit`'s force path: a slash command runs on a live
+                // event loop, so the graceful SIGTERM -> SIGKILL ladder can run and a
+                // dev server gets its chance to release its port cleanly.
+                const stopped = await controller.stopService(value);
+                if (stopped.length === 0) {
+                    ctx.notify('info', 'Nothing to stop.');
+                    return;
+                }
+                const leaked = stopped.filter((svc) => svc.killIncomplete);
+                ctx.toast('success', `Stopped ${stopped.length} service${stopped.length === 1 ? '' : 's'}.`);
+                if (leaked.length > 0) {
+                    // AN HONEST WARNING BEATS A SILENT LEAK (R-2 / P2-6). `taskkill /t`
+                    // cannot reach a grandchild that re-parented itself, and saying so is
+                    // the difference between a puzzle and a `netstat` the user knows to run.
+                    ctx.notify('warn', `${leaked.map((svc) => svc.id).join(', ')} may have left a detached child - ` +
+                        'check with netstat/lsof if a port is still held.');
+                }
+                return;
+            }
+            if (verb !== 'list' && verb !== '') {
+                ctx.notify('warn', `Unknown argument "${verb}" - use /bg [list|logs|stop|status].`);
+                return;
+            }
+            if (services.length === 0) {
+                ctx.notify('info', 'No background services this session.');
+                return;
+            }
+            const now = Date.now();
+            const lines = services.map((svc) => {
+                const uptime = formatDuration((svc.endedAt ?? now) - svc.startedAt);
+                const where = svc.url ? `  ${svc.url}` : '';
+                return `${svc.id}  ${svc.status}  ${uptime}${where}  $ ${svc.command}`;
+            });
+            ctx.notify('info', `Background services:\n${lines.join('\n')}`);
+        },
+    },
     {
         name: 'exit',
         aliases: ['quit'],
@@ -1055,6 +1144,8 @@ const COMMANDS = [
         run: (ctx) => ctx.exit(),
     },
 ];
+/** Rows `/bg logs <id>` shows when the user names no count. */
+const DEFAULT_BG_LOG_ROWS = 40;
 export function registerBuiltinCommands(registry) {
     for (const command of COMMANDS)
         registry.register(command);

package/dist/compaction/child.js

@@ -85,6 +85,11 @@ export function createChildContextManager(req, deps) {
             }
             if (event.type !== 'compaction_end')
                 return;
+            // DEFENCE IN DEPTH SINCE quiet-noop D-8: a child compaction that declines
+            // before committing to work no longer emits this event at all, so this
+            // filter is now unreachable on that path. It is retained deliberately -
+            // it is this tree's own record that a no-op compaction is a non-event, and
+            // deleting it would make the child depend on that rule holding forever.
             if (!event.record.applied && event.record.mode === 'none')
                 return;
             req.onCompacted();

package/dist/compaction/command.js

@@ -66,9 +66,22 @@ export function formatCompactionStatus(ctx) {
     lines.push(`  Summarizer: ${snapshot.model || '(none)'}` +
         (config.useFastTier ? ' (fast tier preferred)' : ' (fast tier not used)'));
     lines.push(`  On summarize failure: ${config.onFailure}`);
+    // THE PARENTHETICAL IS BUILT FROM WHATEVER APPLIES, AND OMITTED WHEN NOTHING
+    // DOES (quiet-noop D-9). `declined` counts checkpoints that fired and chose to
+    // do nothing - the only human-readable trace of a decline once the transcript
+    // stopped carrying a card for one. It renders ONLY when non-zero: a counter
+    // that says `(0 checkpoints declined)` in every healthy session would have
+    // replaced one piece of noise with another.
+    const sessionNotes = [];
+    if (snapshot.generation > 0)
+        sessionNotes.push(`generation ${snapshot.generation}`);
+    const declined = snapshot.declined ?? 0;
+    if (declined > 0) {
+        sessionNotes.push(`${declined} ${declined === 1 ? 'checkpoint' : 'checkpoints'} declined`);
+    }
     lines.push(`  This session: ${snapshot.compactions} ` +
         `${snapshot.compactions === 1 ? 'compaction' : 'compactions'}` +
-        (snapshot.generation > 0 ? ` (generation ${snapshot.generation})` : '') +
+        (sessionNotes.length > 0 ? ` (${sessionNotes.join(', ')})` : '') +
         `, ${formatTokens(snapshot.tokensReclaimed)} tokens reclaimed`);
     const cost = snapshot.pricingUnknown
         ? `unknown (no price table for ${snapshot.model || 'the summarizer'})`

package/dist/compaction/compactor.d.ts

@@ -78,6 +78,15 @@ export declare class Compactor implements ContextManager {
     private compactionsThisRun;
     private lastCompactionTurn;
     private compactions;
+    /**
+     * How many `compact()` calls returned WITHOUT announcing (quiet-noop D-9).
+     *
+     * A SESSION TOTAL, LIKE `compactions`, and reset by neither `onRunStart()` nor
+     * `clearSelfDisable()`: `/compact on` overrides a guard, it does not rewrite
+     * history. `/compact status` is its only reader, and it is the whole of what
+     * keeps a decline reportable once the transcript stops carrying one.
+     */
+    private declined;
     private tokensReclaimed;
     private sessionUsage;
     private pricingUnknown;
@@ -175,6 +184,29 @@ export declare class Compactor implements ContextManager {
      */
     shouldCompact(probe: CompactionProbe): boolean;
     compact(ctx: CompactionContext): Promise<CompactionOutcome>;
+    /**
+     * Open the card (quiet-noop §3.2).
+     *
+     * THE ONLY EMITTER OF `compaction_start`, AND THE ONLY PLACE `this.compactions`
+     * ADVANCES. A compaction that never reaches an announce point is a DECLINE: it
+     * changed nothing, called nothing and spent nothing, and it is deliberately
+     * indistinguishable - on every human surface except `/compact status`'s
+     * `declined` count (D-9) - from a turn at which `shouldCompact` returned false.
+     * `finish` is the other half of that rule.
+     *
+     * IT RETURNS THE ANNOUNCEMENT RATHER THAN STORING IT (P1-1), and the caller
+     * keeps it in a LOCAL for the lifetime of one `runCompaction` call - the same
+     * slot `index` occupied before this change. An instance field would have needed
+     * a no-re-entrancy argument, and the obvious one is WRONG: guard 1 lives in
+     * `shouldCompact`, while the idle `/compact` path calls `compact()` straight
+     * through `wiring.compactNow()` without consulting it. What actually keeps two
+     * compactions apart is that `command.ts` QUEUES instead of calling `compactNow`
+     * while the loop runs - a property of a different file, which is exactly why
+     * this one must not depend on it. A clobbered field would leave `finish` unable
+     * to settle the card it opened, and a card that never settles pins
+     * `Transcript`'s monotonic boundary for the rest of the session.
+     */
+    private announce;
     private runCompaction;
     /** Tail relief against this session's window (hardening §3.3.3 / W2). */
     private relieveInPlace;
@@ -237,6 +269,8 @@ export declare class Compactor implements ContextManager {
     recordApplied(tokensBefore: number, tokensAfter: number): void;
     sessionTotals(): {
         compactions: number;
+        /** Checkpoints that declined before committing to any work (quiet-noop D-9). */
+        declined: number;
         tokensReclaimed: number;
         usage: TokenUsage;
         pricingUnknown: boolean;