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

package/dist/session-index/connection.js

@@ -0,0 +1,310 @@
+/**
+ * The session index of one ACP connection: what `ClaudeAcpAgent` does for a
+ * client that declared `sessionIndex`, and the archive of an AIR client
+ * without it. The agent keeps thin call sites; everything else
+ * lives here.
+ *
+ * Wire contract: docs/air-extensions.md, "Session index".
+ */
+import { RequestError, } from "@agentclientprotocol/sdk";
+import { deleteSession as sdkDeleteSession } from "@anthropic-ai/claude-agent-sdk";
+import { AIR_SESSION_ARCHIVE_CAPABILITY, AIR_SESSION_INDEX_CAPABILITY, AIR_SESSION_LIST_SUBSCRIBE_CAPABILITY, AIR_SESSION_RENAME_CAPABILITY, clientSupportsAirCapability, withAirMeta, } from "../air-extension.js";
+import { isArchivedTitle, storedTitle, visibleTitle } from "./archive-title.js";
+import { LIST_CHANGES_METHOD, LIST_SUBSCRIBE_METHOD, LIST_UNSUBSCRIBE_METHOD, parseListSubscribeRequest, parseListUnsubscribeRequest, } from "./list-subscriptions.js";
+import { archiveInsteadOfDelete, archiveTo, renameTo, parseRenameSessionRequest, parseSessionIdRequest, SESSION_ARCHIVE_METHOD, SESSION_RENAME_METHOD, SESSION_UNARCHIVE_METHOD, SessionIndexService, } from "./service.js";
+/** Records the end of a turn at `session_state_changed`. */
+export function noteSessionState(session, previous, state) {
+    if (state === "idle" && previous !== "idle")
+        session.lastTurnEndedAt = Date.now();
+    if (state === "running" && previous !== "running")
+        session.lastTurnFailed = false;
+}
+export class SessionIndexConnection {
+    host;
+    /**
+     * The session index of a client that declared `sessionIndex`. Undefined for
+     * every other client, which keeps the session list, delete and the watchers
+     * exactly as before.
+     */
+    service;
+    /** The archive behind `session/delete` of an AIR client without
+     *  `sessionIndex`: the same writes, without a list or a watcher. */
+    archiver;
+    /** When the query of a session failed here, by session id. */
+    failedQueries = new Map();
+    constructor(host) {
+        this.host = host;
+    }
+    /** Sets the index up for the client of `initialize`. ACP v2 does not route
+     *  the session index methods yet. */
+    negotiate(request, options) {
+        this.service?.dispose();
+        this.service = undefined;
+        if (!options.v2 &&
+            this.host.isAirClient() &&
+            clientSupportsAirCapability(request.clientCapabilities, AIR_SESSION_INDEX_CAPABILITY)) {
+            this.service = new SessionIndexService({
+                ownSessionState: (sessionId) => this.ownSessionState(sessionId),
+                notifyListChanges: (changes) => this.host.agent.client.extNotification(LIST_CHANGES_METHOD, changes),
+                logError: (message, error) => this.host.agent.logger.error(`[session-index] ${message}:`, error),
+            });
+        }
+    }
+    /** A stored title as the client shows it: an AIR client gets the title
+     *  of an archived session without the archive prefix, as in its list;
+     *  every other client the title as stored. */
+    clientTitle(title) {
+        return this.host.isAirClient() && isArchivedTitle(title) ? visibleTitle(title) : title;
+    }
+    /** The AIR capabilities the agent advertises for the index: the index
+     *  itself, archive, rename and the list subscription, all only to a client
+     *  that declared `sessionIndex`. */
+    capabilities() {
+        return this.service
+            ? [
+                AIR_SESSION_INDEX_CAPABILITY,
+                AIR_SESSION_ARCHIVE_CAPABILITY,
+                AIR_SESSION_RENAME_CAPABILITY,
+                AIR_SESSION_LIST_SUBSCRIBE_CAPABILITY,
+            ]
+            : [];
+    }
+    dispose() {
+        this.service?.dispose();
+    }
+    /** The query of a session that ran here failed (not a cancel): its row
+     *  shows `error` until its transcript changes. */
+    onQueryFailed(sessionId) {
+        this.failedQueries.set(sessionId, Date.now());
+        if (this.failedQueries.size > 1024) {
+            this.failedQueries.delete(this.failedQueries.keys().next().value);
+        }
+        this.service?.ownSessionChanged(sessionId);
+    }
+    /** A turn of a session started here: an earlier failed query of it no
+     *  longer counts. */
+    onTurnStarted(sessionId) {
+        this.failedQueries.delete(sessionId);
+    }
+    onTeardown(sessionId) {
+        // Its row now shows what the registry and the transcript tell.
+        this.service?.ownSessionChanged(sessionId);
+    }
+    /** A session this connection runs changed its state, turn end or cost:
+     *  the list subscriptions send it at once. */
+    onOwnSessionChanged(sessionId) {
+        this.service?.ownSessionChanged(sessionId);
+    }
+    /** `_session/list/subscribe`. */
+    subscribeList(params) {
+        return this.requireService(LIST_SUBSCRIBE_METHOD).subscribeList(params.cwd);
+    }
+    /** `_session/list/unsubscribe`. Idempotent. */
+    unsubscribeList(params) {
+        this.requireService(LIST_UNSUBSCRIBE_METHOD).unsubscribeList(params.subscriptionId);
+        return {};
+    }
+    /** `session/list` of a `sessionIndex` client; undefined for another one. */
+    list(params) {
+        return this.service?.list(params, (sessionId) => this.ownSessionState(sessionId));
+    }
+    /** An AIR client archives with session/delete (see {@link deleteSession}):
+     *  its archived sessions (an archived custom title) stay hidden from the
+     *  old list, as when the delete removed them. */
+    hideArchived(sessions) {
+        if (!this.host.isAirClient())
+            return sessions;
+        return sessions.filter((session) => !isArchivedTitle(session.customTitle));
+    }
+    /** `_session/rename`: names a session; no generated title replaces it.
+     *  An archived session stays archived. */
+    async rename(request) {
+        const index = this.requireService(SESSION_RENAME_METHOD);
+        const { sessionId } = request;
+        // As the CLI keeps it, and never with the archive prefix: a rename does
+        // not change the archive state.
+        const title = storedTitle(request.title, false, sessionId);
+        // The title as stored: an archived one is cut with its prefix.
+        const shown = (stored) => stored === undefined ? title : visibleTitle(stored);
+        await this.retitle(index, sessionId, renameTo(title), shown, {
+            mayBeUnwritten: true,
+            sidecar: "always",
+        });
+        return {};
+    }
+    /** `_session/archive`: hides a session from the default list and stops
+     *  it. Idempotent; the session need not be loaded. A session loaded here
+     *  is interrupted, retitled through its CLI while that still runs, then
+     *  closed as `session/close` closes it. */
+    async archive(params) {
+        const index = this.requireService(SESSION_ARCHIVE_METHOD);
+        const { sessionId } = params;
+        const loaded = this.host.agent.sessions[sessionId] !== undefined;
+        // No turn goes on after the archive: the interrupt goes to the CLI ahead
+        // of the rename.
+        if (loaded)
+            await this.host.interruptSession(sessionId);
+        await this.retitle(index, sessionId, archiveTo(true), undefined, {
+            mayBeUnwritten: this.isUnwrittenSession(sessionId),
+            sidecar: "existing",
+        });
+        if (loaded) {
+            await this.host.teardownSession(sessionId);
+            // The closed CLI may have lost or overwritten the agent name it was
+            // still to write: the transcripts are archived without it once more,
+            // as a best effort, since the CLI took the archived title.
+            try {
+                await index.retitle(sessionId, archiveTo(true), {
+                    mayBeUnwritten: true,
+                    sidecar: "existing",
+                });
+            }
+            catch (error) {
+                this.host.agent.logger.error(`[session-index] archiving ${sessionId} after its close failed:`, error);
+            }
+        }
+        await this.reportArchived(sessionId, true, loaded);
+        return {};
+    }
+    /** `_session/unarchive`. Idempotent; it does not load the session. */
+    async unarchive(params) {
+        const index = this.requireService(SESSION_UNARCHIVE_METHOD);
+        const { sessionId } = params;
+        await this.retitle(index, sessionId, archiveTo(false), undefined, {
+            mayBeUnwritten: this.isUnwrittenSession(sessionId),
+            sidecar: "existing",
+        });
+        await this.reportArchived(sessionId, false, this.host.agent.sessions[sessionId] !== undefined);
+        return {};
+    }
+    /**
+     * Retitles a session (see {@link SessionIndexService.retitle}). A session
+     * this connection runs is titled through its CLI (`rename_session`). A
+     * loaded session's title state takes the change as a client title, so no
+     * generated title replaces it; `publish` is the title it then publishes.
+     */
+    async retitle(index, sessionId, change, publish, options) {
+        const session = this.host.agent.sessions[sessionId];
+        // Decided once a title generation in flight has ended: the query may
+        // have closed meanwhile.
+        const persist = () => {
+            const query = session?.query;
+            // A closed session's CLI is gone here: only a running query titles it.
+            const running = session !== undefined && !session.queryClosed;
+            if (running && typeof query?.renameSession !== "function") {
+                // Its CLI holds the title and would write it back over ours.
+                throw RequestError.invalidRequest({ sessionId }, "The Claude Code CLI of this session cannot change its title while it runs.");
+            }
+            const live = running
+                ? {
+                    cwd: session.cwd,
+                    rename: (title) => query.renameSession(title, sessionId),
+                    stored: () => session.titles.storedTitle,
+                    remember: (title) => session.titles.rememberStoredTitle(title),
+                    shown: session.titles.shownTitle,
+                }
+                : undefined;
+            return index.retitle(sessionId, change, {
+                ...options,
+                // Without its CLI, a session needs its transcript.
+                mayBeUnwritten: live !== undefined && options.mayBeUnwritten,
+                live,
+            });
+        };
+        if (session) {
+            await session.titles.setExplicitTitle(publish, persist);
+        }
+        else {
+            await persist();
+        }
+    }
+    /**
+     * `session/delete`:
+     * - A `sessionIndex` client deletes for real: every transcript, whoever
+     *   else has the session open, as the CLI does.
+     * - Another AIR client uses delete to mark a session done, and may reopen
+     *   it later: the adapter archives it instead (as `_session/archive` does,
+     *   after the CLI closed), so the transcript survives.
+     * - Every other client: the SDK delete, as before.
+     */
+    async deleteSession(params) {
+        const loaded = this.host.agent.sessions[params.sessionId] !== undefined;
+        // Tear down any active in-memory state first so the on-disk file isn't
+        // recreated by an outstanding query writing to it.
+        if (loaded) {
+            await this.host.teardownSession(params.sessionId);
+        }
+        if (this.service) {
+            await this.service.delete(params.sessionId, loaded);
+        }
+        else if (this.host.isAirClient()) {
+            await archiveInsteadOfDelete(params.sessionId, this.airArchiver());
+        }
+        else {
+            await sdkDeleteSession(params.sessionId);
+        }
+        return {};
+    }
+    airArchiver() {
+        this.archiver ??= new SessionIndexService({
+            logError: (message, error) => this.host.agent.logger.error(`[session-index] ${message}:`, error),
+        });
+        return this.archiver;
+    }
+    requireService(method) {
+        if (!this.service)
+            throw RequestError.methodNotFound(method);
+        return this.service;
+    }
+    /** What the session index reports for a session this connection runs. */
+    ownSessionState(sessionId) {
+        const session = this.host.agent.sessions[sessionId];
+        if (!session || session.queryClosed) {
+            const failedAt = this.failedQueries.get(sessionId);
+            return failedAt === undefined ? undefined : { queryFailedAt: failedAt };
+        }
+        return {
+            state: session.lastSessionState,
+            lastTurnEndedAt: session.lastTurnEndedAt,
+            // A session loaded again after its query failed here shows the failure
+            // until a turn of it starts.
+            lastTurnFailed: session.lastTurnFailed || this.failedQueries.has(sessionId),
+            costUsd: session.lastTotalCostUsd,
+        };
+    }
+    /** A new session this connection runs that may have no transcript yet: it
+     *  resumed no stored conversation and no turn of it has ended. A session
+     *  whose query ended, or that has history, needs its transcript. */
+    isUnwrittenSession(sessionId) {
+        const session = this.host.agent.sessions[sessionId];
+        return (session !== undefined &&
+            !session.queryClosed &&
+            !session.resumedFromHistory &&
+            session.lastTurnEndedAt === undefined);
+    }
+    /** Tells the client the archive state of a session that was loaded on
+     *  this connection (`session_info_update` with
+     *  `_meta.jetbrains.air.archived`, RFD #2161's `archived` field), also
+     *  once the archive closed it. */
+    async reportArchived(sessionId, archived, loaded) {
+        if (!loaded)
+            return;
+        await this.host.agent.client.sessionUpdate({
+            sessionId,
+            update: {
+                sessionUpdate: "session_info_update",
+                _meta: withAirMeta(undefined, "archived", archived),
+            },
+        });
+    }
+}
+/** Routes `_session/list/subscribe`, `_session/list/unsubscribe`,
+ *  `_session/rename`, `_session/archive` and `_session/unarchive`. */
+export function onSessionIndexRequests(app, agent) {
+    return app
+        .onRequest(LIST_SUBSCRIBE_METHOD, { parse: parseListSubscribeRequest }, (ctx) => agent().subscribeSessionList(ctx.params))
+        .onRequest(LIST_UNSUBSCRIBE_METHOD, { parse: parseListUnsubscribeRequest }, (ctx) => agent().unsubscribeSessionList(ctx.params))
+        .onRequest(SESSION_RENAME_METHOD, { parse: parseRenameSessionRequest }, (ctx) => agent().renameSessionTitle(ctx.params))
+        .onRequest(SESSION_ARCHIVE_METHOD, { parse: parseSessionIdRequest }, (ctx) => agent().archiveSession(ctx.params))
+        .onRequest(SESSION_UNARCHIVE_METHOD, { parse: parseSessionIdRequest }, (ctx) => agent().unarchiveSession(ctx.params));
+}

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

