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

package/dist/session-index/worktrees.js

@@ -0,0 +1,128 @@
+/**
+ * The git worktrees of a working directory, read from the repository files.
+ *
+ * The SDK `listSessions({ dir })` includes the sessions of every worktree of
+ * the repository and runs `git worktree list` for that on each call. This
+ * module reads the same list without spawning git, the way the Codex TUI does:
+ * the main worktree is the parent of the common `.git` directory, and each
+ * linked worktree is named by `<common-dir>/worktrees/<name>/gitdir`.
+ * A worktree whose directory no longer exists is dropped. Nothing is cached:
+ * `git worktree move` rewrites a `gitdir` file without touching the
+ * `worktrees` directory, so a cache keyed on it would miss the move.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { normalizePath } from "./project-dirs.js";
+async function statOrUndefined(target) {
+    try {
+        return await fs.stat(target);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The git dir of the repository that contains `cwd`, or undefined. */
+async function findGitDir(cwd) {
+    let current = path.resolve(cwd);
+    for (;;) {
+        const candidate = path.join(current, ".git");
+        const stats = await statOrUndefined(candidate);
+        if (stats?.isDirectory())
+            return candidate;
+        if (stats?.isFile()) {
+            try {
+                const text = await fs.readFile(candidate, "utf8");
+                const match = /^gitdir:\s*(.+)$/m.exec(text);
+                if (match)
+                    return path.resolve(current, match[1].trim());
+            }
+            catch {
+                // An unreadable `.git` file is not a repository.
+            }
+            return undefined;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+async function commonDirOf(gitDir) {
+    try {
+        const text = await fs.readFile(path.join(gitDir, "commondir"), "utf8");
+        const value = text.trim();
+        if (value)
+            return path.resolve(gitDir, value);
+    }
+    catch {
+        // No `commondir`: the git dir is the common dir.
+    }
+    return gitDir;
+}
+async function linkedWorktrees(commonDir) {
+    const worktreesDir = path.join(commonDir, "worktrees");
+    const stats = await statOrUndefined(worktreesDir);
+    if (!stats?.isDirectory())
+        return [];
+    let names;
+    try {
+        names = await fs.readdir(worktreesDir);
+    }
+    catch {
+        return [];
+    }
+    return (await Promise.all(names.map(async (name) => {
+        try {
+            const text = await fs.readFile(path.join(worktreesDir, name, "gitdir"), "utf8");
+            const gitFile = text.trim();
+            return gitFile ? path.dirname(path.resolve(worktreesDir, name, gitFile)) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }))).filter((value) => value !== undefined);
+}
+/** The root of the worktree that contains `cwd`: the directory of its
+ *  `.git` (a directory in the main worktree, a file in a linked one). */
+async function worktreeRootOf(cwd) {
+    let current = path.resolve(cwd);
+    for (;;) {
+        if (await statOrUndefined(path.join(current, ".git")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+/**
+ * The same subdirectory as `cwd` in every existing worktree of its
+ * repository (the main one and the linked ones), as the Codex TUI expands a
+ * cwd: for `/repo/packages/a`, `/wt1/packages/a` if it exists. For a cwd at a
+ * worktree root, the worktree roots. Empty outside a repository.
+ */
+export async function worktreeCounterparts(cwd) {
+    const root = await worktreeRootOf(cwd);
+    if (!root)
+        return [];
+    const relative = path.relative(root, path.resolve(cwd));
+    const candidates = (await repositoryWorktrees(cwd)).map((worktree) => relative ? path.join(worktree, relative) : worktree);
+    const existing = await Promise.all(candidates.map(async (candidate) => (await statOrUndefined(candidate))?.isDirectory() ? normalizePath(candidate) : undefined));
+    return [...new Set(existing.filter((value) => value !== undefined))];
+}
+/**
+ * Every existing worktree of the repository that contains `cwd`: the main
+ * worktree and the linked ones. Empty outside a repository.
+ */
+export async function repositoryWorktrees(cwd) {
+    const gitDir = await findGitDir(cwd);
+    if (!gitDir)
+        return [];
+    const commonDir = await commonDirOf(gitDir);
+    const candidates = [];
+    if (path.basename(commonDir) === ".git")
+        candidates.push(path.dirname(commonDir));
+    candidates.push(...(await linkedWorktrees(commonDir)));
+    const existing = await Promise.all(candidates.map(async (candidate) => (await statOrUndefined(candidate))?.isDirectory() ? normalizePath(candidate) : undefined));
+    return [...new Set(existing.filter((value) => value !== undefined))];
+}

package/dist/session-titles.d.ts

@@ -36,6 +36,18 @@ export declare class SessionTitles {
      *  the same field as a user `/rename`, so re-titling could silently overwrite
      *  one. Released by {@link reset}, and when generation yields nothing. */
     private settled;
+    /** The title a client set, which no generated title replaces. */
+    private readonly explicit;
+    /** The title last stored through {@link setExplicitTitle}, as stored
+     *  (with the archive prefix of an archived session): the title the CLI
+     *  holds. */
+    private persistedTitle?;
+    /** Client title changes in flight, and the title state before the first. */
+    private explicitChanges;
+    private beforeExplicit?;
+    get storedTitle(): string | undefined;
+    /** The title last published, as the client shows it. */
+    get shownTitle(): string | undefined;
     constructor(agent: ClaudeAcpAgent, sessionId: string);
     /** Collect a prompt's own text for the title, skipping openers not worth
      *  titling after. No-op once the title is settled. */
@@ -58,6 +70,15 @@ export declare class SessionTitles {
      *  not possible do we fall back to `summary`, which for an SDK-driven session
      *  is just the raw first prompt. */
     onTurnEnd(session: Session): Promise<void>;
+    /** Applies a title that the client chose (a rename, an archive or an
+     *  unarchive). Settles the title for good, waits for a generation in flight
+     *  so that its persisted title cannot land after this one, persists the
+     *  title with `persist`, which returns what it stored, if anything, and
+     *  publishes `title` unless it is undefined. A change that stored and
+     *  publishes nothing leaves the title state as it was. */
+    setExplicitTitle(publish: string | ((stored: string | undefined) => string) | undefined, persist: () => Promise<string | undefined | void>): Promise<void>;
+    /** Records a title the CLI took, as soon as it took it. */
+    rememberStoredTitle(title: string): void;
     /** Read the SDK's stored info for this session. A missing session file or read
      *  error is non-fatal: the title is best-effort and another turn will retry. */
     private readSessionInfo;

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

@@ -1 +1 @@
-{"version":3,"file":"session-titles.d.ts","sourceRoot":"","sources":["../src/session-titles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE5E,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AA0B9D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUlD;AAED;gEACgE;AAChE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGrF;AAOD;;iDAEiD;AACjD,qBAAa,aAAa;IAgBtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAhB5B;sEACkE;IAClE,OAAO,CAAC,SAAS,CAAC,CAAS;IAE3B;yEACqE;IACrE,OAAO,CAAC,OAAO,CAAC,CAAS;IAEzB;;;8EAG0E;IAC1E,OAAO,CAAC,OAAO,CAAS;gBAGL,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,MAAM;IAGpC;0DACsD;IACtD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,GAAG,IAAI;IAW/C;kFAC8E;IAC9E,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAO5C;iEAC6D;IAC7D,KAAK,IAAI,IAAI;IAMb;;;;;;;;;;wCAUoC;IAC9B,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BhD;oFACgF;YAClE,eAAe;IAS7B,uEAAuE;YACzD,OAAO;IAgBrB;iFAC6E;IAC7E,OAAO,CAAC,UAAU;IAUlB;;;;;kBAKc;YACA,oBAAoB;CAoCnC"}
+{"version":3,"file":"session-titles.d.ts","sourceRoot":"","sources":["../src/session-titles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE5E,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AA+B9D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqBlD;AAED;gEACgE;AAChE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGrF;AAOD;;iDAEiD;AACjD,qBAAa,aAAa;IAqCtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IArC5B;sEACkE;IAClE,OAAO,CAAC,SAAS,CAAC,CAAS;IAE3B;yEACqE;IACrE,OAAO,CAAC,OAAO,CAAC,CAAS;IAEzB;;;8EAG0E;IAC1E,OAAO,CAAC,OAAO,CAAS;IAExB,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAEhD;;iBAEa;IACb,OAAO,CAAC,cAAc,CAAC,CAAS;IAEhC,4EAA4E;IAC5E,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,cAAc,CAAC,CAAoD;IAE3E,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAEpC;IAED,wDAAwD;IACxD,IAAI,UAAU,IAAI,MAAM,GAAG,SAAS,CAEnC;gBAGkB,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,MAAM;IAGpC;0DACsD;IACtD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,GAAG,IAAI;IAW/C;kFAC8E;IAC9E,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAO5C;iEAC6D;IAC7D,KAAK,IAAI,IAAI;IAQb;;;;;;;;;;wCAUoC;IAC9B,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAoDhD;;;;;8DAK0D;IACpD,gBAAgB,CACpB,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,CAAC,GAAG,SAAS,EACtE,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,GAChD,OAAO,CAAC,IAAI,CAAC;IAkChB,2DAA2D;IAC3D,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIxC;oFACgF;YAClE,eAAe;IAS7B,uEAAuE;YACzD,OAAO;IAgBrB;iFAC6E;IAC7E,OAAO,CAAC,UAAU;IAUlB;;;;;kBAKc;YACA,oBAAoB;CAoCnC"}

package/dist/session-titles.js

@@ -14,6 +14,7 @@
  * {@link SessionTitles.reset} on `conversation_reset`.
  */
 import { getSessionInfo } from "@anthropic-ai/claude-agent-sdk";
+import { ExplicitTitle } from "./session-index/explicit-title.js";
 const MAX_TITLE_LENGTH = 256;
 /** How much session text the title is generated from. The CLI caps its own
  *  title input at the same 1000 trailing characters. */
@@ -21,7 +22,21 @@ const MAX_TITLE_CONTEXT_LENGTH = 1000;
 /** Below this the generator returns null without calling the model, so there is
  *  nothing to gain by asking yet. */
 const MIN_TITLE_CONTEXT_LENGTH = 10;
+/** How much of a long text {@link sanitizeTitle} reads first. Collapsed, it
+ *  is longer than a title unless it is mostly whitespace. */
+const TITLE_SCAN_LENGTH = 4096;
 export function sanitizeTitle(text) {
+    if (text.length > TITLE_SCAN_LENGTH) {
+        // A stored summary can be a whole first prompt of megabytes. The title
+        // depends only on the start of the text: collapsing the whitespace of a
+        // prefix gives a prefix of the collapsed text. Two more characters than a
+        // title hold at least one that is not a space (spaces are collapsed), so
+        // the full text is longer than a title and gets the same cut.
+        const head = text.slice(0, TITLE_SCAN_LENGTH).replace(/\s+/g, " ").trimStart();
+        if (head.length >= MAX_TITLE_LENGTH + 2) {
+            return head.slice(0, MAX_TITLE_LENGTH - 1) + "…";
+        }
+    }
     // Replace newlines and collapse whitespace
     const sanitized = text
         .replace(/[\r\n]+/g, " ")
@@ -59,6 +74,22 @@ export class SessionTitles {
      *  the same field as a user `/rename`, so re-titling could silently overwrite
      *  one. Released by {@link reset}, and when generation yields nothing. */
     settled = false;
+    /** The title a client set, which no generated title replaces. */
+    explicit = new ExplicitTitle();
+    /** The title last stored through {@link setExplicitTitle}, as stored
+     *  (with the archive prefix of an archived session): the title the CLI
+     *  holds. */
+    persistedTitle;
+    /** Client title changes in flight, and the title state before the first. */
+    explicitChanges = 0;
+    beforeExplicit;
+    get storedTitle() {
+        return this.persistedTitle;
+    }
+    /** The title last published, as the client shows it. */
+    get shownTitle() {
+        return this.lastTitle;
+    }
     constructor(agent, sessionId) {
         this.agent = agent;
         this.sessionId = sessionId;
@@ -86,8 +117,10 @@ export class SessionTitles {
      *  `conversation_reset`, which mounts a fresh transcript. */
     reset() {
         this.settled = false;
+        this.explicit.reset();
         this.context = undefined;
         this.lastTitle = undefined;
+        this.persistedTitle = undefined;
     }
     /** Turn-end title handling. `idle` is the SDK's turn-over signal, so it is
      *  when a title may have landed or become generatable.
@@ -101,7 +134,26 @@ export class SessionTitles {
      *  not possible do we fall back to `summary`, which for an SDK-driven session
      *  is just the raw first prompt. */
     async onTurnEnd(session) {
+        if (this.explicit.settledByClient) {
+            // No title is generated over the one the client set, but a custom title
+            // stored since by someone else (a `/rename`) is adopted, as before.
+            const renames = this.explicit.renames;
+            const info = await this.readSessionInfo(session);
+            // No client change ran during the read, so the stored title is current;
+            // an unchanged one is not published again.
+            const stored = info?.customTitle;
+            if (stored && this.explicit.settledByClient && this.explicit.renames === renames) {
+                await this.publish(stored, info.lastModified);
+            }
+            return;
+        }
+        // While a client title change is in flight, the session info read below
+        // could still hold the previous title.
+        if (this.explicit.active)
+            return;
         const info = await this.readSessionInfo(session);
+        if (this.explicit.active)
+            return;
         if (info?.customTitle) {
             this.settled = true;
             this.context = undefined;
@@ -113,9 +165,9 @@ export class SessionTitles {
             : undefined;
         if (this.canRequest(session)) {
             this.settled = true;
-            void this.requestGenerateTitle(session, fallback).catch((error) => {
+            this.explicit.track(this.requestGenerateTitle(session, fallback).catch((error) => {
                 this.agent.logger.error(`Session ${this.sessionId}: session title update failed: ${error}`);
-            });
+            }));
             return;
         }
         // Only while this session has no title of its own: `summary` degrades to the
@@ -125,6 +177,50 @@ export class SessionTitles {
             await this.publish(fallback.title, fallback.lastModified);
         }
     }
+    /** Applies a title that the client chose (a rename, an archive or an
+     *  unarchive). Settles the title for good, waits for a generation in flight
+     *  so that its persisted title cannot land after this one, persists the
+     *  title with `persist`, which returns what it stored, if anything, and
+     *  publishes `title` unless it is undefined. A change that stored and
+     *  publishes nothing leaves the title state as it was. */
+    async setExplicitTitle(publish, persist) {
+        // The state before the first of overlapping changes, which a change that
+        // fails or names nothing puts back.
+        if (this.explicitChanges++ === 0) {
+            this.beforeExplicit = { settled: this.settled, context: this.context };
+        }
+        const previous = this.beforeExplicit;
+        this.settled = true;
+        this.context = undefined;
+        let stored;
+        try {
+            await this.explicit.apply(async () => {
+                stored = (await persist()) ?? undefined;
+                if (stored !== undefined)
+                    this.persistedTitle = stored;
+                return stored !== undefined || publish !== undefined;
+            }, () => {
+                this.settled = previous.settled;
+                this.context ??= previous.context;
+            });
+        }
+        finally {
+            if (--this.explicitChanges === 0)
+                this.beforeExplicit = undefined;
+        }
+        const title = typeof publish === "function" ? publish(stored) : publish;
+        if (title === undefined)
+            return;
+        this.lastTitle = title;
+        await this.agent.client.sessionUpdate({
+            sessionId: this.sessionId,
+            update: { sessionUpdate: "session_info_update", title },
+        });
+    }
+    /** Records a title the CLI took, as soon as it took it. */
+    rememberStoredTitle(title) {
+        this.persistedTitle = title;
+    }
     /** Read the SDK's stored info for this session. A missing session file or read
      *  error is non-fatal: the title is best-effort and another turn will retry. */
     async readSessionInfo(session) {
@@ -138,7 +234,7 @@ export class SessionTitles {
     }
     /** Notify the client of a title, unless it is the one we last sent. */
     async publish(rawTitle, lastModified) {
-        const title = sanitizeTitle(rawTitle);
+        const title = sanitizeTitle(this.agent.clientTitle?.(rawTitle) ?? rawTitle);
         if (title === this.lastTitle) {
             return;
         }
@@ -182,8 +278,8 @@ export class SessionTitles {
             this.agent.logger.error(`Session ${this.sessionId}: failed to generate a session title: ${error}`);
         }
         // A session torn down or replaced while the title was in flight must not
-        // adopt it.
-        if (this.agent.sessions[this.sessionId] !== session) {
+        // adopt it, and a title the client set meanwhile wins.
+        if (this.agent.sessions[this.sessionId] !== session || this.explicit.active) {
             return;
         }
         if (!title) {

package/dist/utils.d.ts

@@ -12,6 +12,37 @@ export declare class Pushable<T> implements AsyncIterable<T> {
 export declare function nodeToWebWritable(nodeStream: Writable): WritableStream<Uint8Array>;
 export declare function nodeToWebReadable(nodeStream: Readable): ReadableStream<Uint8Array>;
 export declare function unreachable(value: never, logger?: Logger): void;
+/**
+ * Yields to the event loop when the current macrotask has run for too long.
+ *
+ * An await of an already-resolved promise continues in a microtask, so a loop
+ * that drains a backlog of buffered messages never lets timers or I/O run:
+ * incoming requests, `session/cancel` among them, wait until the backlog is
+ * gone. A loop calls {@link maybeYield} once per item. Within the budget it
+ * returns undefined and the loop goes on at once. Past the budget it returns a
+ * promise that resolves in the check phase of the event loop, after pending
+ * I/O has run.
+ *
+ * The budget is measured from the first call since the event loop last
+ * reached its check phase, so a loop that already waits on real I/O never
+ * yields, and all loops that share one instance share one budget per
+ * event-loop iteration.
+ *
+ * A test that fakes `setImmediate` and drives such a loop for longer than the
+ * budget must advance the fake timers, or the loop waits for them.
+ */
+export declare class EventLoopYielder {
+    private readonly budgetMs;
+    private readonly now;
+    /** Whether a check-phase marker is pending. While it is, the event loop has
+     *  not reached its check phase since {@link sliceStart}. */
+    private markerPending;
+    private sliceStart;
+    constructor(budgetMs: number, now?: () => number);
+    maybeYield(): Promise<void> | undefined;
+}
+/** The yielder shared by the loops that forward messages to the client. */
+export declare const messageLoopYielder: EventLoopYielder;
 export declare function sleep(time: number): Promise<void>;
 /** The outcome of {@link raceTimeoutAndAbort}. */
 export type RaceOutcome<T> = {

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAGxC,qBAAa,QAAQ,CAAC,CAAC,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAClD,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,IAAI,CAAS;IAErB,IAAI,CAAC,IAAI,EAAE,CAAC;IASZ,GAAG;IAQH,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;CAgB3C;AAGD,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,CAclF;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,CAUlF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,GAAE,MAAgB,QAQjE;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjD;AAED,kDAAkD;AAClD,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEpG;kFACkF;AAClF,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAoBzB"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAGxC,qBAAa,QAAQ,CAAC,CAAC,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAClD,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,IAAI,CAAS;IAErB,IAAI,CAAC,IAAI,EAAE,CAAC;IASZ,GAAG;IAQH,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;CAgB3C;AAKD,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,CAoBlF;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,CAUlF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,GAAE,MAAgB,QAQjE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAgB;IAOzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB;gEAC4D;IAC5D,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,UAAU,CAAK;gBAGJ,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,MAAM,MAAgC;IAG9D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS;CAaxC;AAMD,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,kBAA+C,CAAC;AAE/E,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjD;AAED,kDAAkD;AAClD,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEpG;kFACkF;AAClF,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAoBzB"}

package/dist/utils.js

@@ -38,12 +38,20 @@ export class Pushable {
         };
     }
 }
-// Helper to convert Node.js streams to Web Streams
+// Helper to convert Node.js streams to Web Streams. A byte stream gets each
+// chunk without a copy, so the caller must not change a chunk until its write
+// resolves.
 export function nodeToWebWritable(nodeStream) {
     return new WritableStream({
         write(chunk) {
             return new Promise((resolve, reject) => {
-                nodeStream.write(Buffer.from(chunk), (err) => {
+                // A Uint8Array is written as it is: Node wraps it in a Buffer view
+                // without a copy. The ACP encoder hands each message a fresh array,
+                // so nothing changes the bytes while the write is pending. An
+                // object-mode stream would get the array itself, so it keeps
+                // getting a Buffer copy, as before.
+                const data = nodeStream.writableObjectMode ? Buffer.from(chunk) : chunk;
+                nodeStream.write(data, (err) => {
                     if (err) {
                         reject(err);
                     }
@@ -76,6 +84,56 @@ export function unreachable(value, logger = console) {
     }
     logger.error(`Unexpected case: ${valueAsString}`);
 }
+/**
+ * Yields to the event loop when the current macrotask has run for too long.
+ *
+ * An await of an already-resolved promise continues in a microtask, so a loop
+ * that drains a backlog of buffered messages never lets timers or I/O run:
+ * incoming requests, `session/cancel` among them, wait until the backlog is
+ * gone. A loop calls {@link maybeYield} once per item. Within the budget it
+ * returns undefined and the loop goes on at once. Past the budget it returns a
+ * promise that resolves in the check phase of the event loop, after pending
+ * I/O has run.
+ *
+ * The budget is measured from the first call since the event loop last
+ * reached its check phase, so a loop that already waits on real I/O never
+ * yields, and all loops that share one instance share one budget per
+ * event-loop iteration.
+ *
+ * A test that fakes `setImmediate` and drives such a loop for longer than the
+ * budget must advance the fake timers, or the loop waits for them.
+ */
+export class EventLoopYielder {
+    budgetMs;
+    now;
+    /** Whether a check-phase marker is pending. While it is, the event loop has
+     *  not reached its check phase since {@link sliceStart}. */
+    markerPending = false;
+    sliceStart = 0;
+    constructor(budgetMs, now = () => performance.now()) {
+        this.budgetMs = budgetMs;
+        this.now = now;
+    }
+    maybeYield() {
+        const time = this.now();
+        if (!this.markerPending) {
+            this.markerPending = true;
+            this.sliceStart = time;
+            setImmediate(() => {
+                this.markerPending = false;
+            });
+            return undefined;
+        }
+        if (time - this.sliceStart < this.budgetMs)
+            return undefined;
+        return new Promise((resolve) => setImmediate(resolve));
+    }
+}
+/** The longest stretch, in milliseconds, that a message loop keeps the event
+ *  loop before it yields. */
+const MESSAGE_LOOP_BUDGET_MS = 8;
+/** The yielder shared by the loops that forward messages to the client. */
+export const messageLoopYielder = new EventLoopYielder(MESSAGE_LOOP_BUDGET_MS);
 export function sleep(time) {
     return new Promise((resolve) => setTimeout(resolve, time));
 }

package/dist/v2/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/v2/agent.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAkB,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAkB9E;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GACvC,EAAE,CAAC,QAAQ,CA4Db"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/v2/agent.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAkB,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAmB9E;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GACvC,EAAE,CAAC,QAAQ,CAoEb"}

package/dist/v2/agent.js

@@ -3,7 +3,7 @@ import { ClaudeAcpAgent } from "../acp-agent.js";
 import { v1InitializeRequest, v2InitializeResponse } from "./initialize.js";
 import { v1PermissionResponse, v2PermissionRequest } from "./permission.js";
 import { v2Prompt } from "./prompt.js";
-import { v1ForkSessionRequests, v1NewSessionRequest, v1RestoreSessionRequest, v1SetSessionConfigOptionRequest, v2ConfigOptions, v2NewSessionResponse, v2ResumeSessionResponse, } from "./session.js";
+import { v1ForkSessionRequests, v1NewSessionRequest, v1RestoreSessionRequest, v1SetSessionConfigOptionRequest, v2AvailableCommands, v2ConfigOptions, v2NewSessionResponse, v2ResumeSessionResponse, } from "./session.js";
 import { v2SessionUpdate } from "./session-update.js";
 import { V2Terminals } from "./terminal.js";
 /**
@@ -31,13 +31,23 @@ export function v2AgentApp(logger, onAgent) {
         .onRequest(v2.methods.agent.providers.list, ({ params }) => agent.unstable_listProviders(params))
         .onRequest(v2.methods.agent.providers.set, ({ params }) => agent.unstable_setProvider(params))
         .onRequest(v2.methods.agent.providers.disable, ({ params }) => agent.unstable_disableProvider(params))
-        .onRequest(v2.methods.agent.session.new, async ({ params }) => v2NewSessionResponse(await agent.newSession(v1NewSessionRequest(params))))
+        .onRequest(v2.methods.agent.session.new, async ({ params }) => {
+        const response = await agent.newSession(v1NewSessionRequest(params));
+        return {
+            ...v2NewSessionResponse(response),
+            ...(await setupCommands(agent, response.sessionId, logger)),
+        };
+    })
         .onRequest(v2.methods.agent.session.list, ({ params }) => agent.listSessions(params))
         .onRequest(v2.methods.agent.session.resume, async ({ params }) => {
         const restore = v1RestoreSessionRequest(params);
-        return v2ResumeSessionResponse(restore.method === "resume"
+        const response = restore.method === "resume"
             ? await agent.resumeSession(restore.request)
-            : await client.replaying(params.sessionId, () => agent.loadSession(restore.request)));
+            : await client.replaying(params.sessionId, () => agent.loadSession(restore.request));
+        return {
+            ...v2ResumeSessionResponse(response),
+            ...(await setupCommands(agent, params.sessionId, logger)),
+        };
     })
         .onRequest(v2.methods.agent.session.fork, async ({ params }) => {
         const requests = v1ForkSessionRequests(params);
@@ -45,6 +55,7 @@ export function v2AgentApp(logger, onAgent) {
         return {
             sessionId,
             ...v2ResumeSessionResponse(await agent.resumeSession(requests.resume(sessionId))),
+            ...(await setupCommands(agent, sessionId, logger)),
         };
     })
         .onRequest(v2.methods.agent.session.close, async ({ params }) => {
@@ -62,6 +73,24 @@ export function v2AgentApp(logger, onAgent) {
     }))
         .onNotification(v2.methods.agent.session.cancel, ({ params }) => agent.cancel(params));
 }
+/**
+ * The `availableCommands` of a setup response, so a client can show the
+ * session's commands without waiting for an update. The agent sends a v1
+ * client the same list as an `available_commands_update` after the response,
+ * and a v2 client none (`ClaudeAcpAgent.afterSetupResponse`). Later changes
+ * still arrive as updates. An empty list is left out, as the draft asks. The
+ * commands are optional, so a failure to read them does not fail the setup.
+ */
+async function setupCommands(agent, sessionId, logger) {
+    try {
+        const commands = await agent.availableCommands(sessionId);
+        return commands.length > 0 ? { availableCommands: v2AvailableCommands(commands) } : {};
+    }
+    catch (error) {
+        (logger ?? console).error(`Session ${sessionId}: failed to read the session's commands`, error);
+        return {};
+    }
+}
 /**
  * The {@link AcpClient} of an ACP v2 connection: it sends the v1 messages of
  * the agent as v2 messages.

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.88.1-preview.5",
+  "version": "0.88.1-preview.7",
   "description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",