@aragon-agent/cli 0.6.25 → 0.6.27

package/dist/session/identity.js

@@ -0,0 +1,148 @@
+/**
+ * Session identity: minting, branching, deriving, and reserving
+ * (tui-session-id-resume §3.5 / D-1 / D-5 / D-23).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * ONE AUTHORITY FOR "WHAT IS A SESSION CALLED". `store.ts` already owns the
+ * SYNTAX (`SESSION_ID_RE`) and the path (`sessionPathFor`); this module owns the
+ * generator and the branch rule, and it produces ids that pass that syntax by
+ * construction rather than by a second regex nobody re-checks.
+ *
+ * BRANCHING NEVER REUSES THE PARENT ID (D-5 / I-3). A `--resume` always derives
+ * a NEW id, so two processes can never take turns overwriting one file: the
+ * parent keeps writing its own id, the branch writes its own. That is the whole
+ * technical content of "a branch must not affect the session it branched from".
+ */
+import { closeSync, mkdirSync, openSync, unlinkSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { SESSION_ID_LIMITS } from './limits.js';
+import { basenameId, sessionPathFor } from './store.js';
+/**
+ * 31 characters: the ten digits and the lowercase alphabet MINUS `0 o 1 l i`.
+ *
+ * Those five are the pairs a human misreads when copying an id out of the
+ * bottom-right corner of a terminal, and copying an id by eye is the one
+ * irreducible failure mode this feature has (D-14 exists to remove it, and this
+ * alphabet removes most of the rest).
+ */
+export const SESSION_ID_ALPHABET = '23456789abcdefghjkmnpqrstuvwxyz';
+/** A generated id: 6 characters, optionally with the 4-character branch suffix. */
+const GENERATED_ID_RE = /^([a-z0-9]{6})(?:-([a-z0-9]{4}))?$/;
+/** One character from the alphabet. `random` is injected for deterministic tests. */
+function pick(random) {
+    // `Math.min` because a stubbed generator may legitimately return 1.
+    const index = Math.min(SESSION_ID_ALPHABET.length - 1, Math.floor(Math.abs(random()) * SESSION_ID_ALPHABET.length));
+    return SESSION_ID_ALPHABET[index];
+}
+function randomChars(count, random) {
+    let out = '';
+    for (let i = 0; i < count; i += 1)
+        out += pick(random);
+    return out;
+}
+/** A fresh 6-character id. Satisfies `SESSION_ID_RE` by construction (D-1). */
+export function createSessionId(random = Math.random) {
+    return randomChars(SESSION_ID_LIMITS.idLength, random);
+}
+/**
+ * The child id for `parentId`: 6-character root plus `-` plus 4 characters.
+ *
+ * THE ROOT DOES NOT GROW. `a4k2m9` and `a4k2m9-x7f2` both branch to
+ * `a4k2m9-<new>`, so a chain of branches keeps a name that still fits the
+ * status bar and still points at the conversation it came from.
+ */
+export function branchSessionId(parentId, random = Math.random) {
+    const root = GENERATED_ID_RE.exec(parentId)?.[1];
+    if (!root)
+        return createSessionId(random);
+    const suffix = randomChars(SESSION_ID_LIMITS.suffixLength, random);
+    return `${root}-${suffix}`;
+}
+/** Whether `id` is a shape this CLI mints (as opposed to a hand-chosen name). */
+export function isGeneratedSessionId(id) {
+    return GENERATED_ID_RE.test(id);
+}
+/**
+ * The next id for a session LOADED FROM `loadedPath`, or `null` when the file
+ * name is not a generated id.
+ *
+ * THE INPUT IS A PATH, NOT AN ID, AND THE PARENT'S IDENTITY COMES FROM THE FILE
+ * NAME (D-5 / R-8). `meta.id` lives inside the file, and a file is input - a
+ * hand-written `meta.id` must not be able to name where this process writes.
+ * `null` means "this was a `/save` export or an archive": the caller mints a
+ * fresh id and the new file has no `branchOf`.
+ */
+export function derivedChildId(loadedPath, random = Math.random) {
+    const base = basenameId(loadedPath);
+    return isGeneratedSessionId(base) ? branchSessionId(base, random) : null;
+}
+/**
+ * Claim `id` with an atomic `wx` create, writing a READABLE EMPTY SESSION into
+ * it (D-23 / R-3).
+ *
+ * `wx` IS THE MUTUAL EXCLUSION and stays that way: `existsSync` followed by a
+ * write has a window in which two processes both see "absent". What changed in
+ * v2 is the CONTENT. A 0-byte placeholder is unparseable, so `loadSession()`
+ * throws a raw `SyntaxError` on it, `listSessions` silently skips it, and
+ * `--save` refuses the name forever - a file the user can neither see nor
+ * resume. A legal empty `SavedSession` fixes all three at once: it loads, it
+ * lists, and `sessions rm` can delete it.
+ *
+ * NO `meta` IS WRITTEN, deliberately: "has `meta`" stays equivalent to "at least
+ * one checkpoint has been written", which is the predicate `sessions list` /
+ * `prune` are built on. `model` is written only when the caller has one - it is
+ * optional in the format, and the startup path resolves an identity BEFORE the
+ * controller exists, so a fabricated model would be a lie on disk for a field
+ * nothing reads back.
+ */
+export function reserveSessionId(id, opts = {}) {
+    const path = (opts.pathFor ?? sessionPathFor)(id);
+    const payload = {
+        version: 1,
+        savedAt: Date.now(),
+        ...(opts.model ? { model: opts.model } : {}),
+        messages: [],
+        entries: [],
+    };
+    let fd;
+    try {
+        // THE DIRECTORY FIRST, and inside the same `try`: on a fresh machine
+        // `sessions/` does not exist yet, and a reservation that silently answered
+        // "name taken" because of a missing parent would send the caller into a
+        // pointless retry loop. A parent that is a FILE fails here, which is the
+        // honest answer.
+        mkdirSync(dirname(path), { recursive: true });
+        fd = openSync(path, 'wx');
+    }
+    catch {
+        // EEXIST is the ordinary answer to "someone already holds this name", and a
+        // missing directory is the ordinary answer on a fresh machine. Both mean
+        // "this id is not available", which is all the caller can act on.
+        return false;
+    }
+    try {
+        writeSync(fd, `${JSON.stringify(payload, null, 2)}\n`);
+    }
+    catch {
+        // A half-written placeholder is exactly the unreadable file D-23 exists to
+        // rule out, so the failure is undone rather than left behind.
+        closeSync(fd);
+        unlinkQuietly(path);
+        return false;
+    }
+    // Closed IMMEDIATELY: an open handle keeps Windows from replacing the file
+    // when the first checkpoint lands (the same reason `store.ts` closes its lock
+    // handle at once).
+    closeSync(fd);
+    return true;
+}
+/** Best effort: a cleanup failure must not turn "id unavailable" into a throw. */
+function unlinkQuietly(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Nothing to clean up, or someone else already did.
+    }
+}

