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

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

@@ -0,0 +1,72 @@
+/**
+ * The live Claude Code processes on this machine, from the CLI's registry.
+ *
+ * Each running CLI writes `<config>/sessions/<pid>.json` with its session id,
+ * kind, entrypoint and status. The format is not documented; the reader keeps
+ * to the fields it needs and applies the liveness rules of Claude Desktop:
+ *
+ * - only `<pid>.json` files are read; `.key` files and other names are never
+ *   opened, and no file is ever written or deleted;
+ * - a record whose JSON does not parse is read once more, then skipped;
+ * - a record of another pid domain (another machine or pid namespace) is
+ *   skipped;
+ * - the process must be alive: `kill(pid, 0)` succeeds or fails with `EPERM`;
+ * - a recorded `procStart` must match the start time of the live process,
+ *   so a reused pid does not count;
+ * - a record older than 24 hours counts only when its `procStart` matches.
+ *
+ * A snapshot is cached for {@link SNAPSHOT_TTL_MS}. The records tell only the
+ * `state` of a session list row; no operation is refused for them.
+ */
+export type LiveRecord = {
+    pid: number;
+    sessionId: string;
+    cwd?: string;
+    kind?: string;
+    entrypoint?: string;
+    status?: string;
+    statusUpdatedAt?: number;
+};
+export type LiveSnapshot = ReadonlyMap<string, LiveRecord>;
+export type LiveRegistryDeps = {
+    /** The registry directory. Defaults to `<config>/sessions`. */
+    dir?: () => string;
+    now?: () => number;
+    /** Whether the process is alive. Defaults to `kill(pid, 0)`. */
+    isAlive?: (pid: number) => boolean;
+    /** The `ps -o lstart=` start time of each live pid. */
+    processStarts?: (pids: number[]) => Promise<Map<number, string>>;
+    /** This machine's pid domain, as the CLI computes it. */
+    pidDomain?: () => Promise<string>;
+};
+/** `<config>/sessions`, where each CLI process registers itself. */
+export declare function liveRegistryDir(): string;
+export declare class LiveSessionRegistry {
+    private cached?;
+    private readonly dir;
+    private readonly now;
+    private readonly isAlive;
+    private readonly processStarts;
+    private readonly pidDomain;
+    /** The start times `ps` gave, by pid, and when. */
+    private readonly starts;
+    constructor(deps?: LiveRegistryDeps);
+    /** The live records by session id. Cached for 5 s. */
+    snapshot(): Promise<LiveSnapshot>;
+    /** Every live record, several per session when several processes hold it. */
+    private read;
+    /**
+     * The live record of each of the registry files `names`, by name:
+     * undefined for a file that is gone or holds no live record. A name that
+     * is not `<pid>.json` (a `.key` file, a temporary file) is never opened and
+     * not in the result. The rules of {@link read} apply. `recentStarts` takes
+     * a start time that `ps` gave in the last 10 s when it matches the record,
+     * so a record that changes often does not run `ps` each time.
+     */
+    readFiles(names: readonly string[], options?: {
+        recentStarts?: boolean;
+    }): Promise<Map<string, LiveRecord | undefined>>;
+}
+/** One record per session: the one with the newest status. */
+export declare function bySession(records: Iterable<LiveRecord>): LiveSnapshot;
+//# sourceMappingURL=live-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"live-registry.d.ts","sourceRoot":"","sources":["../../src/session-index/live-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAiBH,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAE3D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gEAAgE;IAChE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,uDAAuD;IACvD,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACnC,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAwFD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAC,CAAkD;IACjE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmD;IACjF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAClD,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoD;gBAE/D,IAAI,GAAE,gBAAqB;IAQvC,sDAAsD;IACtD,QAAQ,IAAI,OAAO,CAAC,YAAY,CAAC;IAYjC,6EAA6E;YAC/D,IAAI;IAYlB;;;;;;;OAOG;IACG,SAAS,CACb,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAO,GACvC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC;CAqEhD;AAED,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,YAAY,CASrE"}

