@agentclientprotocol/claude-agent-acp 0.94.0 → 0.94.1-preview.10

package/dist/session-index/transcript-scan.js

@@ -7,8 +7,12 @@
  *
  * A last message longer than the tail window leaves no message in it: then
  * the tail window grows, up to {@link MAX_TAIL_SIZE}, until it holds one.
+ *
+ * The open background tasks come from the tail, on top of the tasks of an
+ * earlier scan (see `background-tasks.ts`).
  */
 import * as fs from "node:fs/promises";
+import { backgroundTasksOf } from "./background-tasks.js";
 import { firstPrompt, isUserPrompt, mediaPrompt, promptOf } from "./first-prompt.js";
 const CHUNK_SIZE = 64 * 1024;
 /** The largest tail window read to find the last message. */
@@ -88,6 +92,8 @@ identity) {
             }
         }
     }
+    const previousTasks = grownWithinTail ? previous.backgroundTasks : undefined;
+    facts.backgroundTasks = tailBackgroundTasks(read.tail, size, previousTasks);
     // No worktree record in the tail (or before it, by an earlier scan): the
     // one `claude --worktree` writes at the start may still be in the head.
     if (facts.agentWorktree === undefined) {
@@ -107,8 +113,9 @@ identity) {
         return facts;
     const key = `${filePath}\0${size}\0${identity ?? ""}`;
     const searched = fullySearched.get(key);
+    // The tasks can differ by the earlier scan.
     if (searched)
-        return searched;
+        return { ...searched, backgroundTasks: facts.backgroundTasks };
     let result = facts;
     const handle = await fs.open(filePath, "r");
     try {
@@ -150,6 +157,7 @@ identity) {
                 // A turn end the wider tail lacks may lie before it: the
                 // narrow scan inherited it from an earlier scan of this file.
                 lastTurnEndedAt: wider.lastTurnEndedAt ?? facts.lastTurnEndedAt,
+                backgroundTasks: facts.backgroundTasks,
                 hasMessages: facts.hasMessages,
                 lastPromptAt,
                 // Searched to the start of the file, or found.
@@ -170,6 +178,19 @@ identity) {
     }
     return result;
 }
+/**
+ * The background tasks of the tail of a file of `size` bytes. `previous`:
+ * the tasks of an earlier scan, when the file only grew within the tail
+ * since. The set is complete when the tail is the whole file, or when it
+ * holds all records after a complete earlier set.
+ */
+function tailBackgroundTasks(tail, size, previous) {
+    if (size <= CHUNK_SIZE)
+        return backgroundTasksOf(tail, { complete: true });
+    if (previous?.complete)
+        return backgroundTasksOf(tail, { complete: true, after: previous });
+    return backgroundTasksOf(tail, { complete: false });
+}
 const RELOCATED_MARKER = '"relocated"';
 /** The cwd of the last `relocated` record of the tail: where the session
  *  was moved, whatever cwd its earlier messages carry. */

package/dist/session-titles.d.ts

@@ -1,15 +1,20 @@
 /**
  * AI-generated session titles.
  *
- * Claude Code's own auto-title generation never runs under the Agent SDK — the
- * latch that arms it is pre-set in the headless path — so `SDKSessionInfo.summary`
- * degrades to the raw first prompt. This module asks the CLI for a real title
- * instead, via the `generate_session_title` control request, and publishes it
- * over ACP as a `session_info_update`.
+ * Claude Code titles a new SDK session itself: when it reads the first prompt,
+ * it asks a small model for a title and stores it in the transcript as an
+ * `ai-title` entry, a few seconds in. It sends no message when it does. This
+ * module asks for the title with the `generate_session_title` control request,
+ * which returns the stored title or waits for the one being generated, and
+ * publishes it over ACP as a `session_info_update`. Where the CLI does not
+ * title the session itself (a resumed session, or one with
+ * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or
+ * `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` set), the same request generates it.
  *
  * {@link SessionTitles} holds the per-session state and is owned by `Session`.
- * `acp-agent.ts` drives it from four places: {@link SessionTitles.onPrompt} and
+ * `acp-agent.ts` drives it from five places: {@link SessionTitles.onPrompt} and
  * {@link SessionTitles.onAssistantText} to collect text,
+ * {@link SessionTitles.onPromptQueued} once a prompt is sent to the CLI,
  * {@link SessionTitles.onTurnEnd} at `session_state_changed: idle`, and
  * {@link SessionTitles.reset} on `conversation_reset`.
  */