package/dist/session/limits.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Structural bounds for session identity and the session checkpoint
+ * (tui-session-id-resume §3.13).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * STRUCTURE, NOT POLICY: these are the shapes an id and a checkpoint can
+ * physically take, so they live in the subsystem's own `limits.ts` like every
+ * other subsystem's do (CLAUDE.md: "`limits.ts` is structural,
+ * `config/schema.ts` is policy"). Nothing here is user-tunable (D-19): a
+ * "show an id but never write it" switch would manufacture the one state this
+ * feature must not have - an id a user can copy and cannot use.
+ */
+export declare const SESSION_ID_LIMITS: {
+    /** 6 characters of `SESSION_ID_ALPHABET`: 31^6 is about 8.9e8 ids. */
+    readonly idLength: 6;
+    /** The branch suffix, `-` plus this many characters. */
+    readonly suffixLength: 4;
+    /** The upper bound `SESSION_ID_RE` already imposes (`store.ts:50`). */
+    readonly maxIdLength: 64;
+    /** `maxIdLength - 1 - suffixLength` = 64 - 1 - 4. */
+    readonly maxRootLength: 59;
+    /** `wx` reservation attempts before a fresh id is minted instead. */
+    readonly reserveAttempts: 5;
+};
+export declare const SESSION_CHECKPOINT_LIMITS: {
+    /** The window several `agent_end` events are merged into (T-11b). */
+    readonly debounceMs: 750;
+    /** Floor between two writes, so a burst cannot land twice in one turn. */
+    readonly minWriteIntervalMs: 250;
+    /** `renameSync` retries when Windows refuses to replace an open file (D-4). */
+    readonly renameAttempts: 3;
+    /** Gap between those retries, waited synchronously (`Atomics.wait`). */
+    readonly renameRetryMs: 20;
+    /** Consecutive failures before the log record is raised from warn to error. */
+    readonly loudFailureStreak: 3;
+};
+/**
+ * Structural bounds for branching a session into a NEW terminal window
+ * (tui-branch-terminal-shortcut 5.3).
+ *
+ * WHY THESE LIVE HERE (R-12): this file's header says STRUCTURE, NOT POLICY, and
+ * `cooldownMs` is a timing policy. The precedent is already in this file -
+ * `SESSION_CHECKPOINT_LIMITS.debounceMs` / `minWriteIntervalMs` are timing
+ * policies of exactly the same kind. D-17 keeps every one of these out of
+ * `config/schema.ts`, so none of them is user-tunable.
+ *
+ * EVERY ENTRY NEEDS AN ENFORCEMENT POINT (R-7): a declared limit nobody checks is
+ * worse than no limit, because it makes a review believe the case was handled.
+ * `cooldownMs` is read in `branch-launch.ts` steps 1-2, `titleMaxCells` by
+ * `truncateTitle()` in step 7, `spawnProbeMs` by the `trySpawn` timer,
+ * `maxCommandLineCells` in step 4.5 BEFORE any spawn, and `maxRungs` as the
+ * bound of the rung loop in step 8.
+ */
+export declare const BRANCH_TERMINAL_LIMITS: {
+    /** Minimum gap between two successful opens (D-10). FAILURES DO NOT CONSUME IT. */
+    readonly cooldownMs: 2000;
+    /** Max cells of the new window title (`aragon ` + id; an id can be 64 long). */
+    readonly titleMaxCells: 60;
+    /** How long to wait for the `'spawn'` event; a timeout counts as success. */
+    readonly spawnProbeMs: 1500;
+    /** Hard cap on one command line (base64 included); over it we refuse (step 4.5). */
+    readonly maxCommandLineCells: 8000;
+    /** How many rungs to try (the POSIX candidate table can be long; 3 covers reality). */
+    readonly maxRungs: 3;
+};

