@aragon-agent/cli 0.6.25 → 0.6.27

package/dist/commands/session-command.js

@@ -0,0 +1,109 @@
+/**
+ * `/session` - report this session's identity, and the two things a user does
+ * with it (tui-session-id-resume §3.11 / D-13 / D-14).
+ *
+ * ASCII ONLY - `src/commands/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THE BODY LIVES HERE AND THE REGISTRATION STAYS IN `builtins.ts`: the same
+ * reason `/clear` and `/compact` do. `builtins.ts` is already past the
+ * 1000-line guideline, and this command is a report, not a one-liner.
+ *
+ * COPYING THE RESUME COMMAND IS THE POINT, NOT A CONVENIENCE (D-14). Typing 6
+ * characters off a status bar is the only step of this whole feature that can
+ * fail for a human, and `/session copy` removes it: one keystroke, the exact
+ * command in the clipboard, no transcription.
+ */
+import { sessionPathFor } from '../session/store.js';
+/**
+ * The one path an id maps to.
+ *
+ * THROUGH `sessionPathFor` RATHER THAN A SECOND `join` (§2.2): that function is
+ * the single choke point where an id becomes a file name, and a report that
+ * built its own path would be the first thing to disagree with the writer about
+ * where a session lives.
+ */
+export function sessionFilePath(id) {
+    return sessionPathFor(id);
+}
+/**
+ * Run `/session`, `/session copy` or `/session pin`.
+ *
+ * ONE NOTICE FOR THE WHOLE REPORT (§3.11 / R-20): six separate notices would put
+ * six cards in the transcript and replay them as six fragments on exit. The
+ * `file` line is NOT truncated even when it overflows: it is a path the user
+ * needs to be able to copy, and it is in the same family as `/save`'s
+ * `Saved session to <path>`.
+ */
+export function runSessionCommand(ctx) {
+    const port = ctx.session;
+    if (!port) {
+        // HONEST RATHER THAN SILENT: a build without the feature should say so,
+        // because "nothing happened" reads as a bug.
+        ctx.notify('warn', 'This session has no id (session recording is off for this build).');
+        return;
+    }
+    const verb = ctx.args.trim().toLowerCase();
+    const identity = port.identity();
+    if (!identity) {
+        ctx.notify('warn', 'This session has no id (session recording is off for this build).');
+        return;
+    }
+    if (verb === 'copy') {
+        copyCommand(ctx, identity);
+        return;
+    }
+    if (verb === 'pin') {
+        pinSession(ctx, port, identity);
+        return;
+    }
+    if (verb !== '') {
+        // Rejected rather than ignored: a command that silently discards an argument
+        // is a surface that lies about what it understood.
+        ctx.notify('warn', `Unknown argument "${ctx.args.trim()}" - use /session [copy|pin].`);
+        return;
+    }
+    report(ctx, identity);
+}
+/** The six-line report. Pure read: no checkpoint, no toast, no dispatch. */
+function report(ctx, identity) {
+    const resume = `aragon --resume ${identity.id}`;
+    const lines = [
+        `id        ${identity.id}`,
+        `file      ${sessionFilePath(identity.id)}`,
+        identity.parentId
+            ? `branch    ${identity.parentId} (this session does not write to it)`
+            : 'branch    (none - this session started here)',
+        `pinned    ${identity.pinned ? 'yes' : 'no'}`,
+        `resume    ${resume}`,
+        'save as   aragon --save <new-id>',
+    ];
+    ctx.notify('info', lines.join('\n'));
+}
+/** `/session copy` - the exact command, through the SAME door `/copy` uses. */
+function copyCommand(ctx, identity) {
+    const text = `aragon --resume ${identity.id}`;
+    if (!ctx.requestCopy) {
+        ctx.notify('warn', 'Clipboard coordinator unavailable.');
+        return;
+    }
+    void ctx.requestCopy({ text, lines: 1 }).then((result) => {
+        if (result.status === 'confirmed' || result.status === 'sent') {
+            ctx.toast('info', `Copied ${text}`);
+            return;
+        }
+        // A failed or refused copy must not look like a successful one: the command
+        // is short enough to read off the report above, so naming the failure is
+        // enough to recover.
+        ctx.notify('warn', result.status === 'busy' ? 'Clipboard is busy - try /session copy again.' :
+            `Copy failed: ${result.reason}`);
+    });
+}
+/** `/session pin` - write once and stop `sessions prune` from ever touching it. */
+function pinSession(ctx, port, identity) {
+    const result = port.checkpoint({ pin: true });
+    if (!result.ok) {
+        ctx.notify('warn', `Could not pin this session: ${result.message}`);
+        return;
+    }
+    ctx.toast('info', `Session ${identity.id} pinned: aragon sessions prune will not delete it.`);
+}