@@ -36,6 +41,10 @@ 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;
+    /** Whether {@link onPromptQueued} asked for a title from the latest prompt.
+     *  A turn end then does not ask again: like the CLI, a prompt that yields
+     *  no title gets one try, and the next prompt tries again. */
+    private askedAtPrompt;
     /** The title a client set, which no generated title replaces. */
     private readonly explicit;
     /** The title last stored through {@link setExplicitTitle}, as stored
@@ -52,6 +61,15 @@ export declare class SessionTitles {
     /** Collect a prompt's own text for the title, skipping openers not worth
      *  titling after. No-op once the title is settled. */
     onPrompt(prompt: PromptRequest["prompt"]): void;
+    /** Ask for the title as soon as a prompt is sent to the CLI, instead of
+     *  waiting for `idle`: `idle` comes only after the whole turn and its
+     *  background tasks, often minutes after the CLI stored its title. The CLI
+     *  answers `generate_session_title` while the turn runs, and with the title
+     *  it stored or is generating, so this makes no second model call. The
+     *  prompt alone is the description, because the CLI titles from the prompt
+     *  alone. When this yields no title, the stored summary is published and
+     *  the next prompt tries again. */
+    onPromptQueued(session: Session, prompt: PromptRequest["prompt"]): void;
     /** Collect the assistant's own answer for the title. Chunks are appended
      *  verbatim so streamed text reassembles. No-op once the title is settled. */
     onAssistantText(content: ContentBlock): void;