package/dist/session/limits.js

@@ -0,0 +1,66 @@
+/**
+ * Structural bounds for session identity and the session checkpoint
+ * (tui-session-id-resume §3.13).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * STRUCTURE, NOT POLICY: these are the shapes an id and a checkpoint can
+ * physically take, so they live in the subsystem's own `limits.ts` like every
+ * other subsystem's do (CLAUDE.md: "`limits.ts` is structural,
+ * `config/schema.ts` is policy"). Nothing here is user-tunable (D-19): a
+ * "show an id but never write it" switch would manufacture the one state this
+ * feature must not have - an id a user can copy and cannot use.
+ */
+export const SESSION_ID_LIMITS = {
+    /** 6 characters of `SESSION_ID_ALPHABET`: 31^6 is about 8.9e8 ids. */
+    idLength: 6,
+    /** The branch suffix, `-` plus this many characters. */
+    suffixLength: 4,
+    /** The upper bound `SESSION_ID_RE` already imposes (`store.ts:50`). */
+    maxIdLength: 64,
+    /** `maxIdLength - 1 - suffixLength` = 64 - 1 - 4. */
+    maxRootLength: 59,
+    /** `wx` reservation attempts before a fresh id is minted instead. */
+    reserveAttempts: 5,
+};
+export const SESSION_CHECKPOINT_LIMITS = {
+    /** The window several `agent_end` events are merged into (T-11b). */
+    debounceMs: 750,
+    /** Floor between two writes, so a burst cannot land twice in one turn. */
+    minWriteIntervalMs: 250,
+    /** `renameSync` retries when Windows refuses to replace an open file (D-4). */
+    renameAttempts: 3,
+    /** Gap between those retries, waited synchronously (`Atomics.wait`). */
+    renameRetryMs: 20,
+    /** Consecutive failures before the log record is raised from warn to error. */
+    loudFailureStreak: 3,
+};
+/**
+ * Structural bounds for branching a session into a NEW terminal window
+ * (tui-branch-terminal-shortcut 5.3).
+ *
+ * WHY THESE LIVE HERE (R-12): this file's header says STRUCTURE, NOT POLICY, and
+ * `cooldownMs` is a timing policy. The precedent is already in this file -
+ * `SESSION_CHECKPOINT_LIMITS.debounceMs` / `minWriteIntervalMs` are timing
+ * policies of exactly the same kind. D-17 keeps every one of these out of
+ * `config/schema.ts`, so none of them is user-tunable.
+ *
+ * EVERY ENTRY NEEDS AN ENFORCEMENT POINT (R-7): a declared limit nobody checks is
+ * worse than no limit, because it makes a review believe the case was handled.
+ * `cooldownMs` is read in `branch-launch.ts` steps 1-2, `titleMaxCells` by
+ * `truncateTitle()` in step 7, `spawnProbeMs` by the `trySpawn` timer,
+ * `maxCommandLineCells` in step 4.5 BEFORE any spawn, and `maxRungs` as the
+ * bound of the rung loop in step 8.
+ */
+export const BRANCH_TERMINAL_LIMITS = {
+    /** Minimum gap between two successful opens (D-10). FAILURES DO NOT CONSUME IT. */
+    cooldownMs: 2_000,
+    /** Max cells of the new window title (`aragon ` + id; an id can be 64 long). */
+    titleMaxCells: 60,
+    /** How long to wait for the `'spawn'` event; a timeout counts as success. */
+    spawnProbeMs: 1_500,
+    /** Hard cap on one command line (base64 included); over it we refuse (step 4.5). */
+    maxCommandLineCells: 8_000,
+    /** How many rungs to try (the POSIX candidate table can be long; 3 covers reality). */
+    maxRungs: 3,
+};

