@aragon-agent/cli 0.6.24 → 0.6.26

package/dist/session/branch-launch.js

@@ -0,0 +1,248 @@
+/**
+ * The `/branch` port: flush, plan, spawn (tui-branch-terminal-shortcut 3.6).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * ORDER IS CORRECTNESS (I-1). The child process's first act is to read the parent
+ * session file, and the parent's checkpoint is debounced and fingerprint-
+ * short-circuited (`checkpoint.ts`). Spawning before a successful FORCED write
+ * means the branch can read the previous turn - or, after `aragon sessions rm
+ * <id>`, no file at all - and the user sees "the branch opened but lost the last
+ * ten turns". That is a data defect, not a UX one, so `checkpoint({force:true})`
+ * returns `ok` before any terminal is created.
+ *
+ * THE CHILD IS NOT A SERVICE (D-5 / I-3): `detached: true`, `stdio: 'ignore'`,
+ * `unref()`, and deliberately no `ProcSupervisor` registration. Registering it
+ * would make the parent's exit kill a session running in another window.
+ *
+ * EVERY FAILURE CARRIES A PASTEABLE COMMAND (I-4). "Could not open a terminal" is
+ * a dead end; `aragon --resume a4k2m9` is 22 characters the user can always use.
+ */
+import { spawn } from 'node:child_process';
+import { getLogger } from '../logging/logger.js';
+import { defaultIsExecutable, pathDirsOf, planTerminalLaunch, resolveShell, truncateTitle, } from '../proc/terminal-plan.js';
+import { BRANCH_COPY } from '../commands/branch-command.js';
+import { buildResumeInvocation, joinCommandLine, resolveAragonCommand, validateBranchId, } from './branch-invocation.js';
+import { BRANCH_TERMINAL_LIMITS } from './limits.js';
+/**
+ * Build the port. The only mutable state is this closure's four values, none of
+ * which outlives the process (no persistence, 6 in the spec).
+ */
+export function createBranchLauncher(deps) {
+    const now = deps.now ?? Date.now;
+    const logger = deps.logger ?? getLogger().child('branch');
+    const spawnFn = deps.spawn ?? spawn;
+    const pathDirs = pathDirsOf(deps.env, deps.platform);
+    const isExecutable = deps.isExecutable ?? defaultIsExecutable(deps.platform, pathDirs);
+    /** Last SUCCESSFUL open (D-10). Failures never move it, so a retry is never blocked. */
+    let lastOpenedAt = null;
+    let inFlight = false;
+    /** Resolution is cached for the process (R-13 / K-14); a FAILED probe is not. */
+    let cachedAragon = null;
+    let cachedShell = null;
+    /**
+     * Resolve WHAT the new window runs, and the command line built from it.
+     *
+     * The resolution is cached for the process (R-13 / K-14). It costs no
+     * filesystem probe - the three rules are env, `argv[1]` and a literal - so the
+     * cache is about identity, not speed: the value that opened the first window is
+     * the value the log keeps reporting.
+     */
+    function planFor(id) {
+        cachedAragon ??= resolveAragonCommand({
+            argv: deps.argv,
+            execPath: deps.execPath,
+            env: deps.env,
+        });
+        return {
+            aragon: cachedAragon,
+            invocation: buildResumeInvocation({ id, aragon: cachedAragon }),
+        };
+    }
+    function shellFor() {
+        cachedShell ??= resolveShell({
+            platform: deps.platform,
+            env: deps.env,
+            isExecutable,
+            pathDirs,
+        });
+        return cachedShell;
+    }
+    function cooldown(command, retryInMs) {
+        return {
+            ok: false,
+            reason: 'cooldown',
+            message: BRANCH_COPY.cooldown(retryInMs),
+            command,
+            retryInMs,
+        };
+    }
+    function failure(reason, message, command) {
+        return { ok: false, reason, message, command };
+    }
+    /** Steps 1-2: the in-flight gate, then the cooldown window (D-10). */
+    function gated(command) {
+        const windowMs = BRANCH_TERMINAL_LIMITS.cooldownMs;
+        if (inFlight)
+            return cooldown(command, windowMs);
+        if (lastOpenedAt === null)
+            return null;
+        const waited = now() - lastOpenedAt;
+        if (waited >= windowMs)
+            return null;
+        return cooldown(command, Math.max(1, windowMs - waited));
+    }
+    async function openOnce(request) {
+        const { aragon, invocation } = planFor(request.id);
+        const command = invocation.command;
+        // 4.5 BEFORE ANY SPAWN (R-7 / T-46): a command line that `cmd` or AppleScript
+        // would truncate is worse than no command line, because the window opens and
+        // then fails in a way this process cannot see.
+        if (command.length > BRANCH_TERMINAL_LIMITS.maxCommandLineCells) {
+            // A COMPLETE SENTENCE WITH THE FALLBACK INSIDE IT (I-4 / appendix A): the
+            // over-long case is the one failure where the user most needs a command to
+            // paste, so it may not report the bare reason "command line too long" - that
+            // is an internal code, not an answer, and it would leave a dead end.
+            return failure('spawn-failed', BRANCH_COPY.spawnFailed('command line too long', command), command);
+        }
+        // D-9's second gate: an id is about to enter a command line.
+        const invalid = validateBranchId(request.id);
+        if (invalid !== null)
+            return failure('spawn-failed', invalid, command);
+        // Step 6: flush FIRST, spawn only on `ok` (I-1). `force` skips the fingerprint
+        // short circuit and nothing else (D-15 / I-7).
+        const flushed = deps.checkpoint({ force: true });
+        if (!flushed.ok) {
+            const reason = flushed.message ?? 'write-failed';
+            // R-19: `no-identity` is a timing answer ("this frame has no id yet"), not a
+            // disk problem, so it must not be printed as "could not checkpoint
+            // (no-identity)" - that reads like corruption. It gets `/session`'s sentence.
+            const message = reason === 'no-identity' ? BRANCH_COPY.noIdentity : BRANCH_COPY.checkpointFailed(reason);
+            return failure('checkpoint-failed', message, command);
+        }
+        const shell = shellFor();
+        // Step 7: the TITLE is what gets truncated, never the id in the command line (T-47).
+        const title = truncateTitle(`aragon ${request.id}`, BRANCH_TERMINAL_LIMITS.titleMaxCells);
+        const planned = planTerminalLaunch({
+            platform: deps.platform,
+            env: deps.env,
+            pathDirs,
+            isExecutable,
+            shell,
+            command: invocation.parts,
+            title,
+            cwd: request.cwd,
+            manual: joinCommandLine(invocation.parts),
+        });
+        if (!planned.ok) {
+            // Not cached: the next press must be allowed to find a terminal that appeared.
+            return failure('no-launcher', BRANCH_COPY.noLauncher(planned.manual), command);
+        }
+        // Step 8: walk the ladder, bounded by maxRungs (T-33).
+        const rungs = planned.plans.slice(0, BRANCH_TERMINAL_LIMITS.maxRungs);
+        let lastError = null;
+        for (const plan of rungs) {
+            const outcome = await trySpawn(request, plan);
+            if (outcome === 'ok') {
+                lastOpenedAt = now();
+                // `origin` is why the record exists (D-18): "I pressed Ctrl+L and nothing
+                // happened" is answered by WHICH aragon the child ran (`aragon` from PATH,
+                // `node <script>`, or the env override) and through which rung, which no
+                // other record in the log can tell you.
+                logger.info('opened', {
+                    id: request.id,
+                    rung: plan.rung,
+                    shell: planned.shell.path,
+                    aragon: aragon.kind,
+                    origin: aragon.origin,
+                });
+                return { ok: true, command, shell: planned.shell.path, rung: plan.rung };
+            }
+            logger.warn('rung_failed', { rung: plan.rung, message: outcome.message });
+            lastError = outcome;
+        }
+        // Step 9: every rung failed. `wt`'s own semantic failures land here too only if
+        // the error event fired; a forwarded-but-rejected `wt` invocation does not (K-1).
+        return failure('spawn-failed', BRANCH_COPY.spawnFailed(lastError?.message ?? 'no rung available', command), command);
+    }
+    /**
+     * One rung, with EXACTLY ONE `'error'` LISTENER THAT IS NEVER REMOVED (R-3 / I-10).
+     *
+     * `once('error')` is what the first draft used and it is wrong: after the probe
+     * settles on `'spawn'` (or on the timeout) that handler is still removed on
+     * first use, so a LATE error has no listener - an unhandled `'error'` on a
+     * ChildProcess throws at the process top level and takes the parent TUI with it.
+     * A permanent listener with a `settled` flag gives the probe the first error and
+     * the user the rest.
+     */
+    async function trySpawn(request, plan) {
+        const child = spawnFn(plan.file, plan.args, {
+            cwd: request.cwd,
+            detached: true,
+            // I-3: the child's streams must never join the parent's, or Ink's frame
+            // differ treats another process's bytes as an outside writer.
+            stdio: 'ignore',
+            // A new window has to be visible; hiding it would defeat the whole key.
+            windowsHide: false,
+            // The FULL environment, inherited on purpose (K-7): `ARAGON_HOME` is how the
+            // child finds the same sessions directory, and `ARAGON_*` is user
+            // configuration (D-7). `ARAGON_LOG_FILE` appends per record with `pid` + `sid`.
+            env: deps.env,
+            ...(plan.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
+        });
+        child.unref();
+        return probeSpawn(child, plan, request);
+    }
+    /** Wait for `'spawn'` | `'error'` | the timeout, then keep listening for late errors. */
+    function probeSpawn(child, plan, request) {
+        return new Promise((resolve) => {
+            let settled = false;
+            let timer = null;
+            const finish = (value) => {
+                if (settled) {
+                    if (value === 'ok')
+                        return;
+                    // LATE error: report it, never re-settle, never remove the listener.
+                    const message = value.message || String(value);
+                    logger.warn('late_error', { rung: plan.rung, message });
+                    request.onLateError?.(BRANCH_COPY.lateError(message));
+                    return;
+                }
+                settled = true;
+                if (timer !== null)
+                    clearTimeout(timer);
+                resolve(value);
+            };
+            timer = setTimeout(() => {
+                // A timeout counts as SUCCESS (K-8): `'spawn'` and `'error'` both missing
+                // almost always means the process was created and the event was merely
+                // delayed behind the scheduler. Reporting a failure here produces the worse
+                // error - "window is open, UI says it is not".
+                logger.debug('probe_timeout', { rung: plan.rung });
+                finish('ok');
+            }, BRANCH_TERMINAL_LIMITS.spawnProbeMs);
+            timer.unref?.();
+            // `spawn` fires at most once, so `once` is honest here.
+            child.once('spawn', () => finish('ok'));
+            // PERMANENT. Installed before any await so no error can slip past it.
+            child.on('error', (error) => finish(error));
+        });
+    }
+    return {
+        async open(request) {
+            const blocked = gated(planFor(request.id).invocation.command);
+            if (blocked !== null)
+                return blocked;
+            inFlight = true;
+            try {
+                return await openOnce(request);
+            }
+            finally {
+                // `inFlight` always clears, including on a synchronous throw from `spawn`
+                // (an invalid `cwd`), which then bubbles to `executeSlashInput`'s try/catch
+                // and becomes one honest `Command failed: ...` line (D-2).
+                inFlight = false;
+            }
+        },
+    };
+}

package/dist/session/checkpoint.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Session checkpoint writer (tui-session-id-resume §3.4 / D-2 / D-3 / D-4 /
+ * D-21 / D-22 / D-23).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THIS MODULE EXISTS AT ALL: a TUI conversation lives in memory
+ * (`agent.state.messages`). Another terminal can only continue it if the process
+ * has put it on disk, and the only serializer that exists (`saveSession`) is
+ * written for explicit exports. So this is the one owner of three properties an
+ * export never needed:
+ *
+ *   1. THE FILE ON DISK IS ALWAYS SENDABLE (D-3 / I-4). A checkpoint taken
+ *      mid-tool would leave an assistant `tool_call` with no `tool_result`, and
+ *      the next request of the branch that resumes it is an HTTP 400 - the very
+ *      first thing `--resume` is for.
+ *   2. THE REPLACEMENT IS ATOMIC (D-4). This is the repository's first "a writer
+ *      and a reader coexist" session file: the parent TUI writes while another
+ *      terminal reads. A truncated read says "corrupt session", and one false
+ *      report is enough for a user to stop trusting the feature.
+ *   3. NOTHING LIVE SURVIVES INTO THE FILE (D-22 / I-11). A `running` tool card
+ *      that never settles keeps `ToolCard` spinning and keeps `Transcript`'s
+ *      MONOTONIC settled boundary from ever moving past it, so every frame
+ *      re-renders the tail. The settlement happens on the WRITE COPY, not on the
+ *      load path, because `live-session.test.ts` pins the `/save` decision that
+ *      a reloaded card keeps its status - and `/save` is an explicit export made
+ *      with the user watching, while a checkpoint is not.
+ *
+ * NOTHING HERE MAY INTERRUPT A CONVERSATION (I-8): every filesystem failure is
+ * swallowed, logged, and reported as a value.
+ */
+import { type Message, type ModelRef } from '@aragon-agent/core';
+import type { Entry, UsageTotal } from '../agent/reducer.js';
+import type { TodoItem } from '../todo/types.js';
+import type { CompactionIdentity } from '../compaction/memory-identity.js';
+import { type SessionLockHandle } from './store.js';
+/**
+ * What the view side can tell the writer: the identity, the transcript, and this
+ * process's spend.
+ *
+ * A MINIMAL PORT RATHER THAN A REFERENCE TO `ViewState`. The writer must not know
+ * what a reducer is, and `usageTotal` is here because `meta.usage` has no other
+ * source (R-5): it is the cumulative value this process has spent, it is NEVER
+ * read back (D-10), and it starts again from zero whenever the id changes.
+ */
+export interface LiveSessionView {
+    id: string;
+    entries: Entry[];
+    /** This process's spend; the only source of `meta.usage` (R-5). Never read back. */
+    usageTotal: UsageTotal;
+}
+export interface CheckpointDeps {
+    /** `cli.tsx` injects `readSessionView`; `undefined` means "no identity here". */
+    readView(): LiveSessionView | undefined;
+    /** The controller's two live pieces; injected so the writer is unit-testable. */
+    readHistory(): {
+        messages: Message[];
+        compactionIdentity?: CompactionIdentity;
+    };
+    readTodos(): TodoItem[];
+    readModel(): ModelRef;
+    /** `meta.cwd`; read at every write because `/cwd` can change it. */
+    readCwd(): string;
+    /** `meta.cli`. */
+    version: string;
+    /**
+     * `meta.branchOf`. Read at write time rather than captured, because the App
+     * can rotate the identity after `/resume` (D-15) and the lineage must follow.
+     */
+    readParentId?(): string | undefined;
+    /** `--save <id>` starts the session pinned; `/session pin` sets it later. */
+    startPinned?: boolean;
+    now?(): number;
+    /** The target path; injected so tests point at a temporary directory. */
+    pathFor?(id: string): string;
+    /**
+     * The per-process claim on this id (S-7). Injected so a unit test can answer
+     * `null` instead of creating a lock in the real sessions directory.
+     */
+    lockFor?(id: string): SessionLockHandle | null;
+}
+export interface CheckpointResultOk {
+    ok: true;
+    path: string;
+    bytes: number;
+    repaired: number;
+    settled: number;
+}
+export type CheckpointResult = CheckpointResultOk | {
+    ok: false;
+    reason: 'no-identity' | 'not-sendable' | 'write-failed';
+    message: string;
+};
+/**
+ * `writeNow`'s switches.
+ *
+ * `force` skips the fingerprint short circuit and NOTHING ELSE (D-15 / I-7): an
+ * unsendable history is still refused, the settle-and-repair pass still runs, and
+ * the file it produces is still `loadSession()`-readable. It exists because
+ * `Ctrl+L` spawns a process that reads this file immediately, and a short-
+ * circuited write returns `bytes: 0` with the file's content being whatever the
+ * last successful write left there - right after `aragon sessions rm <id>`, that
+ * is "no file at all", and the branch would greet the user with
+ * `No session "<id>"` (tui-branch-terminal-shortcut D-3).
+ */
+export interface CheckpointOptions {
+    /** `/session pin` and `--save <id>`. */
+    pin?: boolean;
+    /** Ignore the fingerprint short circuit (D-15). */
+    force?: boolean;
+}
+/**
+ * Repair every `tool_call` that never received its `tool_result` (D-3).
+ *
+ * ON A COPY, AND THAT IS THE POINT (I-2). The live history belongs to the
+ * engine; a host that edited it would change what the next request sends. Each
+ * dangling call gets an `isError` result carrying one fixed sentence, and the
+ * caller re-runs `validateHistory` afterwards: a repair that is still not
+ * sendable means the file must not be written.
+ */
+export declare function closeDanglingToolCalls(messages: readonly Message[]): {
+    messages: Message[];
+    repaired: number;
+};
+/**
+ * Settle every `running` tool card on a COPY (D-22 / I-11).
+ *
+ * `error` rather than `done`: the command did not finish, and a card that said
+ * otherwise would claim a result nobody saw. The live tail is cleared for the
+ * same reason `stripLiveToolOutput` clears it - it describes a process that died
+ * with the session - and `preview` names WHY, so a resumed card is not a silent
+ * lie. `pending` is left alone: `ToolCard` draws no spinner for it and
+ * `Transcript.nowSecFor` never re-clocks it, so it settles by itself.
+ */
+export declare function settleRunningToolCards(entries: readonly Entry[]): {
+    entries: Entry[];
+    settled: number;
+};
+/** What may reach the disk: nothing at all, or a history the engine can resend. */
+export declare function isSendable(messages: readonly Message[]): boolean;
+/**
+ * The checkpoint writer.
+ *
+ * ONE TIMER (I-10). Several `agent_end` events in a row - a todo follow-through
+ * restarts the run without the user typing - are merged into one write, and the
+ * timer is `unref`ed so a pending write can never hold the process open. Every
+ * exit path calls `flushSync`, which is idempotent so the three of them
+ * (`waitUntilExit().then()`, the signal hook and `process.on('exit')`) can
+ * coexist without writing three times.
+ */
+export declare class SessionCheckpointWriter {
+    private readonly deps;
+    private readonly pathFor;
+    private lastFingerprint;
+    private lastWriteAt;
+    private createdAt;
+    private pinned;
+    private failureStreak;
+    private pending;
+    private unsubscribe;
+    private exited;
+    /**
+     * Whether the LAST WRITE FILE still says `live: true`.
+     *
+     * The fingerprint deliberately does not include the reason for the write, so
+     * without this the exit flush would short-circuit as "nothing changed" and the
+     * file would keep `live: true` forever - which is the flag `sessions prune`
+     * reads as "a writer is still here" (T-10's sibling, and the reason
+     * `flushSync` must be able to write a file whose CONTENT is unchanged but whose
+     * METADATA is not).
+     */
+    private lastWroteLive;
+    private lastResult;
+    /**
+     * THIS PROCESS'S CLAIM ON THE FILE IT WRITES (S-7).
+     *
+     * Without it, `meta.live` is a flag nobody can verify: `sessions prune` reads
+     * the `.lock` payload to decide whether the writer is still alive, and the TUI
+     * never took one - so `prune --origin tui --yes` deleted the checkpoint of a
+     * session that was running at that moment. The lock is the same one `exec`
+     * uses to keep two writers off one file; a killed process leaves a dead pid
+     * behind and the existing staleness probe collects it.
+     */
+    private lock;
+    private lockedId;
+    constructor(deps: CheckpointDeps);
+    /**
+     * Write once now: after mount, so the id on screen is resumable immediately.
+     *
+     * THE `no-identity` ANSWER IS A TIMING ANSWER, NOT A PERMANENT ONE. `render()`
+     * returns before `App` has run its first effects, so the session slot can still
+     * be empty when this is called - and "the id on screen is not resumable until
+     * the first turn" is exactly the failure D-2 exists to prevent (a zero-turn
+     * session must already be a session). One deferred retry through the SAME
+     * single timer (I-10) turns that window into the write; if the view was already
+     * published, the first call succeeded and no timer is armed at all.
+     */
+    start(): CheckpointResult;
+    /** Subscribe to `agent_end`. The writer does not own the controller's lifetime. */
+    attach(subscribe: (fn: () => void) => () => void): void;
+    /** Write now, optionally pinning (`/session pin`) or forcing past the short circuit. */
+    writeNow(opts?: CheckpointOptions): CheckpointResult;
+    /**
+     * The exit-path write. Never throws, and after the first call it is a no-op
+     * (I-10): all three exit paths run on a normal quit.
+     */
+    flushSync(reason: 'exit' | 'signal'): CheckpointResult;
+    dispose(): void;
+    private onAgentEnd;
+    /**
+     * Coalesce into one timer. `debounceMs` is the window; `minWriteIntervalMs`
+     * keeps two consecutive run boundaries - which arrive closer together than a
+     * human can type - from landing two full session writes back to back.
+     */
+    private schedule;
+    private clearPending;
+    private now;
+    /**
+     * The full write, in the one order that keeps the file honest: read, repair,
+     * gate, settle, write to a temporary file, replace.
+     *
+     * `force` is ONE switch with ONE effect (D-15 / I-7): it skips the fingerprint
+     * short circuit below. Everything after it - the dangling-call repair, the
+     * sendable gate, the settle pass, the atomic replace - runs unchanged, because a
+     * forced write still has to produce a file `loadSession()` can read back.
+     */
+    private write;
+    /** Serialize to `<id>.json.tmp-<uuid>` and rename over the real file (D-4). */
+    private persist;
+    /**
+     * `meta`, field by field (§6.1). Two of these are easy to get subtly wrong:
+     * `createdAt` is frozen at the first write (re-reading it every time would
+     * make the field a second `updatedAt`), and `turns` counts assistant messages
+     * IN THE FILE - a quantity a reader can verify, unlike "what this cost".
+     */
+    private buildMeta;
+    /**
+     * Take, or move, this process's lock on the id being written (S-7).
+     *
+     * BEST EFFORT, AND NEVER FATAL: a checkpoint must not fail because someone
+     * else holds the lock - the write is atomic and the file is this id's own, so
+     * the worst case is a `live` flag that `prune` declines to trust.
+     */
+    private holdLock;
+    private releaseLock;
+    /** A failed write is a log line and a return value, never an exception (I-8). */
+    private fail;
+    /**
+     * A cheap content fingerprint: identity, message count, last message shape,
+     * entry count, last entry id, todo count and the pin flag.
+     *
+     * SHORT AND STRUCTURAL ON PURPOSE. Hashing the whole conversation would cost
+     * as much as writing it (K-1), and the question this answers is only "did
+     * anything settle since the last write".
+     */
+    private fingerprint;
+}