@@ -65,10 +83,12 @@ export declare class SessionTitles {
      *  title — a user `/rename` or one generated earlier; the SDK folds both into
      *  that one field. Adopt it and latch, so neither is ever titled over.
      *
-     *  With no title yet, ask the SDK to generate one in the background: it is a
-     *  ~2s small-model call and turn-end must not wait on it. Only when that is
-     *  not possible do we fall back to `summary`, which for an SDK-driven session
-     *  is just the raw first prompt. */
+     *  With no title yet, and none asked for at the latest prompt (see
+     *  {@link onPromptQueued}), ask the SDK to generate one in the background
+     *  from the prompts and replies so far: it is a ~2s small-model call and
+     *  turn-end must not wait on it. That covers a prompt too short to title
+     *  from, such as "hi". Only when that is 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
@@ -87,12 +107,20 @@ export declare class SessionTitles {
     /** Whether to ask the SDK for a generated title now: once per session, on a
      *  live query, with enough collected text for the generator to work with. */
     private canRequest;
-    /** Generate a title from the session's own text and publish it. `persist`
-     *  writes it to the session file, which is what carries it into
-     *  `session/list` and `session/load`. A null or failed generation releases the
-     *  latch so a later turn retries, and publishes `fallback` (the stored
-     *  summary) so a backend that can't generate titles is no worse off than
-     *  before. */
+    /** Latch the title and run `generation` in the background, so neither the
+     *  prompt nor turn-end waits on a model call. A client title change waits
+     *  for it to finish (see {@link ExplicitTitle.track}). */
+    private startGeneration;
+    /** The prompt-time title: the one the session file already holds (a resumed
+     *  session's title, or a `/rename`), else one generated from `description`.
+     *  The file is read first because the CLI checks only the titles it holds in
+     *  memory before generating one. */
+    private titleFromPrompt;
+    /** Generate a title from `description` and publish it. `persist` writes it
+     *  to the session file, which is what carries it into `session/list` and
+     *  `session/load`. A null or failed generation releases the latch so a later
+     *  prompt or turn end retries, and publishes `fallback` (the stored summary)
+     *  so a backend that can't generate titles is no worse off than before. */
     private requestGenerateTitle;
 }
 //# sourceMappingURL=session-titles.d.ts.map

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,mCAAmC,CAAC;AAErF,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"}
+{"version":3,"file":"session-titles.d.ts","sourceRoot":"","sources":["../src/session-titles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAErF,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;AAYD;;iDAEiD;AACjD,qBAAa,aAAa;IA0CtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IA1C5B;sEACkE;IAClE,OAAO,CAAC,SAAS,CAAC,CAAS;IAE3B;yEACqE;IACrE,OAAO,CAAC,OAAO,CAAC,CAAS;IAEzB;;;8EAG0E;IAC1E,OAAO,CAAC,OAAO,CAAS;IAExB;;kEAE8D;IAC9D,OAAO,CAAC,aAAa,CAAS;IAE9B,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;IAO/C;;;;;;;uCAOmC;IACnC,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,GAAG,IAAI;IAkBvE;kFAC8E;IAC9E,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAO5C;iEAC6D;IAC7D,KAAK,IAAI,IAAI;IASb;;;;;;;;;;;;mFAY+E;IACzE,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA4ChD;;;;;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;;8DAE0D;IAC1D,OAAO,CAAC,eAAe;IASvB;;;wCAGoC;YACtB,eAAe;IAgB7B;;;;+EAI2E;YAC7D,oBAAoB;CAoCnC"}

package/dist/session-titles.js

@@ -1,15 +1,20 @@
 /**
  * AI-generated session titles.
  *
- * Claude Code's own auto-title generation never runs under the Agent SDK — the
- * latch that arms it is pre-set in the headless path — so `SDKSessionInfo.summary`
- * degrades to the raw first prompt. This module asks the CLI for a real title
- * instead, via the `generate_session_title` control request, and publishes it
- * over ACP as a `session_info_update`.
+ * Claude Code titles a new SDK session itself: when it reads the first prompt,
+ * it asks a small model for a title and stores it in the transcript as an
+ * `ai-title` entry, a few seconds in. It sends no message when it does. This
+ * module asks for the title with the `generate_session_title` control request,
+ * which returns the stored title or waits for the one being generated, and
+ * publishes it over ACP as a `session_info_update`. Where the CLI does not
+ * title the session itself (a resumed session, or one with
+ * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or
+ * `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` set), the same request generates it.
  *
  * {@link SessionTitles} holds the per-session state and is owned by `Session`.
- * `acp-agent.ts` drives it from four places: {@link SessionTitles.onPrompt} and
+ * `acp-agent.ts` drives it from five places: {@link SessionTitles.onPrompt} and
  * {@link SessionTitles.onAssistantText} to collect text,
+ * {@link SessionTitles.onPromptQueued} once a prompt is sent to the CLI,
  * {@link SessionTitles.onTurnEnd} at `session_state_changed: idle`, and
  * {@link SessionTitles.reset} on `conversation_reset`.
  */
@@ -53,6 +58,10 @@ export function appendTitleContext(previous, text) {
     const next = (previous ?? "") + text;
     return next.length > MAX_TITLE_CONTEXT_LENGTH ? next.slice(-MAX_TITLE_CONTEXT_LENGTH) : next;
 }
+/** The text chunks of a prompt, one per line. */
+function promptText(prompt) {
+    return prompt.flatMap((chunk) => (chunk.type === "text" ? [chunk.text] : [])).join("\n");
+}
 /** Whether this SDK still offers on-demand title generation. */
 function supportsTitleGeneration(query) {
     return typeof query.generateSessionTitle === "function";
@@ -74,6 +83,10 @@ 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;
+    /** Whether {@link onPromptQueued} asked for a title from the latest prompt.
+     *  A turn end then does not ask again: like the CLI, a prompt that yields
+     *  no title gets one try, and the next prompt tries again. */
+    askedAtPrompt = false;
     /** The title a client set, which no generated title replaces. */
     explicit = new ExplicitTitle();
     /** The title last stored through {@link setExplicitTitle}, as stored
@@ -100,10 +113,32 @@ export class SessionTitles {
         if (this.settled) {
             return;
         }
-        const promptText = prompt
-            .flatMap((chunk) => (chunk.type === "text" ? [chunk.text] : []))
-            .join("\n");
-        this.context = appendTitleContext(this.context, `\n${promptText}\n`);
+        this.context = appendTitleContext(this.context, `\n${promptText(prompt)}\n`);
+    }
+    /** Ask for the title as soon as a prompt is sent to the CLI, instead of
+     *  waiting for `idle`: `idle` comes only after the whole turn and its
+     *  background tasks, often minutes after the CLI stored its title. The CLI
+     *  answers `generate_session_title` while the turn runs, and with the title
+     *  it stored or is generating, so this makes no second model call. The
+     *  prompt alone is the description, because the CLI titles from the prompt
+     *  alone. When this yields no title, the stored summary is published and
+     *  the next prompt tries again. */
+    onPromptQueued(session, prompt) {
+        this.askedAtPrompt = false;
+        // `session.cancelled` is not checked: after a cancelled turn it stays set
+        // until the next turn starts, which is after this prompt is queued.
+        if (this.settled || this.explicit.active || session.queryClosed) {
+            return;
+        }
+        if (!supportsTitleGeneration(session.query)) {
+            return;
+        }
+        const description = promptText(prompt).trim();
+        if (description.length < MIN_TITLE_CONTEXT_LENGTH) {
+            return;
+        }
+        this.askedAtPrompt = true;
+        this.startGeneration(() => this.titleFromPrompt(session, description));
     }
     /** Collect the assistant's own answer for the title. Chunks are appended
      *  verbatim so streamed text reassembles. No-op once the title is settled. */
@@ -117,6 +152,7 @@ export class SessionTitles {
      *  `conversation_reset`, which mounts a fresh transcript. */
     reset() {
         this.settled = false;
+        this.askedAtPrompt = false;
         this.explicit.reset();
         this.context = undefined;
         this.lastTitle = undefined;
@@ -129,10 +165,12 @@ export class SessionTitles {
      *  title — a user `/rename` or one generated earlier; the SDK folds both into
      *  that one field. Adopt it and latch, so neither is ever titled over.
      *
-     *  With no title yet, ask the SDK to generate one in the background: it is a
-     *  ~2s small-model call and turn-end must not wait on it. Only when that is
-     *  not possible do we fall back to `summary`, which for an SDK-driven session
-     *  is just the raw first prompt. */
+     *  With no title yet, and none asked for at the latest prompt (see
+     *  {@link onPromptQueued}), ask the SDK to generate one in the background
+     *  from the prompts and replies so far: it is a ~2s small-model call and
+     *  turn-end must not wait on it. That covers a prompt too short to title
+     *  from, such as "hi". Only when that is 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
@@ -163,11 +201,9 @@ export class SessionTitles {
         const fallback = info?.summary
             ? { title: info.summary, lastModified: info.lastModified }
             : undefined;
-        if (this.canRequest(session)) {
-            this.settled = true;
-            this.explicit.track(this.requestGenerateTitle(session, fallback).catch((error) => {
-                this.agent.logger.error(`Session ${this.sessionId}: session title update failed: ${error}`);
-            }));
+        if (!this.askedAtPrompt && this.canRequest(session)) {
+            const description = this.context?.trim() ?? "";
+            this.startGeneration(() => this.requestGenerateTitle(session, description, fallback));
             return;
         }
         // Only while this session has no title of its own: `summary` degrades to the
@@ -259,14 +295,40 @@ export class SessionTitles {
         }
         return (this.context?.trim().length ?? 0) >= MIN_TITLE_CONTEXT_LENGTH;
     }
-    /** Generate a title from the session's own text and publish it. `persist`
-     *  writes it to the session file, which is what carries it into
-     *  `session/list` and `session/load`. A null or failed generation releases the
-     *  latch so a later turn retries, and publishes `fallback` (the stored
-     *  summary) so a backend that can't generate titles is no worse off than
-     *  before. */
-    async requestGenerateTitle(session, fallback) {
-        const description = this.context?.trim() ?? "";
+    /** Latch the title and run `generation` in the background, so neither the
+     *  prompt nor turn-end waits on a model call. A client title change waits
+     *  for it to finish (see {@link ExplicitTitle.track}). */
+    startGeneration(generation) {
+        this.settled = true;
+        this.explicit.track(generation().catch((error) => {
+            this.agent.logger.error(`Session ${this.sessionId}: session title update failed: ${error}`);
+        }));
+    }
+    /** The prompt-time title: the one the session file already holds (a resumed
+     *  session's title, or a `/rename`), else one generated from `description`.
+     *  The file is read first because the CLI checks only the titles it holds in
+     *  memory before generating one. */
+    async titleFromPrompt(session, description) {
+        const info = await this.readSessionInfo(session);
+        if (this.agent.sessions[this.sessionId] !== session || this.explicit.active) {
+            return;
+        }
+        if (info?.customTitle) {
+            this.context = undefined;
+            await this.publish(info.customTitle, info.lastModified);
+            return;
+        }
+        const fallback = info?.summary
+            ? { title: info.summary, lastModified: info.lastModified }
+            : undefined;
+        await this.requestGenerateTitle(session, description, fallback);
+    }
+    /** Generate a title from `description` and publish it. `persist` writes it
+     *  to the session file, which is what carries it into `session/list` and
+     *  `session/load`. A null or failed generation releases the latch so a later
+     *  prompt or turn end retries, and publishes `fallback` (the stored summary)
+     *  so a backend that can't generate titles is no worse off than before. */
+    async requestGenerateTitle(session, description, fallback) {
         let title = null;
         try {
             title =

package/dist/subagent-replay.d.ts

@@ -8,6 +8,13 @@
  * history to the child session. Every child's end goes out before the replay
  * ends, since no subagent from before the reload still runs.
  *
+ * As live, the parent is not shown the Agent or Task call of a child that the
+ * replay announces: the launch's prompt is the parent's outgoing message, and
+ * a foreground child's answer is its reply to the parent. A child's
+ * successful SubagentHandback call is its message to the parent instead.
+ * Unlike live, the replay does not tell runs apart, so a child that handed
+ * back any report gets no reply from its launch's result.
+ *
  * A launch without metadata has no known id, so it is not announced: the RFD
  * forbids inventing one. Its Agent call stays an ordinary tool call of the
  * parent, and a notice says that subagent history is missing.
@@ -33,6 +40,8 @@ export type ReplayChild = {
     notified?: SubagentState;
     announced: boolean;
     promptSent: boolean;
+    /** Whether it handed a report to its parent with a SubagentHandback call. */
+    handedBack?: boolean;
 };
 export declare class RfdSubagentReplay {
     private readonly history;
@@ -45,6 +54,8 @@ export declare class RfdSubagentReplay {
     private readonly omitted;
     /** Children whose transcript could not be read: only their association is replayed. */
     private withoutHistory;
+    /** The SubagentHandback calls, with their report and whether their result failed. */
+    private readonly handbacks;
     constructor(history: SubagentHistory, publish: Publish);
     /**
      * Registers the launches, the launch results, and the SendMessage calls in
@@ -73,6 +84,15 @@ export declare class RfdSubagentReplay {
      * comes from the launch call.
      */
     childReplayed(child: ReplayChild, messages: readonly SessionMessage[]): Promise<void>;
+    /**
+     * Takes a replayed update of a tool call, from the transcript of `owner`
+     * when it is a child's. Returns whether the client is not shown it: an
+     * update of the launch of a child that the replay shows, or of a successful
+     * SubagentHandback call of `owner`. A foreground launch's completed result
+     * goes out as the child's reply, and a hand-back as the child's message to
+     * its parent.
+     */
+    toolCallUpdate(update: AcpSessionNotification["update"], owner: ReplayChild | undefined): Promise<boolean>;
     /**
      * Takes a persisted task notification. Returns whether it was a child's:
      * its task id is the agent id.
@@ -86,7 +106,7 @@ export declare class RfdSubagentReplay {
      */
     finish(supportsNotices: boolean, rootSessionId: string): Promise<void>;
     private registerLaunch;
-    /** The prompt of the launch, with the launch's id, as live. */
+    /** The prompt of the launch, with the launch's id, to the parent and the child, as live. */
     private sendPrompt;
     /**
      * A message that a SendMessage call delivered. Claude Code frames it for the

package/dist/subagent-replay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subagent-replay.d.ts","sourceRoot":"","sources":["../src/subagent-replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAShF,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE7E,KAAK,OAAO,GAAG,CAAC,YAAY,EAAE,sBAAsB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEvE,8DAA8D;AAC9D,MAAM,MAAM,WAAW,GAAG;IACxB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB,wCAAwC;IACxC,eAAe,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,mEAAmE;IACnE,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAUF,qBAAa,iBAAiB;IAW1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAX1B,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAC5D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;IACtD,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,uFAAuF;IACvF,OAAO,CAAC,cAAc,CAAK;gBAGR,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,OAAO;IAGnC;;;OAGG;IACH,IAAI,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI;IA6BvE,kFAAkF;IAClF,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIzD,mFAAmF;IAC7E,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBjD;;;;;;;;;;OAUG;IACG,YAAY,CAChB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,OAAO,CAAC;IAanB;;;;OAIG;IACG,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3F;;;OAGG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAOzD;;;;;OAKG;IACG,MAAM,CAAC,eAAe,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B5E,OAAO,CAAC,cAAc;IAwBtB,+DAA+D;YACjD,UAAU;IAKxB;;;;;;;OAOG;YACW,YAAY;YAoBZ,WAAW;CAiB1B;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,WAAW,GAAG,QAAQ,GAAG,WAAW,CAMtC"}
+{"version":3,"file":"subagent-replay.d.ts","sourceRoot":"","sources":["../src/subagent-replay.ts"],"names":[],"mappings":"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"}

package/dist/subagent-replay.js

@@ -1,4 +1,4 @@
-import { isNativeSubagentControlTool, nativeSubagentState, rfdEndState, rfdLabels, } from "./native-subagents.js";
+import { HANDBACK_TOOL, handbackMessage, isNativeSubagentControlTool, launchReply, linkedSessionMessages, nativeSubagentState, rfdEndState, rfdLabels, } from "./native-subagents.js";
 import { noticeUpdate } from "./session-notices.js";
 export class RfdSubagentReplay {
     history;
@@ -11,6 +11,8 @@ export class RfdSubagentReplay {
     omitted = new Set();
     /** Children whose transcript could not be read: only their association is replayed. */
     withoutHistory = 0;
+    /** The SubagentHandback calls, with their report and whether their result failed. */
+    handbacks = new Map();
     constructor(history, publish) {
         this.history = history;
         this.publish = publish;
@@ -26,6 +28,11 @@ export class RfdSubagentReplay {
                     if (isNativeSubagentControlTool(block.name)) {
                         this.registerLaunch(block.id, inputOf(block), ownerSessionId);
                     }
+                    else if (block.name === HANDBACK_TOOL) {
+                        const message = handbackMessage(block.input);
+                        if (message)
+                            this.handbacks.set(block.id, { message, failed: false, sent: false });
+                    }
                     else if (block.name === "SendMessage") {
                         const input = inputOf(block);
                         if (typeof input.to === "string" && typeof input.message === "string") {
@@ -40,6 +47,9 @@ export class RfdSubagentReplay {
                     }
                 }
                 else if (block.type === "tool_result" && typeof block.tool_use_id === "string") {
+                    const handback = this.handbacks.get(block.tool_use_id);
+                    if (handback && block.is_error === true)
+                        handback.failed = true;
                     const child = this.children.get(block.tool_use_id);
                     // A background launch answers at once; its result is not the end.
                     if (child && !child.record.background) {
@@ -106,6 +116,42 @@ export class RfdSubagentReplay {
             await this.sendPrompt(child, child.input.prompt);
         }
     }
+    /**
+     * Takes a replayed update of a tool call, from the transcript of `owner`
+     * when it is a child's. Returns whether the client is not shown it: an
+     * update of the launch of a child that the replay shows, or of a successful
+     * SubagentHandback call of `owner`. A foreground launch's completed result
+     * goes out as the child's reply, and a hand-back as the child's message to
+     * its parent.
+     */
+    async toolCallUpdate(update, owner) {
+        if (update.sessionUpdate !== "tool_call" && update.sessionUpdate !== "tool_call_update") {
+            return false;
+        }
+        const handback = owner ? this.handbacks.get(update.toolCallId) : undefined;
+        if (owner && handback && !handback.failed) {
+            if (!handback.sent) {
+                handback.sent = true;
+                owner.handedBack = true;
+                for (const view of linkedSessionMessages(update.toolCallId, owner.sessionId, owner.parentSessionId, handback.message)) {
+                    await this.publish(view);
+                }
+            }
+            return true;
+        }
+        const child = this.children.get(update.toolCallId);
+        if (!child)
+            return false;
+        if (update.status === "completed" &&
+            child.announced &&
+            !child.record.background &&
+            !child.handedBack) {
+            const reply = launchReply(child.launchId, child.sessionId, child.parentSessionId, update);
+            if (reply)
+                await this.publish(reply);
+        }
+        return true;
+    }
     /**
      * Takes a persisted task notification. Returns whether it was a child's:
      * its task id is the agent id.
@@ -168,10 +214,12 @@ export class RfdSubagentReplay {
         this.children.set(toolUseId, child);
         this.byAgentId.set(record.agentId, child);
     }
-    /** The prompt of the launch, with the launch's id, as live. */
+    /** The prompt of the launch, with the launch's id, to the parent and the child, as live. */
     async sendPrompt(child, text) {
         child.promptSent = true;
-        await this.sendMessage(child, child.launchId, text, child.parentSessionId);
+        for (const view of linkedSessionMessages(child.launchId, child.parentSessionId, child.sessionId, text)) {
+            await this.publish(view);
+        }
     }
     /**
      * A message that a SendMessage call delivered. Claude Code frames it for the

package/dist/task-notifications.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The `<task-notification>` inputs that Claude Code writes to a transcript
+ * when a background task stops. The replay of a session (`acp-agent.ts`) and
+ * the session index (`session-index/background-tasks.ts`) read them here, so
+ * both read the same fields.
+ */
+export declare const TASK_NOTIFICATION_TAG = "task-notification";
+/** The text between the first `<tag>` and the next `</tag>` after it. */
+export declare function markerTagText(text: string, tag: string): string | undefined;
+/** The fields of a persisted `<task-notification>`, in the shape of the SDK
+ *  `task_notification` frame that reported the same stop live. */
+export type PersistedTaskNotification = {
+    task_id: string;
+    status: string;
+    tool_use_id?: string;
+    summary?: string;
+    output_file?: string;
+};
+/**
+ * Returns each `<task-notification>` in user-message content (a string or its
+ * text blocks). The `<result>` body is model context that the live frame does
+ * not carry, so the scan stops at it and a tag quoted in it cannot match.
+ *
+ * Only a notification with a `<task-id>` and a `<status>` is returned. A
+ * notification without a status comes while its task still runs: the
+ * check-in of a quiet shell ("is still running after …") or a `Monitor`
+ * event.
+ */
+export declare function taskNotificationsOf(content: unknown): PersistedTaskNotification[];
+//# sourceMappingURL=task-notifications.d.ts.map

package/dist/task-notifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-notifications.d.ts","sourceRoot":"","sources":["../src/task-notifications.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAEzD,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQ3E;AAED;kEACkE;AAClE,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,yBAAyB,EAAE,CAkCjF"}

package/dist/task-notifications.js

@@ -0,0 +1,62 @@
+/**
+ * The `<task-notification>` inputs that Claude Code writes to a transcript
+ * when a background task stops. The replay of a session (`acp-agent.ts`) and
+ * the session index (`session-index/background-tasks.ts`) read them here, so
+ * both read the same fields.
+ */
+export const TASK_NOTIFICATION_TAG = "task-notification";
+/** The text between the first `<tag>` and the next `</tag>` after it. */
+export function markerTagText(text, tag) {
+    const open = `<${tag}>`;
+    const close = `</${tag}>`;
+    const start = text.indexOf(open);
+    if (start === -1)
+        return undefined;
+    const end = text.indexOf(close, start + open.length);
+    if (end === -1)
+        return undefined;
+    return text.slice(start + open.length, end);
+}
+/**
+ * Returns each `<task-notification>` in user-message content (a string or its
+ * text blocks). The `<result>` body is model context that the live frame does
+ * not carry, so the scan stops at it and a tag quoted in it cannot match.
+ *
+ * Only a notification with a `<task-id>` and a `<status>` is returned. A
+ * notification without a status comes while its task still runs: the
+ * check-in of a quiet shell ("is still running after …") or a `Monitor`
+ * event.
+ */
+export function taskNotificationsOf(content) {
+    const texts = typeof content === "string"
+        ? [content]
+        : Array.isArray(content)
+            ? content.flatMap((block) => block?.type === "text" && typeof block.text === "string" ? [block.text] : [])
+            : [];
+    const open = `<${TASK_NOTIFICATION_TAG}>`;
+    const close = `</${TASK_NOTIFICATION_TAG}>`;
+    const notifications = [];
+    for (const text of texts) {
+        let start = text.indexOf(open);
+        while (start !== -1) {
+            const end = text.indexOf(close, start + open.length);
+            if (end === -1)
+                break;
+            const body = text.slice(start + open.length, end).split("<result>", 1)[0];
+            const field = (tag) => markerTagText(body, tag)?.trim() || undefined;
+            const taskId = field("task-id");
+            const status = field("status");
+            if (taskId && status) {
+                notifications.push({
+                    task_id: taskId,
+                    status,
+                    tool_use_id: field("tool-use-id"),
+                    summary: field("summary"),
+                    output_file: field("output-file"),
+                });
+            }
+            start = text.indexOf(open, end + close.length);
+        }
+    }
+    return notifications;
+}

package/package.json

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