@@ -0,0 +1,30 @@
+/**
+ * File system reads of the session index that stay cheap with thousands of
+ * transcripts: bounded batches of stats, and directory listings that are
+ * read again only when the directory changed.
+ */
+import * as fs from "node:fs";
+/**
+ * The stats of `filePaths` (undefined for one that is gone). A project
+ * directory holds thousands of transcripts: the callback API costs about
+ * half of one promise per file, and a bounded number in flight, shared by
+ * all callers, keeps each turn of the event loop short (dispatching
+ * thousands at once holds it for 100 ms and more). Unlike synchronous
+ * stats, a file system stall never holds the event loop.
+ */
+export declare function statFiles(filePaths: readonly string[]): Promise<(fs.Stats | undefined)[]>;
+/**
+ * Directory listings, read again only when the directory's mtime changed
+ * (an entry was added, removed or renamed; an append to a file does not
+ * change it). A project directory with thousands of transcripts is then one
+ * stat instead of one `readdir` per list or mutation.
+ */
+export declare class DirListings {
+    private readonly listings;
+    /** The entry names of `dir`, empty when it cannot be read. */
+    names(dir: string): Promise<string[]>;
+    /** The entry names of each of `dirs`, one bounded batch of stats. */
+    namesOfAll(dirs: readonly string[]): Promise<string[][]>;
+    private listing;
+}
+//# sourceMappingURL=dir-listing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dir-listing.d.ts","sourceRoot":"","sources":["../../src/session-index/dir-listing.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAkC9B;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,KAAK,GAAG,SAAS,CAAC,EAAE,CAAC,CAYzF;AAgBD;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IAEvD,8DAA8D;IACxD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAI3C,qEAAqE;IAC/D,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAKhD,OAAO;CAyBtB"}

