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

package/dist/session-index/service.js

@@ -0,0 +1,546 @@
+/**
+ * The `sessionIndex` AIR extension: the session list, rename, archive and
+ * delete of a client that declared the capability.
+ *
+ * Wire contract: docs/air-extensions.md, "Session index". Everything here is
+ * reached only for a `sessionIndex` client, except the archive that an AIR
+ * client without the capability gets in place of a delete (see
+ * `ClaudeAcpAgent.deleteSession`).
+ */
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { RequestError, } from "@agentclientprotocol/sdk";
+import { deleteSession as sdkDeleteSession, getSessionInfo as sdkGetSessionInfo, } from "@anthropic-ai/claude-agent-sdk";
+import { airExtensionMeta } from "../air-extension.js";
+import { sanitizeTitle } from "../session-titles.js";
+import { effectiveTitle, isArchivedTitle, storedTitle, titleRecords, visibleTitle, } from "./archive-title.js";
+import { ListSubscriptions, } from "./list-subscriptions.js";
+import { LiveSessionRegistry } from "./live-registry.js";
+import { canonicalPath, errorCode, isExactProjectDir, isSessionId, projectDirMatches, sameProjectPath, } from "./project-dirs.js";
+import { readHeadTail, readHeadTailOf, sdkTitles, tailCustomTitle, transcriptAgentName, transcriptProjectCwd, } from "./transcript-scan.js";
+import { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, ARCHIVED_FILTERS, readSidecarTitle, SessionIndex, } from "./session-index.js";
+import { sessionInfoOf } from "./session-info.js";
+export const SESSION_RENAME_METHOD = "_session/rename";
+export const SESSION_ARCHIVE_METHOD = "_session/archive";
+export const SESSION_UNARCHIVE_METHOD = "_session/unarchive";
+/** The JSON-RPC code of an unknown session (ACP `ResourceNotFound`). */
+const RESOURCE_NOT_FOUND = -32002;
+/** The cursor format. A cursor of another version is rejected. */
+const CURSOR_VERSION = 5;
+export function sessionNotFound(sessionId) {
+    return new RequestError(RESOURCE_NOT_FOUND, `Session not found: ${sessionId}`, { sessionId });
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function parseSessionIdRequest(value) {
+    const sessionId = asRecord(value).sessionId;
+    if (typeof sessionId !== "string" || !sessionId.trim()) {
+        throw RequestError.invalidParams(undefined, "params require a non-empty sessionId");
+    }
+    return { sessionId: sessionId.trim() };
+}
+export function parseRenameSessionRequest(value) {
+    const { sessionId } = parseSessionIdRequest(value);
+    const raw = asRecord(value).title;
+    const title = typeof raw === "string" ? sanitizeTitle(raw) : "";
+    if (!title)
+        throw RequestError.invalidParams(undefined, "title must be a non-empty string");
+    return { sessionId, title };
+}
+function archivedFilter(list) {
+    // Omitted or null is `unarchived`.
+    const value = list.archived ?? "unarchived";
+    if (!ARCHIVED_FILTERS.includes(value)) {
+        throw RequestError.invalidParams({ archived: value }, '`_meta.jetbrains.air.list.archived` must be "unarchived", "archived" or "all"');
+    }
+    return value;
+}
+function optionalBoolean(list, key) {
+    // Omitted or null is false.
+    const value = list[key] ?? false;
+    if (typeof value !== "boolean") {
+        throw RequestError.invalidParams({ [key]: value }, `\`_meta.jetbrains.air.list.${key}\` must be a boolean`);
+    }
+    return value;
+}
+/** `_meta.jetbrains.air.list` of a list request. */
+export function parseListOptions(meta) {
+    const list = asRecord(airExtensionMeta(meta)?.list);
+    // Omitted or null is the default; an integer of at least 1 is clamped;
+    // anything else is invalid.
+    const raw = list.limit ?? DEFAULT_LIST_LIMIT;
+    if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1) {
+        throw RequestError.invalidParams({ limit: raw }, "`_meta.jetbrains.air.list.limit` must be an integer of at least 1");
+    }
+    return {
+        limit: Math.min(MAX_LIST_LIMIT, raw),
+        archived: archivedFilter(list),
+        includeWorktrees: optionalBoolean(list, "includeWorktrees"),
+    };
+}
+export function encodeListCursor(cursor, scope) {
+    const payload = {
+        v: CURSOR_VERSION,
+        u: cursor.orderAtMs,
+        id: cursor.sessionId,
+        cwd: scope.cwd,
+        archived: scope.archived,
+        worktrees: scope.includeWorktrees,
+    };
+    return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+/** The position a cursor names. A cursor of another cwd or filter, or one
+ *  this adapter did not issue, is rejected. */
+export function decodeListCursor(cursor, scope) {
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    }
+    catch {
+        payload = undefined;
+    }
+    if (!payload ||
+        payload.v !== CURSOR_VERSION ||
+        typeof payload.u !== "number" ||
+        typeof payload.id !== "string") {
+        throw RequestError.invalidParams(undefined, `Unknown session/list cursor: ${cursor}`);
+    }
+    if (payload.cwd !== scope.cwd ||
+        payload.archived !== scope.archived ||
+        payload.worktrees !== scope.includeWorktrees) {
+        throw RequestError.invalidParams(undefined, "The session/list cursor belongs to another cwd or filter");
+    }
+    return { orderAtMs: payload.u, sessionId: payload.id };
+}
+/** `<projectDir>/<sessionId>/custom-title.json` of a transcript. */
+function sidecarPath(transcriptPath) {
+    const sessionId = path.basename(transcriptPath, ".jsonl");
+    return path.join(path.dirname(transcriptPath), sessionId, "custom-title.json");
+}
+/** Writes `<projectDir>/<sessionId>/custom-title.json` the way the CLI's
+ *  `/rename` does: file 0600 in a 0700 directory, replaced atomically. The
+ *  temporary file has a random name of the CLI's `custom-title.json.tmp.*`
+ *  pattern, and only a temporary file this call created is removed. */
+export async function writeCustomTitleSidecar(transcriptPath, title) {
+    const target = sidecarPath(transcriptPath);
+    await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    const temporary = `${target}.tmp.${randomBytes(8).toString("hex")}`;
+    const handle = await fs.open(temporary, "wx", 0o600);
+    try {
+        try {
+            await handle.writeFile(JSON.stringify({ customTitle: title }));
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(temporary, target);
+    }
+    catch (error) {
+        await fs.rm(temporary, { force: true });
+        throw error;
+    }
+}
+/** The last two non-empty lines of a file, from its last 64 KB, and
+ *  whether the file ends with a newline. */
+async function lastLines(filePath) {
+    const handle = await fs.open(filePath, "r");
+    try {
+        const { size } = await handle.stat();
+        const length = Math.min(size, 64 * 1024);
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, size - length);
+        const text = buffer.toString("utf8");
+        const lines = text.split("\n").filter((line) => line.trim());
+        return {
+            lines: lines.slice(-2),
+            last: lines.at(-1) ?? "",
+            endsWithNewline: text.endsWith("\n"),
+        };
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Appends the title records of `title` (see archive-title.ts) to a
+ *  transcript whose last two records are not those already, whoever else
+ *  has the session open, as the CLI's `/rename` does. A torn last line is
+ *  closed first. */
+async function ensureTitleRecords(filePath, sessionId, title) {
+    const records = titleRecords(sessionId, title);
+    const { lines, last, endsWithNewline } = await lastLines(filePath);
+    if (lines.join("\n") + "\n" === records)
+        return;
+    const complete = endsWithNewline || last === "";
+    await fs.appendFile(filePath, `${complete ? "" : "\n"}${records}`);
+}
+/** Appends the `agent-name` record of `title` when the copy's agent name
+ *  is another one, so its archive state follows `title`. Reads and appends
+ *  through one handle. */
+async function ensureAgentName(filePath, sessionId, title) {
+    const handle = await fs.open(filePath, "a+");
+    try {
+        const { size } = await handle.stat();
+        const headTail = await readHeadTailOf(handle, size);
+        const agentName = transcriptAgentName(headTail);
+        if (agentName === undefined || agentName === title)
+            return;
+        const complete = size === 0 || headTail.tail.endsWith("\n");
+        const record = JSON.stringify({ type: "agent-name", agentName: title, sessionId });
+        await handle.appendFile(`${complete ? "" : "\n"}${record}\n`);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** The title of one transcript copy as the list reads it (see
+ *  {@link effectiveTitle}): its agent name, else the title the SDK reports.
+ *  It carries the archive prefix only when the copy is archived: a generated
+ *  title never archives a session. */
+async function copyTitle(filePath, sessionId) {
+    const { size } = await fs.stat(filePath);
+    const headTail = await readHeadTail(filePath, size);
+    const sidecar = tailCustomTitle(headTail.tail) === undefined
+        ? await readSidecarTitle(filePath, sessionId)
+        : undefined;
+    const { title, archived } = effectiveTitle(transcriptAgentName(headTail), sdkTitles(headTail, sidecar));
+    return title !== undefined && !archived && isArchivedTitle(title) ? visibleTitle(title) : title;
+}
+/** Rewrites the sidecar of a copy whose title is `current` when the
+ *  sidecar says the other archive state (a sidecar write that failed after
+ *  the records were appended). */
+async function alignSidecar(transcript, current, sessionId) {
+    if (current === undefined)
+        return;
+    const sidecar = await readSidecarTitle(transcript, sessionId);
+    if (sidecar === undefined || isArchivedTitle(sidecar) === isArchivedTitle(current))
+        return;
+    await writeCustomTitleSidecar(transcript, storedTitle(current, isArchivedTitle(current), sessionId));
+}
+/** `_session/rename`: the new title, with the archive prefix on a copy
+ *  that is archived, so a rename keeps the archive state. */
+export function renameTo(title) {
+    return (current, sessionId) => isArchivedTitle(current) ? storedTitle(title, true, sessionId) : title;
+}
+/** `_session/archive` and `_session/unarchive`: the current title with or
+ *  without the archive prefix; a copy already in that state is left alone. */
+export function archiveTo(archived) {
+    return (current, sessionId) => isArchivedTitle(current) === archived
+        ? undefined
+        : storedTitle(current ?? "", archived, sessionId);
+}
+/**
+ * Whether `transcript` lies in the project directory of one of `paths`, the
+ * one the CLI of that cwd writes: the exact encoding, or, for a long path
+ * whose name the CLI hashes differently, a directory with the cut prefix
+ * whose transcript belongs to the path. Another long path that shares the
+ * prefix does not count.
+ */
+async function isTranscriptOf(transcript, paths) {
+    const dirName = path.basename(path.dirname(transcript));
+    if (paths.some((cwd) => isExactProjectDir(dirName, cwd)))
+        return true;
+    if (!paths.some((cwd) => projectDirMatches(dirName, cwd)))
+        return false;
+    try {
+        const { size } = await fs.stat(transcript);
+        const cwd = transcriptProjectCwd(await readHeadTail(transcript, size));
+        return cwd !== undefined && paths.some((projectPath) => sameProjectPath(cwd, projectPath));
+    }
+    catch {
+        // Unreadable: not known to be the CLI's own copy.
+        return false;
+    }
+}
+function isSdkNotFound(error) {
+    return error instanceof Error && /^Session \S+ not found in /.test(error.message);
+}
+async function exists(target) {
+    try {
+        await fs.lstat(target);
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT" || errorCode(error) === "ENOTDIR")
+            return false;
+        throw error;
+    }
+}
+/** The error the SDK `deleteSession` gives for a session id it rejects or
+ *  does not find, which a client without `sessionIndex` got before. */
+function sdkDeleteError(sessionId) {
+    return new Error(isSessionId(sessionId)
+        ? `Session ${sessionId} not found in any project directory`
+        : `Invalid sessionId: ${sessionId}`);
+}
+/**
+ * `session/delete` of an AIR client without `sessionIndex`, which uses delete
+ * to mark a session done: archives it instead, so the transcript survives. A
+ * session without a transcript fails as the SDK delete did.
+ */
+export async function archiveInsteadOfDelete(sessionId, service) {
+    if (!isSessionId(sessionId))
+        throw sdkDeleteError(sessionId);
+    // The SDK delete skips empty transcripts, so they do not count.
+    const found = await service.index.findTranscripts(sessionId);
+    if (found.length === 0)
+        throw sdkDeleteError(sessionId);
+    await service.retitle(sessionId, archiveTo(true), { sidecar: "existing" });
+}
+export class SessionIndexService {
+    deps;
+    index;
+    registry;
+    subscriptions;
+    /** Set for good by {@link dispose}: no subscription is made after it. */
+    disposed = false;
+    /** The mutation in flight per session, which the next one waits for. */
+    mutations = new Map();
+    now;
+    deleteSession;
+    constructor(deps) {
+        this.deps = deps;
+        this.index = new SessionIndex(deps.getSessionInfo ?? sdkGetSessionInfo);
+        this.registry = deps.registry ?? new LiveSessionRegistry();
+        this.now = deps.now ?? Date.now;
+        this.deleteSession = deps.deleteSession ?? ((id) => sdkDeleteSession(id));
+    }
+    /** `session/list` of a `sessionIndex` client. `own` reports the sessions
+     *  that this connection runs. */
+    async list(params, own) {
+        const { limit, archived, includeWorktrees } = parseListOptions(params._meta);
+        const cwd = params.cwd ?? null;
+        const scope = { cwd, archived, includeWorktrees };
+        const after = params.cursor === null || params.cursor === undefined
+            ? undefined
+            : decodeListCursor(params.cursor, scope);
+        // The live registry is read while the transcripts are.
+        const livePromise = this.registry.snapshot();
+        const { rows, hasMore } = await this.index.list({
+            cwd,
+            includeWorktrees,
+            limit,
+            archived,
+            after,
+        });
+        const live = await livePromise;
+        const now = this.now();
+        const sessions = rows.map((row) => sessionInfoOf(row, own(row.sessionId), live.get(row.sessionId), now));
+        const last = rows[rows.length - 1];
+        return hasMore && last ? { sessions, nextCursor: encodeListCursor(last, scope) } : { sessions };
+    }
+    /** Runs `mutation` after the previous mutation of the session ended. */
+    exclusive(sessionId, mutation) {
+        const previous = this.mutations.get(sessionId) ?? Promise.resolve();
+        const next = previous.catch(() => undefined).then(mutation);
+        const settled = next.catch(() => undefined);
+        this.mutations.set(sessionId, settled);
+        void settled.then(() => {
+            if (this.mutations.get(sessionId) === settled)
+                this.mutations.delete(sessionId);
+        });
+        return next;
+    }
+    /**
+     * Retitles every transcript of a session with `change`: rename, archive
+     * and unarchive. Returns the title stored through the CLI that runs here,
+     * else the title of the first copy that got one; undefined when nothing
+     * was stored.
+     *
+     * - The CLI runs here (`live`): it titles its own transcript and sidecar
+     *   (`rename_session`), the only writer that cannot be overtaken by the
+     *   title the CLI holds. The other copies get the records and the sidecar
+     *   here, as a best effort once the CLI has the title: a failure is
+     *   logged, not returned.
+     * - Otherwise every transcript gets the records (and the sidecar, see
+     *   {@link RetitleOptions.sidecar}).
+     *
+     * As the CLI's `/rename`, the records are written whether or not another
+     * process has the session open.
+     *
+     * A session without a transcript is unknown (`-32002`), unless
+     * {@link RetitleOptions.mayBeUnwritten}.
+     */
+    async retitle(sessionId, change, options) {
+        const { live } = options;
+        if (!isSessionId(sessionId)) {
+            if (!live || !options.mayBeUnwritten)
+                throw sessionNotFound(sessionId);
+            return this.exclusive(sessionId, async () => {
+                const title = change(live.stored() ?? live.shown, sessionId);
+                if (title !== undefined) {
+                    await live.rename(title);
+                    live.remember(title);
+                }
+                return title;
+            });
+        }
+        return this.exclusive(sessionId, async () => {
+            const transcripts = await this.index.findTranscripts(sessionId);
+            if (transcripts.length === 0 && !options.mayBeUnwritten)
+                throw sessionNotFound(sessionId);
+            let stored;
+            // The cache is left as it is: the appended records change the size,
+            // and the next read keeps what the earlier scans found (a last prompt
+            // beyond the tail search).
+            if (live) {
+                const canonical = await canonicalPath(live.cwd);
+                const paths = [...new Set([live.cwd, canonical])];
+                const own = [];
+                for (const transcript of transcripts) {
+                    if (await isTranscriptOf(transcript, paths))
+                        own.push(transcript);
+                }
+                // The CLI writes the transcript of the resolved cwd.
+                const cli = own.find((transcript) => isExactProjectDir(path.basename(path.dirname(transcript)), canonical)) ?? own[0];
+                const others = transcripts.filter((transcript) => transcript !== cli);
+                // The transcript holds the current title, also one changed otherwise
+                // (a `/rename`); without one, the title last given to the CLI.
+                const primary = cli ?? others[0];
+                const read = primary ? await copyTitle(primary, sessionId) : undefined;
+                const current = read ?? live.stored() ?? live.shown;
+                stored = change(current, sessionId);
+                if (stored !== undefined) {
+                    await live.rename(stored);
+                    live.remember(stored);
+                    // The CLI writes the custom title before it answers, the agent name
+                    // only later. An older agent name decides the archive state first,
+                    // so the copy gets the new one now.
+                    // A best effort: the CLI took the title, and writes the agent name
+                    // itself too.
+                    if (cli) {
+                        try {
+                            await ensureAgentName(cli, sessionId, stored);
+                        }
+                        catch (error) {
+                            this.deps.logError(`writing the agent name of ${sessionId} failed`, error);
+                        }
+                    }
+                }
+                else if (cli) {
+                    await alignSidecar(cli, current, sessionId);
+                }
+                try {
+                    await this.titleCopies(sessionId, others, change, options.sidecar);
+                }
+                catch (error) {
+                    this.deps.logError(`titling the other transcripts of ${sessionId} failed`, error);
+                }
+            }
+            else {
+                stored = await this.titleCopies(sessionId, transcripts, change, options.sidecar);
+            }
+            return stored;
+        });
+    }
+    /** Appends the title records `change` gives each copy, then its sidecar.
+     *  A copy already in the requested state gets nothing, but its sidecar is
+     *  brought in line with it. Returns the title the first titled copy got. */
+    async titleCopies(sessionId, transcripts, change, sidecar) {
+        let first;
+        for (const transcript of transcripts) {
+            const current = await copyTitle(transcript, sessionId);
+            const title = change(current, sessionId);
+            if (title === undefined) {
+                await alignSidecar(transcript, current, sessionId);
+                continue;
+            }
+            await ensureTitleRecords(transcript, sessionId, title);
+            first ??= title;
+            if (sidecar === "always" || (await exists(sidecarPath(transcript)))) {
+                await writeCustomTitleSidecar(transcript, title);
+            }
+        }
+        return first;
+    }
+    /** Deletes every transcript of the session, whoever else has it open, as
+     *  the CLI does. `known`: the session was loaded here (and is torn down
+     *  already), so a missing transcript is no error.
+     *
+     *  The SDK deletes the first non-empty transcript it finds and its
+     *  `<sessionId>/` directory, one copy per call; empty transcripts, which it
+     *  skips, are removed here. */
+    async delete(sessionId, known) {
+        if (!isSessionId(sessionId))
+            throw sessionNotFound(sessionId);
+        await this.exclusive(sessionId, async () => {
+            // A session directory can outlive its transcript: a delete that removed
+            // the transcript and then failed on the directory.
+            const found = await this.index.scanSession(sessionId);
+            const all = found.transcripts.map(({ filePath }) => filePath);
+            if (all.length === 0 && found.sessionDirs.length === 0) {
+                // Unknown, unless it was loaded here.
+                if (known)
+                    return;
+                throw sessionNotFound(sessionId);
+            }
+            try {
+                // The SDK deletes one non-empty copy per call.
+                for (const { filePath } of found.transcripts.filter(({ size }) => size > 0)) {
+                    try {
+                        await this.deleteSession(sessionId);
+                    }
+                    catch (error) {
+                        // Only "not found" with that copy gone is a copy removed meanwhile.
+                        if (isSdkNotFound(error) && !(await exists(filePath)))
+                            continue;
+                        throw error;
+                    }
+                }
+                // Empty transcripts, which the SDK skips, and session directories
+                // without a transcript.
+                for (const { filePath, size } of found.transcripts) {
+                    if (size === 0)
+                        await fs.rm(filePath, { force: true });
+                }
+                for (const sessionDir of found.sessionDirs) {
+                    if (await exists(`${sessionDir}.jsonl`))
+                        continue;
+                    await fs.rm(sessionDir, { recursive: true, force: true });
+                }
+                const left = await this.index.scanSession(sessionId);
+                const remaining = [
+                    ...left.transcripts.map(({ filePath }) => filePath),
+                    ...left.sessionDirs,
+                ];
+                if (remaining.length > 0) {
+                    throw new Error(`Session ${sessionId} was not deleted: ${remaining.join(", ")} remain`);
+                }
+            }
+            finally {
+                this.index.invalidate(all);
+            }
+        });
+    }
+    /** `_session/list/subscribe`: pushes the changed rows of `cwd` (an
+     *  absolute path) until {@link unsubscribeList} or {@link dispose}. */
+    subscribeList(cwd) {
+        if (this.disposed) {
+            return Promise.reject(RequestError.internalError(undefined, "The connection is closed"));
+        }
+        this.subscriptions ??= new ListSubscriptions({
+            index: this.index,
+            registry: this.registry,
+            own: (sessionId) => this.deps.ownSessionState?.(sessionId),
+            notify: (changes) => this.deps.notifyListChanges?.(changes) ?? Promise.resolve(),
+            logError: this.deps.logError,
+        });
+        return this.subscriptions.subscribe(cwd);
+    }
+    /** `_session/list/unsubscribe`. Idempotent. */
+    unsubscribeList(subscriptionId) {
+        this.subscriptions?.unsubscribe(subscriptionId);
+    }
+    /** A session this connection runs changed what its row shows. */
+    ownSessionChanged(sessionId) {
+        this.subscriptions?.ownSessionChanged(sessionId);
+    }
+    dispose() {
+        this.disposed = true;
+        this.subscriptions?.dispose();
+        this.subscriptions = undefined;
+    }
+}