package/dist/session-index/live-registry.js

@@ -0,0 +1,240 @@
+/**
+ * The live Claude Code processes on this machine, from the CLI's registry.
+ *
+ * Each running CLI writes `<config>/sessions/<pid>.json` with its session id,
+ * kind, entrypoint and status. The format is not documented; the reader keeps
+ * to the fields it needs and applies the liveness rules of Claude Desktop:
+ *
+ * - only `<pid>.json` files are read; `.key` files and other names are never
+ *   opened, and no file is ever written or deleted;
+ * - a record whose JSON does not parse is read once more, then skipped;
+ * - a record of another pid domain (another machine or pid namespace) is
+ *   skipped;
+ * - the process must be alive: `kill(pid, 0)` succeeds or fails with `EPERM`;
+ * - a recorded `procStart` must match the start time of the live process,
+ *   so a reused pid does not count;
+ * - a record older than 24 hours counts only when its `procStart` matches.
+ *
+ * A snapshot is cached for {@link SNAPSHOT_TTL_MS}. The records tell only the
+ * `state` of a session list row; no operation is refused for them.
+ */
+import { execFile } from "node:child_process";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { claudeConfigDir } from "../paths.js";
+import { errorCode } from "./project-dirs.js";
+const SNAPSHOT_TTL_MS = 5_000;
+const STALE_RECORD_MS = 24 * 60 * 60 * 1000;
+const PS_TIMEOUT_MS = 1_000;
+const RECORD_FILE_PATTERN = /^(\d+)\.json$/;
+/** How long a process start time read with `ps` serves a reader that asks
+ *  for recent ones (see {@link LiveSessionRegistry.readFiles}). */
+const RECENT_START_MS = 10_000;
+/** `<config>/sessions`, where each CLI process registers itself. */
+export function liveRegistryDir() {
+    return path.join(claudeConfigDir(), "sessions");
+}
+function defaultIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return errorCode(error) === "EPERM";
+    }
+}
+/** The start times of `pids`, from one `ps` call, in the format the CLI
+ *  records (`LC_ALL=C TZ=UTC ps -o lstart=`). */
+function defaultProcessStarts(pids) {
+    const result = new Map();
+    if (pids.length === 0 || process.platform === "win32")
+        return Promise.resolve(result);
+    return new Promise((resolve) => {
+        execFile("ps", ["-o", "pid=,lstart=", "-p", pids.join(",")], { timeout: PS_TIMEOUT_MS, env: { ...process.env, LC_ALL: "C", TZ: "UTC" } }, (_error, stdout) => {
+            // `ps` exits 1 when one of the pids is gone; its output still holds
+            // the live ones.
+            for (const line of String(stdout ?? "").split("\n")) {
+                const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(line);
+                if (match)
+                    result.set(Number(match[1]), normalizeStart(match[2]));
+            }
+            resolve(result);
+        });
+    });
+}
+function normalizeStart(value) {
+    return value.trim().replace(/\s+/g, " ");
+}
+let cachedPidDomain;
+/** The pid domain the CLI records: the platform on macOS, the machine id and
+ *  pid namespace on Linux, the host name on Windows. */
+function defaultPidDomain() {
+    cachedPidDomain ??= (async () => {
+        if (process.platform === "win32")
+            return `win32:${os.hostname().toLowerCase()}`;
+        if (process.platform !== "linux")
+            return process.platform;
+        const [machineId, pidNamespace] = await Promise.all([
+            fs.readFile("/etc/machine-id", "utf8").then((value) => value.trim(), () => ""),
+            fs.readlink("/proc/self/ns/pid").catch(() => ""),
+        ]);
+        return `linux:${machineId}:${pidNamespace}`;
+    })();
+    return cachedPidDomain;
+}
+async function readRecord(file) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        let text;
+        try {
+            text = await fs.readFile(file, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+        try {
+            const value = JSON.parse(text);
+            return value && typeof value === "object" && !Array.isArray(value)
+                ? value
+                : undefined;
+        }
+        catch {
+            // The CLI may be rewriting the file; read it once more.
+        }
+    }
+    return undefined;
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function optionalString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+export class LiveSessionRegistry {
+    cached;
+    dir;
+    now;
+    isAlive;
+    processStarts;
+    pidDomain;
+    /** The start times `ps` gave, by pid, and when. */
+    starts = new Map();
+    constructor(deps = {}) {
+        this.dir = deps.dir ?? liveRegistryDir;
+        this.now = deps.now ?? Date.now;
+        this.isAlive = deps.isAlive ?? defaultIsAlive;
+        this.processStarts = deps.processStarts ?? defaultProcessStarts;
+        this.pidDomain = deps.pidDomain ?? defaultPidDomain;
+    }
+    /** The live records by session id. Cached for 5 s. */
+    snapshot() {
+        const now = this.now();
+        if (this.cached && now - this.cached.at < SNAPSHOT_TTL_MS) {
+            return this.cached.snapshot;
+        }
+        const snapshot = this.read()
+            .then(bySession)
+            .catch(() => new Map());
+        this.cached = { at: now, snapshot };
+        return snapshot;
+    }
+    /** Every live record, several per session when several processes hold it. */
+    async read() {
+        let names;
+        try {
+            names = await fs.readdir(this.dir());
+        }
+        catch {
+            return [];
+        }
+        return [...(await this.readFiles(names)).values()].filter((record) => record !== undefined);
+    }
+    /**
+     * The live record of each of the registry files `names`, by name:
+     * undefined for a file that is gone or holds no live record. A name that
+     * is not `<pid>.json` (a `.key` file, a temporary file) is never opened and
+     * not in the result. The rules of {@link read} apply. `recentStarts` takes
+     * a start time that `ps` gave in the last 10 s when it matches the record,
+     * so a record that changes often does not run `ps` each time.
+     */
+    async readFiles(names, options = {}) {
+        const dir = this.dir();
+        const result = new Map();
+        const domain = await this.pidDomain();
+        const candidates = [];
+        await Promise.all(names.map(async (name) => {
+            const match = RECORD_FILE_PATTERN.exec(name);
+            if (!match)
+                return;
+            result.set(name, undefined);
+            const pid = Number(match[1]);
+            const raw = await readRecord(path.join(dir, name));
+            if (!raw || raw.pid !== pid || typeof raw.sessionId !== "string")
+                return;
+            if (typeof raw.pidDomain === "string" && raw.pidDomain !== domain)
+                return;
+            if (!this.isAlive(pid))
+                return;
+            candidates.push({ name, pid, raw });
+        }));
+        const now = this.now();
+        const starts = new Map();
+        const needStarts = [];
+        for (const { pid, raw } of candidates) {
+            if (typeof raw.procStart !== "string")
+                continue;
+            const recent = this.starts.get(pid);
+            // A start that differs may be a new process under the same pid.
+            if (options.recentStarts &&
+                recent &&
+                now - recent.at < RECENT_START_MS &&
+                recent.start === normalizeStart(raw.procStart)) {
+                starts.set(pid, recent.start);
+            }
+            else {
+                needStarts.push(pid);
+            }
+        }
+        if (needStarts.length > 0) {
+            for (const [pid, start] of await this.processStarts(needStarts)) {
+                starts.set(pid, start);
+                this.starts.set(pid, { start, at: now });
+            }
+        }
+        for (const [pid, { at }] of this.starts) {
+            if (now - at >= RECENT_START_MS)
+                this.starts.delete(pid);
+        }
+        for (const { name, pid, raw } of candidates) {
+            const recorded = typeof raw.procStart === "string" ? normalizeStart(raw.procStart) : undefined;
+            const actual = starts.get(pid);
+            if (recorded !== undefined && actual !== undefined && recorded !== actual)
+                continue;
+            const procStartMatches = recorded !== undefined && actual === recorded;
+            const lastSeen = Math.max(finiteNumber(raw.updatedAt) ?? 0, finiteNumber(raw.statusUpdatedAt) ?? 0, finiteNumber(raw.startedAt) ?? 0);
+            if (now - lastSeen > STALE_RECORD_MS && !procStartMatches)
+                continue;
+            result.set(name, {
+                pid,
+                sessionId: raw.sessionId,
+                cwd: optionalString(raw.cwd),
+                kind: optionalString(raw.kind),
+                entrypoint: optionalString(raw.entrypoint),
+                status: optionalString(raw.status),
+                statusUpdatedAt: finiteNumber(raw.statusUpdatedAt),
+            });
+        }
+        return result;
+    }
+}
+/** One record per session: the one with the newest status. */
+export function bySession(records) {
+    const result = new Map();
+    for (const record of records) {
+        const previous = result.get(record.sessionId);
+        if (!previous || (record.statusUpdatedAt ?? 0) > (previous.statusUpdatedAt ?? 0)) {
+            result.set(record.sessionId, record);
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Where Claude Code keeps the transcripts of a working directory.
+ *
+ * The CLI stores the transcripts of `cwd` in `<config>/projects/<encoded cwd>/`.
+ * The encoding replaces every character that is not ASCII alphanumeric with `-`.
+ * A name longer than {@link MAX_SANITIZED_LENGTH} is cut and gets a hash
+ * suffix; the CLI (Bun) and the SDK (Node) compute different hashes, so a long
+ * name is matched by its prefix, as the SDK does.
+ *
+ * The encoding is lossy (`/a/b-c` and `/a/b/c` share a directory), so a
+ * directory name is never decoded: a path belongs to a directory only when
+ * the path encodes to the name.
+ */
+/** Whether `value` is a Claude session id (a UUID). Only such ids name a
+ *  transcript, and only such ids are safe to use as a file name. */
+export declare function isSessionId(value: unknown): value is string;
+/** `<config>/projects`, normalized like the SDK does. */
+export declare function projectsRoot(): string;
+/** The project directory name of `cwd`, exactly as the SDK computes it. */
+export declare function encodeProjectPath(cwd: string): string;
+/** NFC on darwin, as the SDK normalizes paths there. */
+export declare function normalizePath(value: string): string;
+/**
+ * Whether `dirName` is the project directory of `cwd`: the exact encoding, or,
+ * for a long path, a directory with the same cut prefix and any hash suffix.
+ */
+export declare function projectDirMatches(dirName: string, cwd: string): boolean;
+/** Whether a transcript's `cwd` belongs to `projectPath`, compared the way
+ *  the SDK does: the full sanitized forms, ignoring case where the file
+ *  system does. */
+export declare function sameProjectPath(cwd: string, projectPath: string): boolean;
+/** Whether `dirName` is the exact project directory of `cwd`, as the SDK
+ *  finds it by `dir`: the exact encoding, on macOS in any case (the file
+ *  system ignores it). */
+export declare function isExactProjectDir(dirName: string, cwd: string): boolean;
+/** The real path of `cwd`, like the SDK resolves it before encoding. Falls
+ *  back to `cwd` when it does not exist. */
+export declare function canonicalPath(cwd: string): Promise<string>;
+/** The names of the project directories of `cwd` among `rootEntries`. */
+export declare function projectDirsOf(cwd: string, rootEntries: readonly string[]): string[];
+/** `value` and each of its ancestors, nearest first. */
+export declare function pathAndAncestors(value: string): string[];
+/** The `code` of a Node.js system error, if it has one. */
+export declare function errorCode(error: unknown): string | undefined;
+//# sourceMappingURL=project-dirs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"project-dirs.d.ts","sourceRoot":"","sources":["../../src/session-index/project-dirs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH;oEACoE;AACpE,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE3D;AAED,yDAAyD;AACzD,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAeD,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAMD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAOvE;AAED;;mBAEmB;AACnB,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAMzE;AAED;;0BAE0B;AAC1B,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAIvE;AAED;4CAC4C;AAC5C,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAMhE;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAOnF;AAED,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CASxD;AAED,2DAA2D;AAC3D,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG5D"}

package/dist/session-index/project-dirs.js

@@ -0,0 +1,122 @@
+/**
+ * Where Claude Code keeps the transcripts of a working directory.
+ *
+ * The CLI stores the transcripts of `cwd` in `<config>/projects/<encoded cwd>/`.
+ * The encoding replaces every character that is not ASCII alphanumeric with `-`.
+ * A name longer than {@link MAX_SANITIZED_LENGTH} is cut and gets a hash
+ * suffix; the CLI (Bun) and the SDK (Node) compute different hashes, so a long
+ * name is matched by its prefix, as the SDK does.
+ *
+ * The encoding is lossy (`/a/b-c` and `/a/b/c` share a directory), so a
+ * directory name is never decoded: a path belongs to a directory only when
+ * the path encodes to the name.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { claudeConfigDir } from "../paths.js";
+/** The SDK cuts an encoded path at this length and appends a hash. */
+const MAX_SANITIZED_LENGTH = 200;
+const SESSION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Whether `value` is a Claude session id (a UUID). Only such ids name a
+ *  transcript, and only such ids are safe to use as a file name. */
+export function isSessionId(value) {
+    return typeof value === "string" && SESSION_ID_PATTERN.test(value);
+}
+/** `<config>/projects`, normalized like the SDK does. */
+export function projectsRoot() {
+    return path.join(claudeConfigDir(), "projects").normalize("NFC");
+}
+function sanitize(value) {
+    return value.replace(/[^a-zA-Z0-9]/g, "-");
+}
+/** The SDK's 32-bit string hash for long project names. */
+function hashCode(value) {
+    let hash = 0;
+    for (let i = 0; i < value.length; i++) {
+        hash = ((hash << 5) - hash + value.charCodeAt(i)) | 0;
+    }
+    return hash;
+}
+/** The project directory name of `cwd`, exactly as the SDK computes it. */
+export function encodeProjectPath(cwd) {
+    const sanitized = sanitize(normalizePath(cwd));
+    if (sanitized.length <= MAX_SANITIZED_LENGTH)
+        return sanitized;
+    return `${sanitized.slice(0, MAX_SANITIZED_LENGTH)}-${Math.abs(hashCode(normalizePath(cwd))).toString(36)}`;
+}
+/** NFC on darwin, as the SDK normalizes paths there. */
+export function normalizePath(value) {
+    return process.platform === "darwin" ? value.normalize("NFC") : value;
+}
+function sameName(a, b) {
+    return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+/**
+ * Whether `dirName` is the project directory of `cwd`: the exact encoding, or,
+ * for a long path, a directory with the same cut prefix and any hash suffix.
+ */
+export function projectDirMatches(dirName, cwd) {
+    if (sameName(dirName, encodeProjectPath(cwd)))
+        return true;
+    const sanitized = sanitize(normalizePath(cwd));
+    if (sanitized.length <= MAX_SANITIZED_LENGTH)
+        return false;
+    const prefix = `${sanitized.slice(0, MAX_SANITIZED_LENGTH)}-`;
+    const name = process.platform === "win32" ? dirName.toLowerCase() : dirName;
+    return name.startsWith(process.platform === "win32" ? prefix.toLowerCase() : prefix);
+}
+/** Whether a transcript's `cwd` belongs to `projectPath`, compared the way
+ *  the SDK does: the full sanitized forms, ignoring case where the file
+ *  system does. */
+export function sameProjectPath(cwd, projectPath) {
+    const a = sanitize(normalizePath(cwd));
+    const b = sanitize(normalizePath(projectPath));
+    return process.platform === "win32" || process.platform === "darwin"
+        ? a.toLowerCase() === b.toLowerCase()
+        : a === b;
+}
+/** Whether `dirName` is the exact project directory of `cwd`, as the SDK
+ *  finds it by `dir`: the exact encoding, on macOS in any case (the file
+ *  system ignores it). */
+export function isExactProjectDir(dirName, cwd) {
+    const exact = encodeProjectPath(cwd);
+    if (sameName(dirName, exact))
+        return true;
+    return process.platform === "darwin" && dirName.toLowerCase() === exact.toLowerCase();
+}
+/** The real path of `cwd`, like the SDK resolves it before encoding. Falls
+ *  back to `cwd` when it does not exist. */
+export async function canonicalPath(cwd) {
+    try {
+        return normalizePath(await fs.realpath(cwd));
+    }
+    catch {
+        return normalizePath(cwd);
+    }
+}
+/** The names of the project directories of `cwd` among `rootEntries`. */
+export function projectDirsOf(cwd, rootEntries) {
+    const exact = encodeProjectPath(cwd);
+    const sanitizedLength = sanitize(normalizePath(cwd)).length;
+    if (sanitizedLength <= MAX_SANITIZED_LENGTH) {
+        return rootEntries.filter((name) => sameName(name, exact));
+    }
+    return rootEntries.filter((name) => projectDirMatches(name, cwd));
+}
+/** `value` and each of its ancestors, nearest first. */
+export function pathAndAncestors(value) {
+    const result = [];
+    let current = value;
+    for (;;) {
+        result.push(current);
+        const parent = path.dirname(current);
+        if (parent === current)
+            return result;
+        current = parent;
+    }
+}
+/** The `code` of a Node.js system error, if it has one. */
+export function errorCode(error) {
+    const code = error?.code;
+    return typeof code === "string" ? code : undefined;
+}

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

@@ -0,0 +1,158 @@
+/**
+ * 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 { RequestError, type ListSessionsRequest, type ListSessionsResponse } from "@agentclientprotocol/sdk";
+import type { OwnSessionState } from "./activity.js";
+import { type ListChanges, type ListSubscribeResponse } from "./list-subscriptions.js";
+import { LiveSessionRegistry } from "./live-registry.js";
+import { SessionIndex, type ArchivedFilter, type GetSessionInfo, type ListCursor } from "./session-index.js";
+export declare const SESSION_RENAME_METHOD = "_session/rename";
+export declare const SESSION_ARCHIVE_METHOD = "_session/archive";
+export declare const SESSION_UNARCHIVE_METHOD = "_session/unarchive";
+export type SessionIdRequest = {
+    sessionId: string;
+};
+export type RenameSessionRequest = {
+    sessionId: string;
+    title: string;
+};
+export declare function sessionNotFound(sessionId: string): RequestError;
+export declare function parseSessionIdRequest(value: unknown): SessionIdRequest;
+export declare function parseRenameSessionRequest(value: unknown): RenameSessionRequest;
+type ListOptions = {
+    limit: number;
+    archived: ArchivedFilter;
+    includeWorktrees: boolean;
+};
+/** What a cursor is bound to: the request values that select the rows. */
+export type ListScope = {
+    cwd: string | null;
+    archived: ArchivedFilter;
+    includeWorktrees: boolean;
+};
+/** `_meta.jetbrains.air.list` of a list request. */
+export declare function parseListOptions(meta: unknown): ListOptions;
+export declare function encodeListCursor(cursor: ListCursor, scope: ListScope): string;
+/** The position a cursor names. A cursor of another cwd or filter, or one
+ *  this adapter did not issue, is rejected. */
+export declare function decodeListCursor(cursor: string, scope: ListScope): ListCursor;
+/** 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 declare function writeCustomTitleSidecar(transcriptPath: string, title: string): Promise<void>;
+/** The title a change stores for a copy whose title is `current`
+ *  (undefined: none yet), or undefined to leave the copy as it is. */
+export type TitleChange = (current: string | undefined, sessionId: string) => string | undefined;
+/** `_session/rename`: the new title, with the archive prefix on a copy
+ *  that is archived, so a rename keeps the archive state. */
+export declare function renameTo(title: string): TitleChange;
+/** `_session/archive` and `_session/unarchive`: the current title with or
+ *  without the archive prefix; a copy already in that state is left alone. */
+export declare function archiveTo(archived: boolean): TitleChange;
+/**
+ * `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 declare function archiveInsteadOfDelete(sessionId: string, service: SessionIndexService): Promise<void>;
+/** How {@link SessionIndexService.retitle} reaches the session. */
+export type RetitleOptions = {
+    /** The CLI of the session runs here: it stores the title of its own
+     *  transcript (`rename_session`). `stored`: the title last stored through
+     *  it, which it holds; `shown`: the title last shown for a session that has
+     *  neither that nor a transcript. */
+    live?: {
+        cwd: string;
+        rename: (title: string) => Promise<void>;
+        /** Read once the session's earlier title changes are done. */
+        stored: () => string | undefined;
+        /** Records a title the CLI took, before the next change starts. */
+        remember: (title: string) => void;
+        shown?: string;
+    };
+    /** A session without a transcript is not unknown: a new session this
+     *  connection runs, or a live one being renamed. */
+    mayBeUnwritten?: boolean;
+    /** `always` writes the CLI title sidecar next to every titled copy;
+     *  `existing` rewrites only one that is there already. */
+    sidecar: "always" | "existing";
+};
+export type SessionIndexDeps = {
+    getSessionInfo?: GetSessionInfo;
+    deleteSession?: (sessionId: string) => Promise<void>;
+    registry?: LiveSessionRegistry;
+    now?: () => number;
+    /** What this connection knows of a session it runs. */
+    ownSessionState?: (sessionId: string) => OwnSessionState | undefined;
+    /** Sends `_session/list/changes`. */
+    notifyListChanges?: (changes: ListChanges) => Promise<void>;
+    logError: (message: string, error: unknown) => void;
+};
+export declare class SessionIndexService {
+    private readonly deps;
+    readonly index: SessionIndex;
+    readonly registry: LiveSessionRegistry;
+    private subscriptions?;
+    /** Set for good by {@link dispose}: no subscription is made after it. */
+    private disposed;
+    /** The mutation in flight per session, which the next one waits for. */
+    private readonly mutations;
+    private readonly now;
+    private readonly deleteSession;
+    constructor(deps: SessionIndexDeps);
+    /** `session/list` of a `sessionIndex` client. `own` reports the sessions
+     *  that this connection runs. */
+    list(params: ListSessionsRequest, own: (sessionId: string) => OwnSessionState | undefined): Promise<ListSessionsResponse>;
+    /** Runs `mutation` after the previous mutation of the session ended. */
+    private exclusive;
+    /**
+     * 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}.
+     */
+    retitle(sessionId: string, change: TitleChange, options: RetitleOptions): Promise<string | undefined>;
+    /** 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. */
+    private titleCopies;
+    /** 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. */
+    delete(sessionId: string, known: boolean): Promise<void>;
+    /** `_session/list/subscribe`: pushes the changed rows of `cwd` (an
+     *  absolute path) until {@link unsubscribeList} or {@link dispose}. */
+    subscribeList(cwd: string): Promise<ListSubscribeResponse>;
+    /** `_session/list/unsubscribe`. Idempotent. */
+    unsubscribeList(subscriptionId: string): void;
+    /** A session this connection runs changed what its row shows. */
+    ownSessionChanged(sessionId: string): void;
+    dispose(): void;
+}
+export {};
+//# sourceMappingURL=service.d.ts.map

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

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