@agentclientprotocol/claude-agent-acp 0.88.1-preview.5 → 0.88.1-preview.7

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

@@ -0,0 +1,201 @@
+/**
+ * The session list of a `sessionIndex` client.
+ *
+ * Each list enumerates the transcripts of the requested cwd and of every
+ * worktree of its repository: one `readdir` per project directory and one
+ * `stat` per transcript, no long-lived cache. The metadata of a transcript is
+ * cached by `(path, mtime, size)` in an LRU and read on a miss with the SDK
+ * `getSessionInfo` (titles, sidecar) plus one head and tail read for
+ * what the SDK does not report (see {@link scanTranscript}). Misses are read in
+ * parallel batches.
+ *
+ * Order is the last user activity descending, then session id: the time of
+ * the last real user prompt (`lastPromptAt`), else `updatedAt`. `updatedAt`
+ * is the time of the last message, capped at the transcript mtime, so a
+ * rename or another metadata record does not move a session up, and the
+ * order key is never later than it. Candidates are read in mtime order: a
+ * candidate's order key is at most its mtime, so the scan stops as soon as
+ * the page is full and the next mtime is older than the key of the last row.
+ */
+import type { SDKSessionInfo } from "@anthropic-ai/claude-agent-sdk";
+import { type TranscriptFacts } from "./transcript-scan.js";
+export declare const DEFAULT_LIST_LIMIT = 50;
+export declare const MAX_LIST_LIMIT = 200;
+/** Which sessions a list holds by archive state: `unarchived` the
+ *  unarchived ones only, `archived` the archived ones only, `all` both in one
+ *  order. */
+export type ArchivedFilter = "unarchived" | "archived" | "all";
+export declare const ARCHIVED_FILTERS: readonly ArchivedFilter[];
+/** Whether `filter` keeps a session of that archive state. */
+export declare function archivedFilterKeeps(filter: ArchivedFilter, archived: boolean): boolean;
+/** One transcript file found by the enumeration. */
+export type TranscriptCandidate = {
+    sessionId: string;
+    filePath: string;
+    dirName: string;
+    /** The requested path (cwd or worktree) whose project directory this is. */
+    projectPath?: string;
+    mtimeMs: number;
+    size: number;
+    /** Tells a replaced file from one that grew. */
+    ino: number;
+};
+export type IndexRow = {
+    sessionId: string;
+    cwd: string;
+    title: string;
+    updatedAtMs: number;
+    /** The order key: the last user activity, `lastPromptAt`, else
+     *  `updatedAt`. Never later than `updatedAt`, so never later than the
+     *  transcript mtime. */
+    orderAtMs: number;
+    facts: TranscriptFacts;
+    mtimeMs: number;
+    archived: boolean;
+};
+/** A keyset position: the order key and the session id of the last row. */
+export type ListCursor = {
+    orderAtMs: number;
+    sessionId: string;
+};
+export type ListQuery = {
+    cwd?: string | null;
+    /** Also list the sessions of the existing linked worktrees of `cwd`. */
+    includeWorktrees?: boolean;
+    limit: number;
+    archived: ArchivedFilter;
+    after?: ListCursor;
+};
+export type GetSessionInfo = (sessionId: string, options: {
+    dir?: string;
+}) => Promise<SDKSessionInfo | undefined>;
+/** The title of the CLI's `custom-title.json` sidecar of a transcript. */
+export declare function readSidecarTitle(filePath: string, sessionId: string): Promise<string | undefined>;
+export declare class SessionIndex {
+    private readonly getSessionInfo;
+    private readonly listings;
+    private readonly metadata;
+    /** The metadata reads in flight, by path: a list and a subscription that
+     *  want the same transcript at the same stat read it once. */
+    private readonly reading;
+    /** A cwd that encodes to each project directory name, learned from its
+     *  transcripts; it recovers the cwd of a sibling that has none. */
+    private readonly dirCwds;
+    /** The project cwd of the transcripts of prefix-matched long directories. */
+    private readonly transcriptCwds;
+    /** Directories whose transcripts gave no cwd, by the directory mtime and
+     *  when that was learned. */
+    private readonly dirsWithoutCwd;
+    constructor(getSessionInfo: GetSessionInfo);
+    /** The paths whose sessions a list of `cwd` shows: `cwd`, and with
+     *  `includeWorktrees` the same subdirectory of every other existing
+     *  worktree of its repository (the worktree roots for a cwd at the root). */
+    listedPaths(cwd: string, includeWorktrees: boolean): Promise<string[]>;
+    /** The project directories (names under the projects root) of `paths`.
+     *  A long path is matched by its cut prefix, which other long paths may
+     *  share: such a directory counts only when one of its transcripts belongs
+     *  to the path, as the SDK checks. */
+    projectDirs(paths: readonly string[]): Promise<{
+        dirName: string;
+        projectPath: string;
+    }[]>;
+    /** Whether a transcript of the prefix-matched `dirName` belongs to
+     *  `projectPath`. The cwd of each transcript is cached by its
+     *  `(path, mtime, size)`, so a transcript that changes is read again. */
+    private longDirBelongsTo;
+    /** Every non-empty transcript file of `paths` (without, of all projects),
+     *  every copy of a session: a list shows the newest one that has a row
+     *  (see {@link collectRows}), as the SDK does. */
+    enumerateFiles(paths?: readonly string[]): Promise<TranscriptCandidate[]>;
+    /**
+     * Every transcript (with its size) and every `<sessionId>/` directory
+     * (sidecar, subagent transcripts) of the session, in any project
+     * directory, by the exact id. One pass over the (cached) project directory
+     * listings.
+     */
+    scanSession(sessionId: string): Promise<{
+        transcripts: {
+            filePath: string;
+            size: number;
+        }[];
+        sessionDirs: string[];
+    }>;
+    /** Every transcript file of `sessionId` (see {@link scanSession}). Empty
+     *  files only with `includeEmpty`. */
+    findTranscripts(sessionId: string, options?: {
+        includeEmpty?: boolean;
+    }): Promise<string[]>;
+    /** Every `<sessionId>/` directory of the session (see {@link scanSession}). */
+    findSessionDirs(sessionId: string): Promise<string[]>;
+    /** Whether `candidate` was read at its stat: its metadata is cached, also
+     *  when it holds no row. False after a failed read. */
+    isRead(candidate: TranscriptCandidate): boolean;
+    /** The session that the cached metadata of `filePath` says it was
+     *  continued in. */
+    continuedIn(filePath: string): string | undefined;
+    /** Drops the cached metadata of `filePaths`. */
+    invalidate(filePaths: readonly string[]): void;
+    /** One page of rows, plus whether more rows follow the page. */
+    list(query: ListQuery): Promise<{
+        rows: IndexRow[];
+        hasMore: boolean;
+    }>;
+    /**
+     * The rows of `candidates`, one per session (its newest transcript that has
+     * a row), any archive state, as a list of `paths` shows them: a candidate
+     * without a row (no title, a sidechain, continued elsewhere, another path
+     * that shares the project directory) is left out. `siblings` are the other
+     * transcripts of the candidates' directories, read only when a candidate
+     * has no cwd of its own. The metadata cache makes an unchanged transcript
+     * free.
+     */
+    rowsOf(paths: readonly string[], candidates: readonly TranscriptCandidate[], siblings: () => readonly TranscriptCandidate[]): Promise<IndexRow[]>;
+    /**
+     * The rows of `candidates` (as {@link rowsOf}) that the metadata cache
+     * alone gives, read from it at once, and the ids of the sessions it gives
+     * no answer for: a transcript of it has nothing cached at its stat, no cwd
+     * known, or is continued in another session (whether the successor hides
+     * it depends on the successor now). Reads no transcript.
+     */
+    cachedRowsOf(paths: readonly string[], candidates: readonly TranscriptCandidate[]): Promise<{
+        rows: IndexRow[];
+        unknown: Set<string>;
+    }>;
+    /**
+     * Reads `candidates` in order into rows, one per session, sorted. A
+     * session copied to several transcripts shows its newest one that has a
+     * row, as the SDK list does. With a finite `wanted`, stops once `wanted`
+     * rows are certain to come first (a candidate's order key is at most its
+     * mtime, so `candidates` must be in mtime order then).
+     */
+    private collectRows;
+    /** Whether the cached metadata of `candidate`, still current, places it
+     *  at or before `cursor`. */
+    private cachedBefore;
+    /** Reads the unread transcripts of `dirNames` until each directory has a
+     *  known cwd, at most {@link MAX_CWD_PROBES_PER_DIR} per directory. A
+     *  directory that gives none is not read again for a while, unless it
+     *  changes. */
+    private learnDirCwds;
+    /** The requested path of the directory, else a sibling's cwd. */
+    private fallbackCwd;
+    private metadataOf;
+    private readAndCache;
+    private readMetadata;
+    /**
+     * The titles the SDK reports for the listed transcript (`customTitle` and
+     * `summary` of `getSessionInfo`). The SDK reads the first copy of the
+     * session that its search finds; its answer is used only when that copy is
+     * the listed file (same size and mtime), else the same titles are taken
+     * from the listed file itself (see {@link sdkTitles}).
+     */
+    private titlesOf;
+    /** Whether a successor of a continued transcript holds history: the SDK
+     *  list then hides the predecessor. */
+    private continuedElsewhere;
+    /** The first candidate that encodes to `dirName`, or, on macOS, that
+     *  encodes to a name the file system resolves to `dirName` (it differs in
+     *  case only). A directory name is never decoded. */
+    private recoverCwd;
+}
+//# sourceMappingURL=session-index.d.ts.map

package/dist/session-index/session-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-index.d.ts","sourceRoot":"","sources":["../../src/session-index/session-index.ts"],"names":[],"mappings":"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"}