package/dist/session-index/dir-listing.js

@@ -0,0 +1,110 @@
+/**
+ * File system reads of the session index that stay cheap with thousands of
+ * transcripts: bounded batches of stats, and directory listings that are
+ * read again only when the directory changed.
+ */
+import * as fs from "node:fs";
+/** Stats in flight at once, across all callers of {@link statFiles}. */
+const STAT_CONCURRENCY = 512;
+let statsInFlight = 0;
+/** Queued stats, a FIFO read from `waitingHead` (no `shift()`: the queue
+ *  can hold tens of thousands). */
+let waitingStats = [];
+let waitingHead = 0;
+function nextWaitingStat() {
+    if (waitingHead >= waitingStats.length)
+        return undefined;
+    const next = waitingStats[waitingHead++];
+    if (waitingHead > 1024 && waitingHead * 2 > waitingStats.length) {
+        waitingStats = waitingStats.slice(waitingHead);
+        waitingHead = 0;
+    }
+    return next;
+}
+/** Runs `stat` once fewer than {@link STAT_CONCURRENCY} are in flight. */
+function statBounded(filePath, done) {
+    const run = () => {
+        statsInFlight++;
+        fs.stat(filePath, (error, stats) => {
+            statsInFlight--;
+            nextWaitingStat()?.();
+            done(error ? undefined : stats);
+        });
+    };
+    if (statsInFlight < STAT_CONCURRENCY)
+        run();
+    else
+        waitingStats.push(run);
+}
+/**
+ * The stats of `filePaths` (undefined for one that is gone). A project
+ * directory holds thousands of transcripts: the callback API costs about
+ * half of one promise per file, and a bounded number in flight, shared by
+ * all callers, keeps each turn of the event loop short (dispatching
+ * thousands at once holds it for 100 ms and more). Unlike synchronous
+ * stats, a file system stall never holds the event loop.
+ */
+export function statFiles(filePaths) {
+    const result = new Array(filePaths.length);
+    if (filePaths.length === 0)
+        return Promise.resolve(result);
+    return new Promise((resolve) => {
+        let left = filePaths.length;
+        filePaths.forEach((filePath, i) => {
+            statBounded(filePath, (stats) => {
+                result[i] = stats;
+                if (--left === 0)
+                    resolve(result);
+            });
+        });
+    });
+}
+/** A listing read this soon after the directory changed is not trusted:
+ *  some file systems keep the mtime in whole seconds, so another change in
+ *  the same second would leave it unchanged. */
+const MTIME_RESOLUTION_MS = 2000;
+/**
+ * Directory listings, read again only when the directory's mtime changed
+ * (an entry was added, removed or renamed; an append to a file does not
+ * change it). A project directory with thousands of transcripts is then one
+ * stat instead of one `readdir` per list or mutation.
+ */
+export class DirListings {
+    listings = new Map();
+    /** The entry names of `dir`, empty when it cannot be read. */
+    async names(dir) {
+        return (await this.listing(dir, await statOrUndefined(dir))).names;
+    }
+    /** The entry names of each of `dirs`, one bounded batch of stats. */
+    async namesOfAll(dirs) {
+        const stats = await statFiles(dirs);
+        return Promise.all(dirs.map(async (dir, i) => (await this.listing(dir, stats[i])).names));
+    }
+    async listing(dir, stats) {
+        if (!stats?.isDirectory()) {
+            this.listings.delete(dir);
+            return { mtimeMs: 0, ino: 0, readAt: 0, names: [] };
+        }
+        const cached = this.listings.get(dir);
+        if (cached &&
+            cached.mtimeMs === stats.mtimeMs &&
+            cached.ino === stats.ino &&
+            cached.readAt - cached.mtimeMs > MTIME_RESOLUTION_MS) {
+            return cached;
+        }
+        const readAt = Date.now();
+        let names;
+        try {
+            names = await fs.promises.readdir(dir);
+        }
+        catch {
+            return { mtimeMs: 0, ino: 0, readAt, names: [] };
+        }
+        const listing = { mtimeMs: stats.mtimeMs, ino: stats.ino, readAt, names };
+        this.listings.set(dir, listing);
+        return listing;
+    }
+}
+function statOrUndefined(target) {
+    return fs.promises.stat(target).then((stats) => stats, () => undefined);
+}

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

