@phnx-labs/agents-cli 1.20.73 → 1.20.76

package/dist/lib/session/discover.d.ts

@@ -11,6 +11,14 @@ import { type ScanStamp } from './db.js';
 /** Options controlling which sessions to discover and how to report progress. */
 export interface DiscoverOptions {
     agent?: SessionAgentId;
+    /**
+     * Include sessions from the user's own (unmanaged) `~/.<agent>` alongside managed
+     * version homes. Defaults to true only when the agent has no managed versions, so
+     * a user who has never run `agents add` sees exactly what they see today.
+     */
+    includeUnmanaged?: boolean;
+    /** Called with how many rows the managed-only default hid, so callers can say so. */
+    onHiddenUnmanaged?: (count: number) => void;
     version?: string;
     project?: string;
     all?: boolean;
@@ -75,6 +83,29 @@ interface ClaudeSessionScan {
     /** Plan markdown from the last ExitPlanMode tool call (Claude sessions only). */
     plan?: string;
 }
+/** Lightweight metadata extracted from a Codex JSONL file during incremental scan. */
+interface CodexSessionScan {
+    sessionId?: string;
+    timestamp?: string;
+    cwd?: string;
+    gitBranch?: string;
+    version?: string;
+    topic?: string;
+    messageCount: number;
+    tokenCount?: number;
+    /** Real generated (output) tokens, excluding cache-read/-write context. */
+    outputTokens?: number;
+    costUsd?: number;
+    durationMs?: number;
+    lastActivity?: string;
+    contentText?: string;
+    prUrl?: string;
+    prNumber?: number;
+    worktreeSlug?: string;
+    ticketId?: string;
+    createdTickets?: string[];
+    spawnedTeam?: string;
+}
 /**
  * Discover sessions. Scans only files whose (mtime, size) have changed since
  * the last run; everything else is served from the SQLite cache.
@@ -101,6 +132,18 @@ export declare function scanAgentsBounded<T>(items: readonly T[], run: (item: T)
  * when the path sits under the agent's backups root, the first segment below it
  * is the origin machine id; otherwise it's the local machine.
  */
+/**
+ * True when this transcript belongs to a version agents-cli manages — i.e. it lives
+ * under a version home (or a backup mirror of one) rather than in the user's own
+ * `~/.<agent>`.
+ *
+ * `agents sessions` scans both, which is right for indexing: the DB stays a complete
+ * picture and `--unmanaged` can surface everything without a re-scan. But listing
+ * *by default* is a different question. Once you have managed versions, an unmanaged
+ * install's history is not really agents-cli's to show — most visibly after
+ * `agents add --isolated`, where the whole point was to keep the two apart.
+ */
+export declare function isManagedSessionFile(filePath: string): boolean;
 export declare function machineForSessionFile(filePath: string, agent: string): string;
 /**
  * Count sessions in scope without running an incremental scan. Assumes the DB
@@ -108,6 +151,45 @@ export declare function machineForSessionFile(filePath: string, agent: string):
  * turn). Uses the exact same filter shape as the discover query.
  */
 export declare function countSessionsInScope(options: DiscoverOptions): number;
+/**
+ * Canonicalize a working directory path (follows symlinks when it is local).
+ *
+ * Most callers pass a cwd RECORDED in a transcript, which may name a directory
+ * on another machine — a POSIX path read on a Windows host, say. `path.resolve()`
+ * rebases such a path onto the current drive (`/Users/me` -> `D:\Users\me`),
+ * inventing a location that never existed. So an absolute path is normalized but
+ * never rebased; only a genuinely relative one resolves against the process cwd.
+ *
+ * `path.normalize()` still runs on every branch: it collapses `.`, `..`, and
+ * duplicate separators, and folds separators on Windows. Both sides of the cwd
+ * filter in `db.ts` (`cwd = ?` and `cwd LIKE ? || path.sep || '%'`) come through
+ * here, so dropping that would leave a trailing slash or a `..` segment in one
+ * side and match nothing.
+ *
+ * Realpath is attempted only for a path that is absolute in THIS platform's
+ * terms. A POSIX-rooted path on Windows is drive-relative to `fs.realpathSync`,
+ * which would resolve `/Users/me` against the current drive and reintroduce the
+ * graft for any path that happens to exist locally.
+ */
+export declare function _normalizeCwdForTest(cwd?: string): string;
+/**
+ * Whether a query is a session id in full, rather than an id prefix or a search
+ * phrase.
+ *
+ * Callers use this to decide that an id lookup is the ONLY admissible
+ * interpretation: a complete id is unique, so when it misses there is nothing
+ * left to widen to. Without the check, `sessions <uuid>` fell through to the
+ * FTS content search, which tokenizes the UUID and matches every transcript that
+ * merely mentions it — surfacing unrelated sessions as if they were id matches.
+ *
+ * The accepted shapes are the ones the index actually holds, measured over a
+ * 12,507-row index: a bare UUID (11,116 rows), `session_` + UUID (1,360 — kimi
+ * and rush), and `ses_` + ULID (15 — opencode). Deliberately NOT covered, so a
+ * miss keeps today's search behavior rather than gaining a wrong error: routine
+ * run ids (ISO timestamps, matched via `routineRunId` below) and cloud execution
+ * ids, whose charset is too permissive to distinguish from a search phrase.
+ */
+export declare function isCompleteSessionId(query: string): boolean;
 /**
  * Resolve a session by full or short ID. Accepts a pre-loaded session list
  * (fast path from discoverSessions) and falls back to a DB lookup for the
@@ -119,7 +201,87 @@ export declare function resolveSessionById(sessions: SessionMeta[], idQuery: str
  * preserving the existing SessionMeta[] contract so sessions.ts is unchanged.
  */
 export declare function searchContentIndex(sessions: SessionMeta[], query: string): Map<string, SessionMeta>;
+/**
+ * For a list of files, stat each, compare to the DB ledger, and return only
+ * the ones that need rescanning. One bulk DB query for the whole list.
+ *
+ * Actively running agents append to their JSONL every few seconds. Without a
+ * small debounce, repeated `agents sessions` invocations stream-parse the same
+ * growing transcript over and over. The cached row is good enough for a few
+ * seconds; once writes settle or the debounce expires, the file is parsed once.
+ */
+export declare function filterChangedFiles(filePaths: string[]): Array<{
+    filePath: string;
+    scan: ScanStamp;
+}>;
+/** A path already stat'd by the walk — mtime is the raw (unfloored) fs value. */
+export interface PreStatEntry {
+    filePath: string;
+    fileMtimeMs: number;
+    fileSize: number;
+}
+/**
+ * Ledger-compare pre-stat'd entries (from the walk's own stat) without a second
+ * stat. Same debounce and change-detection as filterChangedFiles; the raw
+ * mtime is floored here so warm files match the ledger exactly as the stat path
+ * does (Math.floor(stat.mtimeMs)).
+ */
+export declare function filterChangedEntries(entries: PreStatEntry[]): Array<{
+    filePath: string;
+    scan: ScanStamp;
+}>;
 export declare function shouldDeferRecentAppend(prev: ScanStamp, current: ScanStamp, nowMs: number, debounceMs?: number): boolean;
+/** One leaf directory of transcripts to change-detect, plus its live-root flag. */
+export interface LeafDir {
+    /** Absolute path to the directory that directly holds transcript files. */
+    dirPath: string;
+    /**
+     * True if this dir is under the agent's LIVE `~/.<agent>` root — the only tree
+     * an agent process appends to live. Every file in such a dir is treated as
+     * hot (always re-stat'd), so an in-place append is never missed there.
+     */
+    isLiveRoot: boolean;
+}
+/** The changed files a leaf-dir walk surfaced, ready to parse + upsert. */
+export interface LeafDirScan {
+    /** Files whose (mtime, size) changed vs the ledger — the parse set. */
+    changed: Array<{
+        filePath: string;
+        scan: ScanStamp;
+    }>;
+    /**
+     * Every transcript file seen across all leaf dirs (changed or not), in
+     * live-root-first order, each tagged with whether its dir is a live root.
+     * Lets a caller restore cross-root, session-id precedence (prefer the live
+     * copy of a session over a frozen backup copy) independent of which copy
+     * happened to be flagged "changed" this run.
+     */
+    allFiles: Array<{
+        filePath: string;
+        isLiveRoot: boolean;
+    }>;
+}
+/**
+ * Walk a set of leaf transcript directories and return the files that changed,
+ * skipping the per-file `stat` of directories whose (mtime, entry_count) matches
+ * the dir_ledger.
+ *
+ * Per leaf dir:
+ *   - `stat` the dir once and `readdir` it (one cheap syscall) to get the entry
+ *     count and the file list.
+ *   - If the dir matches the dir_ledger (floored mtime AND entry_count), no file
+ *     was created / deleted / renamed since we last walked it. We then stat ONLY
+ *     the hot files (live-root files, or files scanned within HOT_FILE_WINDOW_MS)
+ *     and run just those through the ledger compare — so an in-place append to a
+ *     still-live session is still caught, while immutable backup/version dirs
+ *     collapse to a single dir stat and zero per-file stats.
+ *   - Else (changed dir, or no ledger row) we stat every file (today's full
+ *     walk) and record the fresh dir stamp so the next run can short-circuit.
+ *
+ * The kill-switch (`AGENTS_SESSIONS_NO_DIR_LEDGER=1`) forces the full-walk branch
+ * for every dir and never consults or records the dir_ledger.
+ */
+export declare function collectChangedFilesInLeafDirs(leafDirs: LeafDir[], ext: string): LeafDirScan;
 /**
  * Collect all directories to scan for an agent's sessions. Deduplicates by
  * realpath to avoid double-counting symlinked version homes.
@@ -165,14 +327,315 @@ export declare function parseCodexThreadNameIndex(raw: string): Map<string, stri
  * performs is deferred until we know this file is a real session worth building
  * metadata for, and only then — never during the file walk / stat phase.
  */
-export declare function readCodexMeta(filePath: string, resolveAccount?: () => string | undefined, currentVersion?: string): Promise<{
+export declare function readCodexMeta(filePath: string, resolveAccount?: () => string | undefined, currentVersion?: string, scanStamp?: ScanStamp, priorRow?: {
+    parserState: string | null;
+    fileMtimeMs: number;
+}): Promise<{
     meta: SessionMeta;
     content: string;
+    parserState?: string;
+    contentText?: string;
 } | null>;
+/**
+ * Mutable accumulator for the Claude transcript reducer. One field per local
+ * that {@link scanClaudeSession} previously declared inline — the reducer
+ * mutates `state.*` instead of closure locals so the exact same logic can drive
+ * both a full parse and a resumable incremental parse (see
+ * {@link scanClaudeSessionIncremental}).
+ */
+export interface ClaudeParseState {
+    timestamp?: string;
+    cwd?: string;
+    gitBranch?: string;
+    version?: string;
+    topic?: string;
+    customTitle?: string;
+    aiTitle?: string;
+    entrypoint?: string;
+    messageCount: number;
+    tokenCount: number;
+    outputTokens: number;
+    sawTokenCount: boolean;
+    costUsd: number;
+    sawCost: boolean;
+    firstTsMs?: number;
+    lastTsMs?: number;
+    seenAssistantIds: Set<string>;
+    userTexts: string[];
+    sawPrCreate: boolean;
+    prUrl?: string;
+    prNumber?: number;
+    createdTickets: Set<string>;
+    pendingTicketTools: Set<string>;
+    spawnedTeam?: string;
+    plan?: string;
+}
+/** Zero-value accumulator for a fresh (from-byte-0) Claude parse. */
+export declare function initClaudeParseState(): ClaudeParseState;
+/**
+ * Fold one parsed transcript line into the accumulator. This is the exact loop
+ * body {@link scanClaudeSession} used to run inline — extracted verbatim,
+ * mutating `state.*` in place. `parsed` is the already-`JSON.parse`d line (the
+ * malformed-line skip happens in the caller, as before).
+ */
+export declare function applyClaudeLine(state: ClaudeParseState, parsed: any): void;
+/**
+ * Build the {@link ClaudeSessionScan} return object from an accumulator. This is
+ * the exact return-building {@link scanClaudeSession} used to run inline.
+ */
+export declare function finalizeClaudeScan(state: ClaudeParseState): ClaudeSessionScan;
 /** Stream a Claude JSONL file and extract scan-level metadata (timestamp, cwd, topic, tokens). */
 export declare function scanClaudeSession(filePath: string): Promise<ClaudeSessionScan>;
+/**
+ * SERIALIZED continuation blob persisted in `scan_ledger.parser_state`. Carries
+ * everything {@link hydrateClaudeParseState} needs to resume a parse from
+ * `offset` such that resuming + applying the appended lines is byte-for-byte
+ * identical to a full parse of the whole file.
+ *
+ * `seenAssistantIds` is persisted as a size counter plus a bounded FIFO window
+ * of the most-recent ids: the fallback logical id `${ts}:${seenAssistantIds.size}`
+ * (see {@link applyClaudeLine}) depends on the set's *size*, so the size must be
+ * exact even when the recent window is smaller than the true count.
+ */
+export interface ClaudeParserState {
+    v: 1;
+    offset: number;
+    timestamp?: string;
+    cwd?: string;
+    gitBranch?: string;
+    version?: string;
+    entrypoint?: string;
+    firstTsMs?: number;
+    topic?: string;
+    customTitle?: string;
+    aiTitle?: string;
+    plan?: string;
+    lastTsMs?: number;
+    messageCount: number;
+    tokenCount: number;
+    outputTokens: number;
+    sawTokenCount: boolean;
+    sawCost: boolean;
+    costUsd: number;
+    seenIdsSize: number;
+    seenIdsRecent: string[];
+    sawPrCreate: boolean;
+    prUrl?: string;
+    prNumber?: number;
+    pendingTicketTools: string[];
+    createdTickets: string[];
+    spawnedTeam?: string;
+    ticketId?: string;
+    contentText?: string;
+}
+/**
+ * Snapshot a live {@link ClaudeParseState} into its serializable form at
+ * `offset` bytes consumed. Round-trips through {@link hydrateClaudeParseState}
+ * so incremental replay equals a full parse.
+ */
+export declare function serializeClaudeParserState(state: ClaudeParseState, offset: number): ClaudeParserState;
+/**
+ * Rebuild a live {@link ClaudeParseState} from a persisted continuation so that
+ * applying the appended lines yields the same accumulator a full parse would.
+ *
+ * `seenAssistantIds` is rehydrated from the recent-id FIFO window, then padded
+ * with unique sentinel entries so its `.size` matches the true prior count
+ * (`seenIdsSize`) — the fallback id `${ts}:${size}` must line up with the full
+ * parse even when the window dropped older ids. Padding sentinels can never
+ * collide with a real logical id (real ids are message ids/uuids or
+ * `${ts}:${n}`; the sentinel prefix is not JSON-line-derived).
+ *
+ * `userTexts` is rehydrated as a single joined blob from `contentText`: only
+ * `userTexts.join('\n')` (detectTicket + contentText) and `userTexts.length > 0`
+ * are ever read downstream, and both are preserved by a one-element array
+ * holding the joined content.
+ */
+export declare function hydrateClaudeParseState(prior: ClaudeParserState): ClaudeParseState;
+/**
+ * Resume a Claude parse from `fromOffset` bytes into the file, folding only the
+ * newly-appended lines into `prior`. Returns the finalized scan, the next
+ * serialized continuation, and the byte offset to resume from next time —
+ * `newOffset` stops at the last `'\n'` seen so a half-written trailing record is
+ * re-read (not lost) on the next append.
+ *
+ * NOT wired into the live scan path yet (that is B-2); {@link scanClaudeSession}
+ * remains the only caller-facing entry point. This exists so the parity harness
+ * can prove full === hydrate(state@k) + apply(k+1..n).
+ */
+export declare function scanClaudeSessionIncremental(filePath: string, fromOffset: number, prior: ClaudeParserState): Promise<{
+    scan: ClaudeSessionScan;
+    newState: ClaudeParserState;
+    newOffset: number;
+}>;
+/** Test seam: read the (incremental, full) Claude parse counters. */
+export declare function __claudeScanBranchCountsForTest(): {
+    incremental: number;
+    full: number;
+};
+/** Test seam: reset the Claude parse-branch counters to observe a scan from a clean slate. */
+export declare function __resetClaudeScanBranchCountsForTest(): void;
+/**
+ * Live (in-memory) accumulator for a Codex parse — the mutable state
+ * {@link scanCodexSession} used to hold in local `let`s, extracted so the same
+ * fold ({@link applyCodexLine}) runs for both a full parse and an incremental
+ * resume. Mirrors {@link ClaudeParseState}.
+ */
+export interface CodexParseState {
+    sessionId?: string;
+    timestamp?: string;
+    cwd?: string;
+    gitBranch?: string;
+    version?: string;
+    model?: string;
+    topic?: string;
+    messageCount: number;
+    tokenCount?: number;
+    lastTotalTokenUsage?: any;
+    firstTsMs?: number;
+    lastTsMs?: number;
+    userTexts: string[];
+    sawPrCreate: boolean;
+    prUrl?: string;
+    prNumber?: number;
+    createdTickets: Set<string>;
+    pendingTicketTools: Set<string>;
+    spawnedTeam?: string;
+}
+/** Zero-value accumulator for a fresh (from-byte-0) Codex parse. */
+export declare function initCodexParseState(): CodexParseState;
+/**
+ * Fold one parsed Codex line into the accumulator — the exact loop body
+ * {@link scanCodexSession} used to run inline, extracted verbatim and mutating
+ * `state.*` in place. `parsed` is the already-`JSON.parse`d line (the
+ * malformed-line skip happens in the caller, as before).
+ */
+export declare function applyCodexLine(state: CodexParseState, parsed: any): void;
+/**
+ * Build the {@link CodexSessionScan} return object from an accumulator — the
+ * exact return-building {@link scanCodexSession} used to run inline.
+ */
+export declare function finalizeCodexScan(state: CodexParseState): CodexSessionScan;
+/**
+ * SERIALIZED continuation blob persisted in `scan_ledger.parser_state` for a
+ * Codex rollout. Carries everything {@link hydrateCodexParseState} needs to
+ * resume a parse from `offset` such that resuming + applying the appended lines
+ * is byte-for-byte identical to a full parse of the whole file.
+ *
+ * Unlike Claude, Codex has NO per-message dedup set, so `messageCount` is a
+ * plain additive base with no recent-id window to persist. The `lastTotalTokenUsage`
+ * object is round-tripped whole so the last-wins cost/output-token pricing at
+ * finalize is identical after a resume.
+ */
+export interface CodexParserState {
+    v: 1;
+    offset: number;
+    sessionId?: string;
+    timestamp?: string;
+    cwd?: string;
+    gitBranch?: string;
+    version?: string;
+    model?: string;
+    topic?: string;
+    messageCount: number;
+    tokenCount?: number;
+    lastTotalTokenUsage?: any;
+    firstTsMs?: number;
+    lastTsMs?: number;
+    sawPrCreate: boolean;
+    prUrl?: string;
+    prNumber?: number;
+    pendingTicketTools: string[];
+    createdTickets: string[];
+    spawnedTeam?: string;
+    ticketId?: string;
+    contentText?: string;
+}
+/**
+ * Snapshot a live {@link CodexParseState} into its serializable form at `offset`
+ * bytes consumed. Round-trips through {@link hydrateCodexParseState} so
+ * incremental replay equals a full parse.
+ */
+export declare function serializeCodexParserState(state: CodexParseState, offset: number): CodexParserState;
+/**
+ * Rebuild a live {@link CodexParseState} from a persisted continuation so that
+ * applying the appended lines yields the same accumulator a full parse would.
+ *
+ * `userTexts` is rehydrated as a single joined blob from `contentText`: only
+ * `userTexts.join('\n')` (detectTicket + contentText) and `userTexts.length > 0`
+ * are ever read downstream, and both are preserved by a one-element array
+ * holding the joined content. Topic is first-wins and already persisted, so a
+ * collapsed userTexts never changes it.
+ */
+export declare function hydrateCodexParseState(prior: CodexParserState): CodexParseState;
+/**
+ * Resume a Codex parse from `fromOffset` bytes into the file, folding only the
+ * newly-appended lines into `prior`. Returns the finalized scan, the next
+ * serialized continuation, and the byte offset to resume from next time.
+ *
+ * Same trailing-line discipline as {@link scanClaudeSessionIncremental}: apply
+ * ONLY the run of newline-terminated lines (slice at the last `'\n'`), and set
+ * `newOffset = fromOffset + consumedBytes`. Any tail after the last `'\n'` —
+ * syntactically broken OR a complete-but-not-yet-terminated record — is DEFERRED
+ * to the next pass once its `'\n'` lands. Codex `messageCount` is additive with
+ * NO dedup, so re-reading a still-unterminated complete line would double-count
+ * it; deferring prevents that (the bug class prix-cloud caught for Claude).
+ */
+export declare function scanCodexSessionIncremental(filePath: string, fromOffset: number, prior: CodexParserState): Promise<{
+    scan: CodexSessionScan;
+    newState: CodexParserState;
+    newOffset: number;
+}>;
+/** Test seam: read the (incremental, full) Codex parse counters. */
+export declare function __codexScanBranchCountsForTest(): {
+    incremental: number;
+    full: number;
+};
+/** Test seam: reset the Codex parse-branch counters to observe a scan from a clean slate. */
+export declare function __resetCodexScanBranchCountsForTest(): void;
 /** Parse a single Kimi session state.json file to extract session metadata. */
-export declare function readKimiMeta(filePath: string): {
+export declare function readKimiMeta(filePath: string, priorRow?: {
+    parserState: string | null;
+}): {
+    meta: SessionMeta;
+    content: string;
+    parserState?: string;
+} | null;
+/**
+ * Kimi wire metrics are pure additive counters (messageCount, tokenCount,
+ * outputTokens) with NO straddle/dedup state, so the continuation is just those
+ * three bases plus the byte `offset` already consumed from wire.jsonl. Resuming
+ * from `offset` + adding the appended tail's deltas equals a full parse.
+ */
+export interface KimiParserState {
+    v: 1;
+    offset: number;
+    messageCount: number;
+    tokenCount: number;
+    outputTokens: number;
+}
+/**
+ * Incrementally parse Kimi's wire.jsonl for message-count and token counters,
+ * resuming from a persisted continuation instead of re-reading from byte 0 every
+ * scan. Returns the finalized counters and the next {@link KimiParserState} to
+ * persist (offset + the three counter bases).
+ *
+ * Same trailing-line discipline as {@link scanClaudeSessionIncremental}: read
+ * only the appended byte range from `prior.offset`, apply ONLY the run of
+ * newline-terminated lines (slice at the last `'\n'`), and advance the offset to
+ * `prior.offset + consumedBytes`. A complete-but-not-yet-terminated last record
+ * is DEFERRED to the next pass; because these counters are additive with no
+ * dedup, re-reading such a line would double-count it. FULL parse from byte 0
+ * (fresh counters) when there is no prior OR the file shrank below the stored
+ * offset (truncation/rewrite).
+ */
+export declare function parseKimiWireMetricsIncremental(sessionDir: string, prior: KimiParserState | null): {
+    messageCount: number;
+    tokenCount: number;
+    outputTokens: number;
+    newState: KimiParserState;
+};
+/** Parse a single Grok session summary.json into session metadata. */
+export declare function readGrokMeta(filePath: string, currentVersion?: string): {
     meta: SessionMeta;
     content: string;
 } | null;