package/dist/config/load.d.ts

@@ -228,6 +228,21 @@ export interface CliFlags {
     compaction?: boolean;
     /** `--compaction-threshold <0..1|N%>` — session override for `threshold`. */
     compactionThreshold?: string;
+    /**
+     * `--resume <id|path>` - continue a saved session under a NEW id
+     * (tui-session-id-resume 4).
+     *
+     * A FLAG FIELD AND NOT A CONFIG KEY (D-19). There is no persisted "always
+     * resume this session", and no switch that shows an id without writing it:
+     * that state - an id a user can copy and cannot use - is worse than having no
+     * id at all.
+     *
+     * Carried through `toFlags` like every other flag; a field that reaches only
+     * `CliFlags` is inert with no compile error and no runtime error.
+     */
+    resumeSession?: string;
+    /** `--save <id>` - name THIS run's persistent session and pin it. */
+    saveSessionAs?: string;
 }
 /**
  * Resolve the effective config by merging all layers, then derive the runtime

package/dist/exec/index.js

@@ -418,7 +418,16 @@ function planSession(options, cwd, err) {
     if (options.sessionId !== undefined) {
         // THE UPSERT. A wrapper that mints its own id must not have to ask whether
         // this is the first turn; that is the whole reason this form exists.
-        return { id: options.sessionId, saved: readSessionFile(sessionPathFor(options.sessionId)), saving, cwd };
+        //
+        // AND IT IS A RESUME FORM, so the same write-back rule applies (tui-session-
+        // id-resume D-20 / I-3). When a file already exists under that id,
+        // `resumedSessionId` decides which id this run writes - and for a TUI
+        // checkpoint that answer is a NEW uuid. Without this line the wrapper-friendly
+        // upsert was the one remaining way to reach a TUI checkpoint and replace it,
+        // which is silent, unrecoverable loss of the user's live conversation.
+        const path = sessionPathFor(options.sessionId);
+        const saved = readSessionFile(path);
+        return { id: saved ? resumedSessionId(path, saved) : options.sessionId, saved, saving, cwd };
     }
     return { id: randomUUID(), saved: null, saving, cwd };
 }

package/dist/logging/logger.d.ts

@@ -23,7 +23,7 @@
 import type { LogConfig } from '../config/schema.js';
 import { type LogLevelName } from './levels.js';
 /** Closed set, not free text: a typo'd scope is a record nobody can filter on. */