@@ -0,0 +1,34 @@
+/**
+ * The client-set title of a session (`_session/rename`), as `SessionTitles`
+ * guards it against generated titles: once a client named the session, or
+ * while a rename is in flight, no generated title is adopted, and a rename
+ * waits for a generation in flight, whose persisted title would otherwise
+ * land after it.
+ */
+export declare class ExplicitTitle {
+    /** Set once a client named the session. Released by {@link reset}. */
+    private named;
+    /** Renames in flight. */
+    private pending;
+    /** Renames started so far, to tell that one ran between two reads. */
+    private started;
+    /** The title generation in flight. */
+    private generation?;
+    /** Whether a generated title must not be adopted. */
+    get active(): boolean;
+    /** Whether a client named the session and no rename is in flight: a title
+     *  stored since by someone else (a `/rename`) may still be adopted. */
+    get settledByClient(): boolean;
+    /** Changes with every rename that starts. */
+    get renames(): number;
+    reset(): void;
+    /** Tracks a title generation until it ends. */
+    track(generation: Promise<void>): void;
+    /** Persists a client title after the generation in flight. `persist`
+     *  tells whether the session is named now. When it fails or names nothing
+     *  (an archive of an archived session), and no other rename named the
+     *  session, `restore` puts the title state back, so a later turn may still
+     *  generate a title. */
+    apply(persist: () => Promise<boolean>, restore: () => void): Promise<void>;
+}
+//# sourceMappingURL=explicit-title.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"explicit-title.d.ts","sourceRoot":"","sources":["../../src/session-index/explicit-title.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qBAAa,aAAa;IACxB,sEAAsE;IACtE,OAAO,CAAC,KAAK,CAAS;IACtB,yBAAyB;IACzB,OAAO,CAAC,OAAO,CAAK;IACpB,sEAAsE;IACtE,OAAO,CAAC,OAAO,CAAK;IACpB,sCAAsC;IACtC,OAAO,CAAC,UAAU,CAAC,CAAgB;IAEnC,qDAAqD;IACrD,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;2EACuE;IACvE,IAAI,eAAe,IAAI,OAAO,CAE7B;IAED,6CAA6C;IAC7C,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,KAAK,IAAI,IAAI;IAIb,+CAA+C;IAC/C,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAOtC;;;;4BAIwB;IAClB,KAAK,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAcjF"}

