@aragon-agent/cli 0.6.25 → 0.6.26

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;
+}