-export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'fast' | 'history' | 'update' | 'compaction';
+export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'fast' | 'history' | 'update' | 'compaction' | 'session' | 'branch';
 export interface LogRecord {
     ts: string;
     lv: LogLevelName;

package/dist/proc/terminal-plan.d.ts

@@ -0,0 +1,173 @@
+/**
+ * What a new terminal window looks like from the outside (tui-branch-terminal-shortcut
+ * 3.7).
+ *
+ * ASCII ONLY - `src/proc/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * PURE, AND THAT IS THE POINT. Three platforms, at least ten terminal emulators,
+ * four exec-argument conventions and Windows' three layers of parsing (we -> `cmd`
+ * -> `PowerShell`) all collapse into "what should we spawn, with which argv". A
+ * command body that called `spawn('cmd', ['/c','start', ...])` inline would bury
+ * the only testable part of this feature - the command line itself - inside
+ * untestable IO. `proc/readiness.ts` and `proc/classify.ts` set the same precedent
+ * inside this directory.
+ *
+ * WHY SESSION CODE MAY DEPEND ON THIS MODULE: it imports nothing from
+ * `node:child_process`, reads no configuration and creates no process. The single
+ * place a process is created stays in `session/branch-launch.ts`, so `proc/` keeps
+ * meaning "processes" and `session/` keeps meaning "sessions".
+ *
+ * EVERY RUNG CARRIES ITS OWN WORKING DIRECTORY (D-16 / D-23 / I-9). This is the
+ * one thing a reviewer will assume is free and is not: `spawn({ cwd })` decides the
+ * cwd of the process WE start, and for `wt -w 0 nt` (a new tab in an already
+ * running Windows Terminal) or `osascript` (a new Terminal.app window) that
+ * process merely forwards the request - the window opens in the terminal's own
+ * default directory. So `wt` passes `-d`, and both script rungs start with
+ * `cd <cwd> &&`. `--resume` does not restore a cwd, so a window that opens in the
+ * wrong place can never be corrected from inside the branch.
+ */
+/** The three ladders, collapsed from `NodeJS.Platform` (win32 / darwin / everything else). */
+export type TerminalPlatform = 'win32' | 'darwin' | 'posix';
+export interface ShellInvocation {
+    /** Executable: an absolute path or a name resolved through PATH. */
+    path: string;
+    /** Which command syntax the aragon command has to be encoded for. */
+    kind: 'powershell' | 'posix';
+}
+export interface TerminalLaunchPlan {
+    /** The program we spawn. */
+    file: string;
+    args: string[];
+    /** True only for the `cmd` rung, whose command line `cmd.exe` must see verbatim. */
+    windowsVerbatimArguments: boolean;
+    /** Ladder name, for the log and for the success toast's debug detail. */
+    rung: string;
+}
+export type TerminalPlanResult = {
+    ok: true;
+    plans: TerminalLaunchPlan[];
+    shell: ShellInvocation;
+    manual: string;
+} | {
+    ok: false;
+    reason: 'no-launcher';
+    shell: ShellInvocation;
+    manual: string;
+};
+export interface TerminalPlanInput {
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+    pathDirs: readonly string[];
+    isExecutable?: (name: string) => boolean;
+    shell: ShellInvocation;
+    /** The aragon command's argv pieces (`session/branch-invocation.ts`'s product). */
+    command: readonly string[];
+    /** New window title, ASCII, already truncated to the cell budget. */
+    title: string;
+    cwd: string;
+    /**
+     * `renderManualCommand(command, platform)`'s product: two lines on win32
+     * (`PowerShell:` / `cmd.exe   :`), one line everywhere else.
+     */
+    manual: string;
+}
+/** The env var that overrides the shell the new window runs (D-7). */
+export declare const ARAGON_BRANCH_SHELL_ENV = "ARAGON_BRANCH_SHELL";
+/**
+ * Build the ladder for this platform, most-preferred rung first.
+ *
+ * The return value is a LIST because the failures this feature can actually hit
+ * are synchronous argument rejections (ENOENT on `wt.exe`, no X display), and a
+ * list lets `branch-launch.ts` walk down it without knowing anything about
+ * terminals. Rung COUNT is bounded by the caller (`BRANCH_TERMINAL_LIMITS.maxRungs`),
+ * so there is exactly one place that number lives.
+ */
+export declare function planTerminalLaunch(input: TerminalPlanInput): TerminalPlanResult;
+/**
+ * The PowerShell statement that runs the aragon command (D-1).
+ *
+ * THE LEADING `&` IS NOT DECORATION. In command position PowerShell reads a quoted
+ * string as an EXPRESSION, so `'C:\Program Files\nodejs\node.exe' <script>` is a
+ * parse error - "unexpected token ..." at column 36 - and the child is never
+ * created, while the parent still believes the window opened (K-1: `wt`/`start`
+ * forward and exit). That is exactly the report this branch exists to fix.
+ * `&` is the call operator: it takes the following word as a command name whatever
+ * its shape, and it does not change name resolution (`& 'npm.cmd'` still finds
+ * `npm` through PATH/PATHEXT, appendix B-8).
+ *
+ * `posixScript` MUST NOT be given the same treatment: in sh `&` means run in the
+ * background, so the window would reach the trailing `exec <shell> -i` immediately
+ * and the branch would start behind a prompt that looks idle (I-3 / K-1).
+ */
+export declare function powerShellScript(parts: readonly string[]): string;
+/** Bare words stay bare; everything else becomes a single-quoted literal. */
+export declare function powerShellQuote(value: string): string;
+/**
+ * `-EncodedCommand` takes base64 of UTF-16LE, which needs no shell quoting at all.
+ *
+ * The alphabet is `A-Za-z0-9+/=` - no spaces, no quotes, no `cmd` metacharacters -
+ * so the blob survives all three of Windows' parsers as an ordinary word. This is
+ * the same trick `ui/win-vt-force.ts` uses, for the same reason: encode the fragile
+ * thing into a form nothing can argue with, at construction time. Our command line
+ * necessarily contains spaced paths (`C:\Program Files\nodejs\node.exe`), so the
+ * fragile thing is not hypothetical.
+ */
+export declare function encodePowerShellCommand(script: string): string;
+/** POSIX single-quote escaping: `'` becomes `'\''`. */
+export declare function posixQuote(value: string): string;
+export declare function posixScript(parts: readonly string[]): string;
+/** AppleScript string literals only need `\` and `"` escaped. */
+export declare function escapeAppleScriptText(value: string): string;
+/**
+ * Win32 argv quoting for the `cmd` rung's title and shell path: quote when it
+ * contains whitespace, otherwise leave it alone.
+ *
+ * THE INPUT DOMAIN EXCLUDES `"` BY CONSTRUCTION (R-17/T-48): Windows paths cannot
+ * contain it, and the title is `aragon <id>` where an id is `[A-Za-z0-9._-]`. If a
+ * future source can contain a quote, this must switch to `cmd`'s rule (`""`) and
+ * not to the POSIX `\"` written here - the two are not interchangeable.
+ */
+export declare function quoteWin32Arg(value: string): string;
+/** PATH entries for `name` probing: both spellings on Windows, `:` on POSIX. */
+export declare function pathDirsOf(env: Record<string, string | undefined>, platform: NodeJS.Platform): string[];
+/**
+ * The default probe: is this a file we could execute?
+ *
+ * An absolute or separator-bearing value is stat'd directly (that is the
+ * `ARAGON_BRANCH_SHELL=/usr/local/bin/fish` case); a bare name is looked up in the
+ * PATH directories, trying `name` and - on Windows - `name + '.exe'`, because a
+ * user typing `pwsh` and a probe looking for `pwsh.exe` are the same request.
+ *
+ * EVERY EXCEPTION RETURNS FALSE: one failed stat means "this candidate is not
+ * here", not "the feature is broken", and a missing terminal must degrade to the
+ * manual command rather than throw out of a key handler.
+ */
+export declare function defaultIsExecutable(platform: NodeJS.Platform, pathDirs?: readonly string[]): (name: string) => boolean;
+/**
+ * Which shell the new window runs (D-7), first match wins.
+ *
+ * The requirement says "PowerShell / bash", and both platforms have two answers
+ * worth distinguishing: PowerShell 7 (`pwsh.exe`) when the user installed it,
+ * Windows PowerShell 5.1 otherwise; `$SHELL` when the user's login shell is not
+ * bash, then bash, then `/bin/sh` as the one path that exists everywhere.
+ * `ARAGON_BRANCH_SHELL` is the escape hatch - an ENV VALUE, not a config key
+ * (D-17): a "Ctrl+L opens no terminal" switch would create the one state this
+ * feature must never have.
+ */
+export declare function resolveShell(input: {
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+    isExecutable?: (name: string) => boolean;
+    pathDirs: readonly string[];
+}): ShellInvocation;
+/**
+ * Fit a window title into `maxCells` columns (R-7 / T-47).
+ *
+ * THE TITLE IS THE ONLY THING THIS TOUCHES. An id can be 64 characters long, so
+ * `aragon <id>` exceeds the 60-cell budget by construction for the longest ids -
+ * and truncating the id anywhere else (the command line, `--resume`) would produce
+ * a branch that cannot find its own parent. Code points, not bytes: the title is
+ * ASCII today, and a future non-ASCII title must not be cut through a surrogate
+ * pair.
+ */
+export declare function truncateTitle(title: string, maxCells: number): string;