package/dist/session-index/explicit-title.js

@@ -0,0 +1,65 @@
+/**
+ * The client-set title of a session (`_session/rename`), as `SessionTitles`
+ * guards it against generated titles: once a client named the session, or
+ * while a rename is in flight, no generated title is adopted, and a rename
+ * waits for a generation in flight, whose persisted title would otherwise
+ * land after it.
+ */
+export class ExplicitTitle {
+    /** Set once a client named the session. Released by {@link reset}. */
+    named = false;
+    /** Renames in flight. */
+    pending = 0;
+    /** Renames started so far, to tell that one ran between two reads. */
+    started = 0;
+    /** The title generation in flight. */
+    generation;
+    /** Whether a generated title must not be adopted. */
+    get active() {
+        return this.named || this.pending > 0;
+    }
+    /** Whether a client named the session and no rename is in flight: a title
+     *  stored since by someone else (a `/rename`) may still be adopted. */
+    get settledByClient() {
+        return this.named && this.pending === 0;
+    }
+    /** Changes with every rename that starts. */
+    get renames() {
+        return this.started;
+    }
+    reset() {
+        this.named = false;
+    }
+    /** Tracks a title generation until it ends. */
+    track(generation) {
+        this.generation = generation;
+        void generation.finally(() => {
+            if (this.generation === generation)
+                this.generation = undefined;
+        });
+    }
+    /** Persists a client title after the generation in flight. `persist`
+     *  tells whether the session is named now. When it fails or names nothing
+     *  (an archive of an archived session), and no other rename named the
+     *  session, `restore` puts the title state back, so a later turn may still
+     *  generate a title. */
+    async apply(persist, restore) {
+        this.pending++;
+        this.started++;
+        try {
+            await this.generation;
+            if (await persist())
+                this.named = true;
+            else if (!this.named && this.pending === 1)
+                restore();
+        }
+        catch (error) {
+            if (!this.named && this.pending === 1)
+                restore();
+            throw error;
+        }
+        finally {
+            this.pending--;
+        }
+    }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * The first prompt of a transcript, extracted the way the SDK does for a
+ * session title (its `rf`, `ti` and `jP` in `@anthropic-ai/claude-agent-sdk`).
+ * Used when the SDK `getSessionInfo` read another copy of the session.
+ *
+ * - Only main-chain user records count: no tool result, meta or compact
+ *   summary record.
+ * - Each text (the string content, or every text block) is expanded from its
+ *   `<pasted_content>` blocks and flattened to one line.
+ * - A slash command (`<command-name>/init</command-name>`) is only a fallback
+ *   while a real prompt may follow; `<bash-input>x</bash-input>` is `! x`;
+ *   a text that starts with another tag or with an interrupt marker is
+ *   skipped.
+ * - A prompt longer than 200 characters is cut and gets an ellipsis.
+ * - Without any text, an image or a document prompt is `Image` or `Document`.
+ */
+type Entry = Record<string, unknown>;
+/**
+ * The prompt of one user record, or undefined when it has none. A slash
+ * command is recorded in `state.commandFallback` instead.
+ */
+export declare function promptOf(entry: Entry, state: {
+    commandFallback: string;
+}): string | undefined;
+/**
+ * Whether a user record is a prompt the user sent: one with prompt text
+ * ({@link promptOf}), or one with an image or a document, which the SDK
+ * titles `Image` or `Document` when it has no prompt text. A tool result, a meta or compact summary
+ * record, an interrupt and a slash command are none.
+ */
+export declare function isUserPrompt(entry: Entry): boolean;
+/** The first prompt of the head, else the first slash command, else "". */
+export declare function firstPrompt(head: string): string;
+/** `Image` or `Document` for a first user record that holds one, else "". */
+export declare function mediaPrompt(head: string): string;
+export {};
+//# sourceMappingURL=first-prompt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"first-prompt.d.ts","sourceRoot":"","sources":["../../src/session-index/first-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH,KAAK,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AA+CrC;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CAgC7F;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAelD;AAMD,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBhD;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWhD"}