package/dist/session/persist.d.ts

@@ -18,8 +18,17 @@ import { type CompactionIdentity } from '../compaction/memory-identity.js';
  * every bare-name and default `/save` target in `getSessionsDir()`. So
  * `aragon sessions list` / `prune` operate ONLY on files carrying `meta.id`,
  * which is what stops a maintenance command destroying conversations a human
- * saved by hand. Anything that starts writing `meta` from the TUI path must
- * revisit that scoping first.
+ * saved by hand.
+ *
+ * THE TUI NOW WRITES `meta`, AND THE RE-EXAMINATION THAT WARNING DEMANDED IS
+ * DONE (tui-session-id-resume 3.7 / R-7). Two axes were hiding in the one
+ * `managed` flag: "may a maintenance command see this row" (still `meta.id`) and
+ * "which writer produced it" (`origin`). `prune` now defaults to
+ * `origin === 'exec'`, so it behaves EXACTLY as it did before this feature on
+ * every file that existed before it; `--all` still only means "also consider
+ * files with no metadata at all" and can no longer reach a TUI checkpoint;
+ * `pinned` is a permanent opt-out and `live` plus a live owner pid is a
+ * temporary one. Four fields, four different jobs - none derivable from another.
  */
 export interface SessionMeta {
     id: string;
@@ -36,6 +45,20 @@ export interface SessionMeta {
         inputTokens: number;
         outputTokens: number;
     };
+    /**
+     * Who wrote this file. Absent (every pre-feature file) reads as 'exec'.
+     *
+     * OPTIONAL AND ADDITIVE, so SESSION_VERSION stays 1: validate-session.ts does
+     * not shape-check `meta` at all, so an older build reads a newer file and a
+     * newer build reads an older one without a migration.
+     */
+    origin?: 'exec' | 'tui';
+    /** `--save <id>` / `/session pin`: `sessions prune` never deletes it. */
+    pinned?: true;
+    /** The writer was alive at this write; omitted by the exit flush. */
+    live?: true;
+    /** The id this session branched from (D-5); absent for a fresh or named one. */
+    branchOf?: string;
 }
 export interface SavedSession {
     version: number;
@@ -53,13 +76,15 @@ export interface SavedSession {
      */
     todos?: TodoItem[];
     /**
-     * Written only by `aragon exec` (cli-integration-surface §5.2 / D-10).
+     * Written by `aragon exec` (cli-integration-surface §5.2 / D-10) AND by the
+     * TUI's session checkpoint (tui-session-id-resume §6.1).
      *
      * `SESSION_VERSION` STAYS 1 for the reason `todos?` records above, and this is
      * the precedent that file's own comments already set: the field is additive
      * and optional. Boundary validation preserves it without changing its shape.
-     * A TUI `/save` file simply has no `meta`, which is exactly how
-     * `sessions list` tells the two apart.
+     * A TUI `/save` EXPORT still has no `meta` at all, which is what keeps a
+     * hand-made file out of the maintenance commands' scope; a TUI CHECKPOINT has
+     * one, and is told apart from an exec file by `meta.origin`.
      */
     meta?: SessionMeta;
 }

package/dist/session/startup-session.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Startup-time session resolution: `--resume <id|path>` and `--save <id>`
+ * (tui-session-id-resume §3.8 / D-5..D-9 / D-20 / D-23).
+ *
+ * ASCII ONLY - `src/session/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * ONE RESOLUTION, TWO CALLERS. The TUI (`runInteractive`) and the headless
+ * one-shot (`runOneShot`) both come through here, and the in-TUI `/resume`
+ * command shares `applyRestoredSession` with them, because two copies of "adopt
+ * a saved conversation" is how `/clear` and `/reset` drifted apart once already.
+ *
+ * THIS MODULE DOES NO I/O BEYOND READING THE FILE AND CLAIMING THE NEW ID. It
+ * builds no controller and renders nothing, so every rule below is testable as a
+ * pure function: a caller gets either an identity plus an `apply` thunk, or one
+ * message and exit code 2.
+ *
+ * THE PARENT IS NEVER WRITTEN (I-3). The id comes from the file NAME, the new id
+ * is always derived, and the only write this module performs is the `wx` claim
+ * of that new id - which is a different file by construction.
+ */
+import type { Message } from '@aragon-agent/core';
+import type { Entry } from '../agent/reducer.js';
+import type { TodoItem } from '../todo/types.js';
+import type { CompactionIdentity } from '../compaction/memory-identity.js';
+import { type SavedSession } from './persist.js';
+/** Who this process is, as the rest of the CLI sees it. */
+export interface SessionIdentity {
+    id: string;
+    kind: 'fresh' | 'named' | 'branch';
+    /** The id this one branched from; absent unless `kind === 'branch'`. */
+    parentId?: string;
+    /** `--save` / `/session pin`: `sessions prune` will not delete it. */
+    pinned?: boolean;
+}
+export interface StartupSessionInput {
+    /** `--resume <id|path>` - both spellings are legal (D-5 / R-8). */
+    resume?: string;
+    /** `--save <id>` - an ID, never a path (D-6). */
+    saveAs?: string;
+    cwd: string;
+    /** True when the user named `--model` / `--provider` explicitly (D-9). */
+    explicitModel?: boolean;
+}
+/**
+ * The minimum controller surface the restore needs.
+ *
+ * THREE METHODS, and `getConfig` is deliberately not one of them: the three
+ * calls below need nothing else, and a wider port only makes the startup path
+ * look like it knows more about the controller than it does.
+ */
+export interface SessionRestorePort {
+    replaceMessages(messages: Message[], identity?: CompactionIdentity): void;
+    restoreTodos(items: TodoItem[]): void;
+    setModel(providerId: string, modelId: string, baseUrl?: string): void;
+}
+export type StartupSessionResolution = {
+    ok: true;
+    identity: SessionIdentity;
+    initialEntries: Entry[];
+    notice?: string;
+    /** The file this session was branched from, if any. */
+    saved?: SavedSession;
+    apply(port: SessionRestorePort): void;
+} | {
+    ok: false;
+    exitCode: 2;
+    message: string;
+};
+/**
+ * Adopt a saved conversation. THE ONLY IMPLEMENTATION of the three calls
+ * `/resume` makes; the slash command and both startup paths call it.
+ *
+ * `skipModel` exists because an explicit `--model` / `--provider` on this run
+ * outranks the model recorded in the file: a user who says which model they want
+ * has said it more recently than the file did.
+ *
+ * `clearAllQueues()` and the `restoreEntries` dispatch are NOT here and belong at
+ * the call sites: the first is a no-op on the startup path (there are no queues
+ * yet) and indispensable inside a live TUI, and the second is a VIEW action with
+ * no controller to attach it to - the startup path seeds the reducer instead.
+ */
+export declare function applyRestoredSession(port: SessionRestorePort, saved: SavedSession, opts?: {
+    skipModel?: boolean;
+}): void;
+/**
+ * Work out which session this process is, and what it starts from.
+ *
+ * FAILURE IS EXIT 2 WITH ONE COPYABLE SENTENCE, and it happens BEFORE any write
+ * (the only write is the id claim, and it is last). Sources: a `--save` value
+ * that is not an id (D-6), a `--save` id that is already taken (D-6), a `--save`
+ * naming the id being resumed (D-7), and a `--resume` that is missing or
+ * unreadable (D-8).
+ */
+export declare function resolveStartupSession(input: StartupSessionInput): StartupSessionResolution;
+/**
+ * Move to a derived id after a `/resume` inside the TUI (D-15 / R-9).
+ *
+ * THE ROTATION IS NOT COSMETIC. `/resume` adopts another conversation, so the
+ * next checkpoint would otherwise write THAT conversation into THIS id's file -
+ * silently destroying the disk record the user was building. The id therefore
+ * changes with the content, exactly as it does on a startup branch, and the
+ * caller resets the spend in the same breath (D-10).
+ *
+ * The parent id comes from the FILE NAME, never from `meta.id` (D-5): a file's
+ * contents are input.
+ */
+export declare function rotateToChildOf(loadedPath: string): SessionIdentity | undefined;