@aragon-agent/cli 0.6.2 → 0.6.4

package/dist/commands/builtins.js

@@ -3,20 +3,20 @@
  * /help /model /settings /thinking /max-tokens /tools /clear /reset /cwd /save
  * /resume /copy /exit (/quit), plus the /team, /fast and /todo subsystems.
  */
-import { spawn } from 'node:child_process';
 import { existsSync, statSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
-import process from 'node:process';
 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';
 import { loadConfig } from '../config/load.js';
 import { loadSession, resolveSessionPath, saveSession } from '../session/persist.js';
 import { getLogger } from '../logging/logger.js';
+import { copyText } from '../ui/clipboard.js';
 import { perfCommand } from './perf.js';
+import { runCompactCommand } from '../compaction/command.js';
 /**
  * `/fast status` — THE GUARANTEED REPORTING SURFACE for the tier (§4.4 / R-8).
  *
@@ -801,8 +801,21 @@ const COMMANDS = [
             ctx.notify('warn', `Unknown argument "${verb}" - use /retry [show|on|off|max <n>].`);
         },
     },
+    {
+        // REGISTRATION ONLY. The body lives in `compaction/command.ts` because this
+        // file is already past the 1000-line guideline and `/compact` has six forms
+        // plus the longest status report in the package (C-16 / P1-12).
+        name: 'compact',
+        description: 'Context compaction: status | on | off | threshold <n> | keep <n> | <instructions>',
+        run: (ctx) => runCompactCommand(ctx),
+    },
     {
         name: 'expand',
+        // DELIBERATELY LEFT TOOL-ONLY, and the asymmetry with Ctrl+O is a decision
+        // rather than an oversight (§6.3). Its description says "a recent tool card",
+        // it takes an N-from-last index over tool cards specifically, and widening it
+        // would change what `/expand 3` means for every existing user. Ctrl+O is the
+        // general expansion surface — that is where `'compaction'` was added.
         description: 'Expand / collapse a recent tool card (default: last)',
         run: (ctx) => {
             const toolEntries = ctx.state.entries.filter((e) => e.kind === 'tool');
@@ -942,8 +955,60 @@ const COMMANDS = [
                 ctx.notify('warn', 'No assistant message to copy.');
                 return;
             }
-            const ok = copyToClipboard(last.text);
-            ctx.toast(ok ? 'success' : 'warn', ok ? 'Copied to clipboard.' : 'Clipboard not available.');
+            // ROUTED THROUGH `ui/clipboard.ts` (§4.4.5). The duplicate spawn helper this
+            // command used to own is gone, and the command gained SSH support on the
+            // way: OSC 52 reaches the clipboard of the machine the USER is sitting at,
+            // which the local `pbcopy` never could.
+            //
+            // `ctx.writeForeign` and not `stdout.write` — see the field's comment.
+            const via = copyText(last.text, ctx.writeForeign);
+            if (via === 'none') {
+                ctx.toast('warn', 'Clipboard not available.');
+                return;
+            }
+            // NAMES THE MECHANISM RATHER THAN CLAIMING SUCCESS: neither path is
+            // detectable, and tmux without `set -g set-clipboard on` swallows OSC 52
+            // silently (R-7).
+            ctx.toast('success', via === 'osc52' ? 'Sent to the terminal clipboard.' : 'Sent to the system clipboard.');
+        },
+    },
+    {
+        name: 'mouse',
+        description: 'Release the mouse to the terminal, or take it back',
+        run: (ctx) => {
+            const port = ctx.mouse;
+            if (!port) {
+                // Inline mode, `--no-mouse`, a non-TTY, or a console that cannot deliver
+                // reports. Saying so beats pretending to toggle something that is not on.
+                ctx.notify('info', 'The mouse is not captured in this session, so there is nothing to release.');
+                return;
+            }
+            const arg = ctx.args.trim().toLowerCase();
+            if (arg === 'off') {
+                port.setCapture(false);
+                // NAMING THE COST IS THE HONEST THING TO DO, and it is one clause. The
+                // wheel goes INERT rather than back to scrolling: alternate scroll is
+                // saved and disabled alongside the capture, because otherwise every notch
+                // becomes a burst of arrow keys that `PromptInput` reads as prompt-history
+                // recall (I-10 / P1-1).
+                ctx.toast('info', 'Mouse released to the terminal - the wheel will not scroll. /mouse on gives it back.');
+                return;
+            }
+            if (arg === 'on') {
+                port.setCapture(true);
+                ctx.toast('info', 'Mouse captured - the wheel scrolls the transcript again.');
+                return;
+            }
+            const captured = port.captured();
+            const lines = [
+                `Mouse capture: ${captured ? 'on' : 'off'}`,
+                `  drag-select  ${port.selectEnabled() ? 'on' : 'off (mouseSelect is false)'}`,
+                '  /mouse off   hand the mouse to your terminal for this session',
+                '  /mouse on    take it back',
+                '  --no-mouse   never capture it (also ARAGON_MOUSE=0)',
+                '  aragon config set mouseSelect false   keep the wheel, drop drag-select',
+            ];
+            ctx.notify('info', lines.join('\n'));
         },
     },
     {
@@ -983,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'],
@@ -990,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);
@@ -1006,22 +1162,7 @@ export const BUILTIN_COMMAND_NAMES = COMMANDS.flatMap((c) => [
     c.name,
     ...(c.aliases ?? []),
 ]).sort();
-/** Best-effort clipboard copy via the platform's clipboard CLI. */
-function copyToClipboard(text) {
-    const cmd = process.platform === 'win32'
-        ? { file: 'clip', args: [] }
-        : process.platform === 'darwin'
-            ? { file: 'pbcopy', args: [] }
-            : { file: 'xclip', args: ['-selection', 'clipboard'] };
-    try {
-        const child = spawn(cmd.file, cmd.args, { stdio: ['pipe', 'ignore', 'ignore'] });
-        child.on('error', () => {
-            /* swallow — clipboard is best-effort */
-        });
-        child.stdin?.end(text);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+// The `copyToClipboard` helper that used to live here moved into
+// `ui/clipboard.ts` (tui-selection-and-scroll-follow §4.4.5), unchanged, so that
+// `/copy` and the drag-select release share ONE clipboard path instead of two
+// that can drift.

package/dist/commands/registry.d.ts

@@ -87,6 +87,33 @@ export interface CommandContext {
         effective: AgentMode;
         pending: AgentMode | null;
     };
+    /**
+     * Mouse capture, for `/mouse` (tui-selection-and-scroll-follow §6.2 / G3).
+     *
+     * OPTIONAL, and legitimately absent: inline mode, `--no-mouse`, a non-TTY, a
+     * Windows console that cannot deliver reports, and every test that builds this
+     * context by literal. `/mouse` has to have something honest to say when it is
+     * missing, which is the same reason `update` above it is optional.
+     */
+    mouse?: MouseCommandPort;
+    /**
+     * The foreign-write door, for `/copy`'s OSC 52 half (§4.4.5).
+     *
+     * NOT `process.stdout.write`. In full-screen mode stdout is a `Proxy` in front
+     * of the frame differ, and an unrecognised chunk there is counted as a foreign
+     * write and prints a diagnostic at the user the first time they copy anything
+     * (P1-6). Absent in inline mode and with `--no-diff-render`, where the real
+     * stream is handed over directly.
+     */
+    writeForeign?: (text: string) => void;
+}
+/** What `/mouse` can see and do. Read at command time, never captured. */
+export interface MouseCommandPort {
+    /** Whether the CLI is holding the mouse right now. */
+    captured(): boolean;
+    /** Whether drag-select is on for this session (`mouseSelect`). */
+    selectEnabled(): boolean;
+    setCapture(on: boolean): void;
 }
 export interface SlashCommand {
     name: string;

package/dist/compaction/archive.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The compaction archive - a compaction stops being irreversible
+ * (context-auto-compaction-hardening §3.5 / W4).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`), and that INCLUDES the field names below and every
+ * string `/compact history` and `/compact show` print.
+ *
+ * WHAT THIS IS FOR. Round 1's non-goal was stated plainly: "the dropped messages
+ * are gone". Combined with R-1 - "the summary is wrong or lossy, and the agent
+ * proceeds confidently on a false record... this is the feature's defining risk
+ * and it cannot be eliminated" - the product was asking the user to accept an
+ * unverifiable, unrecoverable transformation of their session. That is the wrong
+ * default for a tool that runs unattended. This does not add undo (§12: restoring
+ * an over-full history re-creates the condition that triggered compaction). It
+ * adds FIDELITY ON DISK, so R-1 becomes something a human can check.
+ *
+ * NO IMPORTS FROM `ui/`. This module writes files and formats two report blocks;
+ * it has no terminal, no theme and no glyphs.
+ */
+import type { Message } from '@aragon-agent/core';
+import type { CompactionMode, CompactionUiTrigger } from './types.js';
+/** Bumped only when the SHAPE changes; the reader rejects anything else. */
+export declare const ARCHIVE_FORMAT_VERSION = 1;
+export interface CompactionArchive {
+    version: number;
+    /** `COMPACTION_BLOCK_VERSION` at write time, so a bad summary ties to a revision. */
+    blockVersion: string;
+    createdAt: number;
+    /**
+     * Which process wrote this.
+     *
+     * STORED INSIDE THE DOCUMENT as well as in the name, so a file renamed or
+     * copied by hand is still self-describing and the reader never has to parse a
+     * filename for meaning it cannot verify.
+     */
+    runId: string;
+    /** 1-based within this run. */
+    index: number;
+    trigger: CompactionUiTrigger;
+    mode: CompactionMode;
+    model: string;
+    generation: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    messagesBefore: number;
+    messagesAfter: number;
+    /**
+     * THE NUMBER. Deliberately not called `droppedMessages`: that name already
+     * means a COUNT in three typed places (`CompactionPlan`, `finish`'s `applied`
+     * argument, and `AgentEvent.compaction_end`), and this is the document someone
+     * reads while diagnosing a bad summary (RV-3).
+     */
+    droppedCount: number;
+    summary?: string;
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    /** True when `dropped` was shortened to fit `archiveMaxBytes`. */
+    clipped: boolean;
+    /** THE ARRAY. Verbatim, oldest first. */
+    dropped: Message[];
+}
+/** One row of `/compact history`, already resolved from disk. */
+export interface ArchiveListing {
+    entries: ArchiveEntry[];
+    /** Archives in the directory belonging to OTHER runs. Counted, never listed. */
+    otherRuns: number;
+    dir: string;
+}
+export interface ArchiveEntry {
+    path: string;
+    fileName: string;
+    index: number;
+    createdAt: number;
+    trigger: CompactionUiTrigger;
+    mode: CompactionMode;
+    model: string;
+    tokensBefore: number;
+    tokensAfter: number;
+    droppedCount: number;
+    summary?: string;
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    clipped: boolean;
+}
+export interface ArchiveWriteInput {
+    runId: string;
+    index: number;
+    trigger: CompactionUiTrigger;
+    mode: CompactionMode;
+    model: string;
+    generation: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    messagesBefore: number;
+    messagesAfter: number;
+    summary?: string;
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    dropped: Message[];
+    /** Injected by the tests; production passes nothing. */
+    dir?: string;
+    now?: number;
+}
+/**
+ * `compaction-<YYYY-MM-DD>-<hhmmss>-<runId>-<index>.json`.
+ *
+ * THE RUN ID IS IN THE NAME BECAUSE THE DIRECTORY IS SHARED (RV-6).
+ * `file-sink.ts` makes log retention best-effort precisely because "on Windows
+ * another `aragon` process may hold a handle on a file we would like to remove",
+ * so concurrent CLI processes are an acknowledged in-tree condition rather than
+ * an edge case. Without this segment `/compact history` presents another
+ * session's compactions as this one's and `/compact show 2` is ambiguous the
+ * moment two runs both reach their second compaction.
+ */
+export declare function archiveFileName(runId: string, index: number, at: Date): string;
+/**
+ * Mint this process's archive key.
+ *
+ * NOT `SessionMeta.id`: that exists only once a session has been SAVED, and the
+ * unattended long run this feature serves is exactly the one nobody saved. Short,
+ * filename-safe, and only ever compared for equality - a grouping key, not an
+ * identity.
+ */
+export declare function mintRunId(pid?: number, now?: number): string;
+/**
+ * Serialize, clipping the dropped bodies from the OLDEST end if the document
+ * exceeds `archiveMaxBytes`.
+ *
+ * THE METADATA AND THE SUMMARY ARE NEVER CLIPPED. A truncated archive that still
+ * says what happened, when, and with which model beats no archive at all - and
+ * the oldest dropped messages are the least likely to be the ones a human came
+ * looking for.
+ */
+export declare function serializeArchive(doc: CompactionArchive, maxBytes: number): string;
+/**
+ * Write one archive, then prune. Returns the path written, or `null`.
+ *
+ * NEVER THROWS. The caller runs inside an event handler on the compaction path;
+ * a filesystem is not allowed to affect whether a session survives its context
+ * window. Every failure is a `warn` with the path and nothing else - a toast for
+ * a best-effort audit file trains users to ignore toasts.
+ */
+export declare function writeArchive(input: ArchiveWriteInput): string | null;
+/**
+ * Two-tier retention, and the ORDER MATTERS (§3.5.2 / RV-6).
+ *
+ *  1. WITHIN THIS RUN: keep the newest `archiveMaxFiles` files carrying THIS
+ *     `runId`. This is the bound that protects the user from their own long
+ *     session, and it can never touch another run.
+ *  2. ACROSS RUNS: delete files older than `archiveMaxAgeMs`, regardless of
+ *     `runId`, so an abandoned run's archives do not accumulate forever. AGE, not
+ *     count - a count-based global prune is exactly the rule that deletes a live
+ *     session's work while it is still running.
+ *
+ * Best-effort throughout, in the `enforceRetention` shape: every `rmSync` in its
+ * own `try`, a locked file skipped rather than fatal.
+ */
+export declare function pruneArchives(runId: string, dir: string, now: number): void;
+/**
+ * This run's archives, newest first, plus a COUNT of everyone else's.
+ *
+ * THE COUNT IS REPORTED RATHER THAN THE FILES, because the alternative is a user
+ * concluding their own compactions went missing when the directory holds a
+ * neighbour's.
+ */
+export declare function listArchives(runId: string, dirOverride?: string): ArchiveListing;
+/** One archive by its `#n`, or `null`. `n` is the index within THIS run. */
+export declare function findArchive(runId: string, index: number, dirOverride?: string): ArchiveEntry | null;