@agentclientprotocol/claude-agent-acp 0.99.2-preview.9 → 0.100.1-preview.1

package/dist/acp-agent.js

@@ -9,6 +9,7 @@ import { childModelOption, isNativeSubagentControlTool, isNativeSubagentControlU
 import { AIR_ASYNC_TASKS_CAPABILITY, AIR_BACKGROUND_SUBAGENTS_CAPABILITY, AIR_CUSTOM_INSTRUCTIONS_CAPABILITY, airCustomInstructions, AIR_DIFF_PATCH_CAPABILITY, AIR_PLAN_FILE_CAPABILITY, AIR_GOAL_KEY, AIR_KIND_KEY, AIR_LOAD_REPLAY_END_CAPABILITY, AIR_LOAD_REPLAY_END_KEY, AIR_RECOMMENDED_CONFIG_VALUE_CAPABILITY, AIR_SKILL_PATH_KEY, clientSupportsAirCapability, withAirMeta, } from "./air-extension.js";
 import * as sessionIndex from "./session-index/connection.js";
 import { AsyncTaskRuntime, backgroundBashTaskFromToolResult, backgroundedBashToolCallIds, clientSupportsAsyncTasks, } from "./async-tasks.js";
+import { backgroundLevel, backgroundToolCallPause, backgroundToolCallStates, BackgroundWorkReporter, cancelBackgroundWork, droppedTasks, endBackgroundWork, finishBackgroundTerminalOutput, followBackgroundTerminalOutput, registerBackgroundToolCalls, takeBackgroundTerminalExit, takeBackgroundToolCallEnd, } from "./background-work.js";
 import { AUTH_STATUS_PROBE_TIMEOUT_MS, AUTH_STATUS_UPDATE_METHOD, authStatusCapability, fromAccountInfo, fromCliStatus, gatewayAuthStatus, mergeAuthStatus, notLoggedInAuthStatus, sameAuthStatus, } from "./auth-status.js";
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -36,7 +37,7 @@ import { ContextCompactionLifecycle, clientSupportsCompactionUpdates, contextCom
 import { clientSupportsNotices, MAX_NOTICE_TITLE_LENGTH, normalizeNoticeText, noticeOrTranscriptUpdate, sentenceCase, splitNoticeText, } from "./session-notices.js";
 import { applyTaskCreate, applyTaskList, applyTaskUpdate, clearHookCallbacks, completeHookCallback, createPostToolUseHook, hasHookCallback, createTaskHook, parseTaskCreateOutput, parseTaskListOutput, parseTaskUpdateOutput, planEntries, registerHookCallback, changedTaskPlanEntries, forgetPublishedTaskPlan, unregisterHookCallback, } from "./tools.js";
 import { previewPatchContent } from "./diff.js";
-import { backgroundedBashToolCall, withRunningTerminal } from "./tool-calls/background.js";
+import { backgroundedBashToolCall, withRunningTerminal, withRunningToolCall, } from "./tool-calls/background.js";
 import { ChangedMetaFilter } from "./tool-calls/changed-meta-filter.js";
 import { ToolCallFieldTracker } from "./tool-calls/field-tracker.js";
 import { ClientCapabilities as ToolCallClientCapabilities } from "./tool-calls/client-capabilities.js";
@@ -55,6 +56,7 @@ import { applyAvailableModelsAllowlist, buildModelConfigOption, getAvailableMode
 import { GatewayListingError, listBedrockModels, listGatewayModels, PROVIDER_AUTH_TOKEN_PLACEHOLDER, selectBedrockRegion, } from "./gateway-models.js";
 import { buildEffortConfigOption, EFFORT_CONFIG_ID, effortFlagSettings, effortLevelName, mergeEffortSettings, settingsEffortForModel, } from "./session-effort.js";
 import { createUltracodeConfigOption, readUltracodeSettings, resolveUltracodeEnabled, ULTRACODE_CONFIG_ID, ultracodeSupported, ultracodeWorkflowsEnabled, } from "./session-ultracode.js";
+import { STARTUP_FAILURE_RESULTS_ENV, startupFailureError } from "./startup-failure.js";
 export { EFFORT_CONFIG_ID, settingsEffortForModel } from "./session-effort.js";
 export { applyAvailableModelsAllowlist, matchResumedModel, MODEL_CONFIG_ID, resolveModelPreference, } from "./session-model.js";
 const execFileAsync = promisify(execFile);
@@ -954,6 +956,7 @@ class ClientConnection {
     requestPermission(params, signal) {
         return this.ctx.request(methods.client.session.requestPermission, params, {
             cancellationSignal: signal,
+            stopWaitingOnCancel: true,
         });
     }
     readTextFile(params) {
@@ -965,6 +968,7 @@ class ClientConnection {
     createElicitation(params, signal) {
         return this.ctx.request(methods.client.elicitation.create, params, {
             cancellationSignal: signal,
+            stopWaitingOnCancel: true,
         });
     }
     completeElicitation(params) {
@@ -1222,6 +1226,8 @@ export class ClaudeAcpAgent {
     replayedChildModels = new Map();
     /** See the `foreground` constructor option. */
     foregroundEvents;
+    /** See the `background` constructor option. */
+    backgroundWork;
     /** Counts the prompts `startTurn()` has received, across sessions. */
     promptsReceived = 0;
     /** Per session, the `promptsReceived` count when its last cancel started.
@@ -1256,6 +1262,7 @@ export class ClaudeAcpAgent {
     constructor(client, logger, options = {}) {
         this.v2 = options.v2 ?? false;
         this.foregroundEvents = options.foreground;
+        this.backgroundWork = new BackgroundWorkReporter(options.background);
         this.sessions = {};
         this.client = new ChangedMetaClient(client, () => this.toolCallCapabilities.air.client);
         this.logger = logger ?? console;
@@ -3431,28 +3438,18 @@ export class ClaudeAcpAgent {
             }
             this.syncAwaitingUser(params.sessionId, session);
         };
-        /** Ends the display terminal of a command that went to the background, once
-         *  its task ends (see `Session.backgroundTerminals`). Claude Code reports no
-         *  exit code for it, and `completed` does not mean 0: Claude Code accepts
-         *  some non-zero codes as a success, such as grep's 1. */
-        const endBackgroundTerminal = async (taskId) => {
-            const terminal = session.backgroundTerminals?.get(taskId);
-            if (!terminal)
-                return;
-            session.backgroundTerminals.delete(taskId);
-            await sendUpdate({
-                sessionId: params.sessionId,
-                update: {
-                    sessionUpdate: "tool_call_update",
-                    toolCallId: terminal.toolCallId,
-                    _meta: {
-                        ...(terminal.parentToolUseId
-                            ? { claudeCode: { parentToolUseId: terminal.parentToolUseId } }
-                            : {}),
-                        terminal_exit: { terminal_id: terminal.toolCallId, exit_code: null, signal: null },
-                    },
-                },
-            });
+        /** Ends the display terminal of a command that went to the background, and
+         *  gives a tool call whose task went on in the background its final
+         *  status, once the task ends (see `Session.backgroundTerminals` and
+         *  `Session.backgroundToolCalls`). */
+        const endBackgroundTask = async (taskId, end) => {
+            await finishBackgroundTerminalOutput(session, taskId);
+            const exit = takeBackgroundTerminalExit(session, params.sessionId, taskId);
+            if (exit)
+                await sendUpdate(exit);
+            const toolCallEnd = takeBackgroundToolCallEnd(session, params.sessionId, taskId, end);
+            if (toolCallEnd)
+                await sendUpdate(toolCallEnd);
         };
         /** Settles a task. Its request may still be open, and an agent without a
          *  record no longer blocks the foreground work, so that is checked again. */
@@ -3932,6 +3929,9 @@ export class ClaudeAcpAgent {
                 const pause = messageLoopYielder.maybeYield();
                 if (pause)
                     await pause;
+                // The last message may have changed the background work, and its
+                // updates are sent, so the list follows them.
+                this.backgroundWork.sync(params.sessionId, session, this.foregroundState(params.sessionId));
                 pendingNext ??= session.query
                     .next()
                     .then((result) => ({ kind: "message", result }));
@@ -4763,7 +4763,7 @@ export class ClaudeAcpAgent {
                                     streamedBlocksByParent.delete(message.tool_use_id);
                                     droppedStreams.delete(message.tool_use_id);
                                 }
-                                await endBackgroundTerminal(message.task_id);
+                                await endBackgroundTask(message.task_id, message.status);
                                 if (message.status === "stopped") {
                                     await closeStoppedSubagentToolCalls(message.tool_use_id);
                                 }
@@ -4797,14 +4797,22 @@ export class ClaudeAcpAgent {
                                         streamedBlocksByParent.delete(parentToolUseId);
                                         droppedStreams.delete(parentToolUseId);
                                     }
-                                    await endBackgroundTerminal(message.task_id);
+                                    await endBackgroundTask(message.task_id, message.patch.status === "killed" ? "stopped" : message.patch.status);
                                     if (message.patch.status === "killed") {
                                         await closeStoppedSubagentToolCalls(parentToolUseId);
                                     }
                                     settleLiveTask(message.task_id);
                                 }
+                                else if (message.patch.status === "paused") {
+                                    const pause = backgroundToolCallPause(session, params.sessionId, message.task_id, true);
+                                    if (pause)
+                                        await sendUpdate(pause);
+                                }
                                 else if (message.patch.status === "running" ||
                                     message.patch.status === "pending") {
+                                    const resume = backgroundToolCallPause(session, params.sessionId, message.task_id, false);
+                                    if (resume)
+                                        await sendUpdate(resume);
                                     // The SDK can resume a finished subagent under the same
                                     // agent id without a new task_started.
                                     resumeLiveTask(message.task_id);
@@ -4958,8 +4966,15 @@ export class ClaudeAcpAgent {
                             // control requests, which this adapter never issues.
                             case "control_request_progress":
                                 break;
-                            case "background_tasks_changed":
+                            case "background_tasks_changed": {
                                 await asyncTasks.backgroundTasksChanged(message.tasks);
+                                if (session.reportsBackground) {
+                                    const level = backgroundLevel(message.tasks);
+                                    for (const taskId of droppedTasks(session, level)) {
+                                        await endBackgroundTask(taskId, undefined);
+                                    }
+                                    session.backgroundLevel = level;
+                                }
                                 // A level signal: the full live background-task set on every
                                 // membership change, with REPLACE semantics. Used only to
                                 // reconcile `liveBackgroundTasks` — dropping (or, for
@@ -5004,6 +5019,7 @@ export class ClaudeAcpAgent {
                                     }
                                 }
                                 break;
+                            }
                             default:
                                 unreachable(message, this.logger);
                                 break;
@@ -6142,6 +6158,8 @@ export class ClaudeAcpAgent {
                         const acceptedPlanToolUseId = observeExitPlanToolResults(message, content, session);
                         let backgroundedToolCalls = new Set();
                         let runningTerminal;
+                        let runningTerminalTask;
+                        let runningToolCalls = new Set();
                         if (message.type === "user") {
                             rememberResolvedToolNames(session, content);
                             recordSubagentFileEdits(session.activeTurn, message.parent_tool_use_id, content, session.toolUseCache);
@@ -6162,8 +6180,13 @@ export class ClaudeAcpAgent {
                                     ...(message.parent_tool_use_id
                                         ? { parentToolUseId: message.parent_tool_use_id }
                                         : {}),
+                                    ...(backgroundBashTask.outputFilePath
+                                        ? { outputFilePath: backgroundBashTask.outputFilePath }
+                                        : {}),
                                 });
+                                runningTerminalTask = backgroundBashTask.taskId;
                             }
+                            runningToolCalls = registerBackgroundToolCalls(session, content, toolUseResult, session.toolUseCache, message.parent_tool_use_id);
                             await asyncTasks.toolResults(content);
                             backgroundedToolCalls = backgroundedBashToolCallIds(content, session.toolUseCache, asyncTasks, backgroundBashTask);
                             const resumedAgentId = resumedNativeSubagentId(toolUseResult);
@@ -6199,7 +6222,14 @@ export class ClaudeAcpAgent {
                             // filtered out of `content` above; blocks that do pass through
                             // (e.g. a subagent image) carry the stamped parentToolUseId
                             // meta and are excluded there.
-                            await sendUpdate(withRunningTerminal(backgroundedBashToolCall(acceptedPlanToolResult(notification, acceptedPlanToolUseId), backgroundedToolCalls, asyncTasks.enabled), runningTerminal));
+                            await sendUpdate(withRunningToolCall(withRunningTerminal(backgroundedBashToolCall(acceptedPlanToolResult(notification, acceptedPlanToolUseId), backgroundedToolCalls, asyncTasks.enabled), runningTerminal), runningToolCalls));
+                        }
+                        // After the result's own updates: the command's output replaces
+                        // the placeholder that they gave its terminal.
+                        if (runningTerminalTask) {
+                            followBackgroundTerminalOutput(session, params.sessionId, runningTerminalTask, (notification) => sendUpdate(notification).catch((error) => {
+                                this.logger.error(`Session ${params.sessionId}: failed to send background command output:`, error);
+                            }));
                         }
                         break;
                     }
@@ -6847,10 +6877,18 @@ export class ClaudeAcpAgent {
             return;
         }
         session.queryClosed = true;
-        // Its list row now shows what the registry and the transcript tell.
         for (const [sessionId, candidate] of Object.entries(this.sessions)) {
-            if (candidate === session)
-                this.sessionIndex.onOwnSessionChanged(sessionId);
+            if (candidate !== session)
+                continue;
+            // Its list row now shows what the registry and the transcript tell.
+            this.sessionIndex.onOwnSessionChanged(sessionId);
+            // Its background tasks end with the query's process.
+            for (const exit of endBackgroundWork(session, sessionId)) {
+                this.client.sessionUpdate(exit).catch((error) => {
+                    this.logger.error(`Session ${sessionId}: failed to end a background terminal:`, error);
+                });
+            }
+            this.backgroundWork.sync(sessionId, session, this.foregroundState(sessionId));
         }
         session.consumer = undefined;
         session.contextCompaction = undefined;
@@ -6904,6 +6942,7 @@ export class ClaudeAcpAgent {
         session.asyncTaskRuntime?.clear();
         this.replayedChildModels.delete(sessionId);
         this.cancelledThrough.delete(sessionId);
+        this.backgroundWork.forget(sessionId);
         delete this.sessions[sessionId];
         this.sessionIndex.onTeardown(sessionId);
         const ended = await raceTimeoutAndAbort(turnsEnded, TEARDOWN_TURN_END_TIMEOUT_MS, new AbortController().signal);
@@ -6942,6 +6981,57 @@ export class ClaudeAcpAgent {
         await this.teardownSession(params.sessionId);
         return {};
     }
+    /** Stops a command running in the background (v2 `terminal/cancel`, see
+     *  {@link cancelBackgroundWork}). */
+    cancelBackgroundTerminal(params) {
+        return cancelBackgroundWork(this.sessions, params.sessionId, {
+            terminalId: params.terminalId,
+        });
+    }
+    /** Stops the task of a tool call running in the background (v2
+     *  `tool_call/cancel`, see {@link cancelBackgroundWork}). */
+    cancelBackgroundToolCall(params) {
+        return cancelBackgroundWork(this.sessions, params.sessionId, {
+            toolCallId: params.toolCallId,
+        });
+    }
+    /** Sends the current state of each tool call in `toolCallIds` that the root
+     *  session `sessionId` runs in the background: the call as its tool use
+     *  shows it, with its status now. v2 requires it for each tool call that a
+     *  `session/resume` snapshot lists. A failure is logged, as for
+     *  {@link publishLiveSubagents}. */
+    async publishBackgroundToolCalls(sessionId, toolCallIds) {
+        const session = this.sessions[sessionId];
+        if (!session)
+            return;
+        const renderer = new AcpToolCallRenderer(this.toolCallCapabilities);
+        try {
+            for (const update of backgroundToolCallStates(session, sessionId, toolCallIds, renderer)) {
+                await this.client.sessionUpdate(update);
+            }
+        }
+        catch (error) {
+            this.logger.error(`Session ${sessionId}: failed to send background tool calls:`, error);
+        }
+    }
+    /** Sends the current `subagent_update` of each live subagent session in
+     *  `children`, of the session `sessionId` (see
+     *  {@link NativeSubagentRuntime.currentUpdate}). v2 requires it for each
+     *  child that a `session/resume` snapshot lists. A failure is logged, as
+     *  for {@link publishCurrentSubagentStates}. */
+    async publishLiveSubagents(sessionId, children) {
+        const runtime = this.sessions[sessionId]?.nativeSubagentRuntime;
+        try {
+            for (const child of children) {
+                const update = runtime?.currentUpdate(child);
+                if (update)
+                    await this.client.sessionUpdate(asSdkSessionNotification(update));
+            }
+        }
+        catch (error) {
+            this.logger.error(`Session ${sessionId}: failed to send current subagent states:`, error);
+        }
+    }
     /** Per client: see {@link sessionIndex.SessionIndexConnection.deleteSession}. */
     async deleteSession(params) {
         return this.sessionIndex.deleteSession(params);
@@ -7739,10 +7829,9 @@ export class ClaudeAcpAgent {
     /** Forward a permission request to the client, wiring the tool call's
      *  `signal` through as a `cancellationSignal`. When the turn is cancelled
      *  while the client's prompt is still open the signal aborts, the SDK sends
-     *  `$/cancel_request`, and our local abort race settles even if the client
-     *  ignores it. A request rejection and a local abort surface the same
-     *  "Tool use aborted" that the callers expect. `canUseTool` decides what a
-     *  `cancelled` outcome means. */
+     *  `$/cancel_request` and stops waiting for the client's answer. The
+     *  rejection surfaces as the "Tool use aborted" that the callers expect.
+     *  `canUseTool` decides what a `cancelled` outcome means. */
     async requestPermissionFromClient(params, toolName, toolSignal, parentToolUseId, ownerSessionId, agentID, toolInput, previewContent) {
         const signal = this.untilSessionClosed(ownerSessionId, toolSignal);
         if (signal.aborted)
@@ -7756,13 +7845,10 @@ export class ClaudeAcpAgent {
         await this.ensureToolCallEmitted(ownerSessionId, toolName, params.toolCall.toolCallId, toolInput, parentToolUseId, signal, params.sessionId, previewContent);
         if (signal.aborted)
             throw new Error("Tool use aborted");
-        // Do not rely on every ACP client settling requestPermission after the
-        // cancellation signal. The local race guarantees that Claude's tool call
-        // is released even when an older or broken client ignores $/cancel_request.
         // The request goes to a subagent's child session for a tool call of that
         // subagent, but it blocks the turn of the owner session.
         try {
-            return await this.withChildAwaitingUser(ownerSessionId, params.sessionId, signal, () => this.withPendingUserInput(ownerSessionId, signal, () => raceWithAbort(this.client.requestPermission(params, signal), signal), agentID));
+            return await this.withChildAwaitingUser(ownerSessionId, params.sessionId, signal, () => this.withPendingUserInput(ownerSessionId, signal, () => this.client.requestPermission(params, signal), agentID));
         }
         catch (error) {
             if (signal.aborted) {
@@ -7772,21 +7858,20 @@ export class ClaudeAcpAgent {
         }
     }
     /** Send the client an elicitation for a callback of Claude Code. When the
-     *  callback's `signal` aborts, the SDK sends `$/cancel_request` and keeps
-     *  waiting for the client's reply, which a client that ignores the cancel
-     *  never sends. So the call also rejects at once on the abort, as
-     *  {@link requestPermissionFromClient} does for a permission request. Left
-     *  open, the request would stay in `openUserInputs` (see
-     *  {@link withPendingUserInput}), which keeps steering non-interrupting, and
-     *  a child's `openRequests` would not drop. */
+     *  callback's `signal` aborts, the SDK sends `$/cancel_request` and the call
+     *  rejects at once, without waiting for a reply that a client ignoring the
+     *  cancel never sends. Left open, the request would stay in
+     *  `openUserInputs` (see {@link withPendingUserInput}), which keeps steering
+     *  non-interrupting, and a child's `openRequests` would not drop. */
     elicitFromClient(request, signal) {
-        return raceWithAbort(this.client.createElicitation(request, signal), signal);
+        return this.client.createElicitation(request, signal);
     }
     /** `signal`, also aborted when `teardownSession` aborts the
      *  `abortController` of session `sessionId`. Claude Code aborts a callback's
      *  own signal when its query closes, but not necessarily before
-     *  `session/close` responds, and v2 requires every pending elicitation of
-     *  the session to be cancelled with `$/cancel_request` before that response. */
+     *  `session/close` responds, and v2 requires every pending permission
+     *  request and elicitation of the session to be cancelled with
+     *  `$/cancel_request` before that response. */
     untilSessionClosed(sessionId, signal) {
         const sessionSignal = this.sessions[sessionId]?.abortController?.signal;
         return sessionSignal ? AbortSignal.any([signal, sessionSignal]) : signal;
@@ -9118,6 +9203,7 @@ export class ClaudeAcpAgent {
             ...providerEnv,
             // Opt-in to session state events like when the agent is idle
             CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: "1",
+            ...STARTUP_FAILURE_RESULTS_ENV,
         };
         // Scopes the context-window cache to this query's backend (see
         // `contextWindowCache`). Derived from the same `env` object handed to the
@@ -9362,7 +9448,7 @@ export class ClaudeAcpAgent {
                         error.message.includes("No conversation found with session ID"))) {
                     throw RequestError.sessionNotFound(sessionId);
                 }
-                throw error;
+                throw startupFailureError(error) ?? error;
             }
             timing.phase("sdk-initialize");
             // Publish the identity BEFORE the guard can refuse this session. A
@@ -9586,7 +9672,9 @@ export class ClaudeAcpAgent {
                 emittedToolCalls: new Set(),
                 eagerToolCallSessions: new Map(),
                 liveBackgroundTasks: new Map(),
+                reportsBackground: this.backgroundWork.enabled && options.perTaskStopAffordance === true,
                 stopsWorkflowsOnCancel: options.perTaskStopAffordance === true &&
+                    !this.backgroundWork.enabled &&
                     !clientSupportsAsyncTasks(this.clientCapabilities),
                 nativeSubagentsByTaskId: new Map(),
                 nativeSubagentTaskIdByToolUseId: new Map(),
@@ -9600,6 +9688,7 @@ export class ClaudeAcpAgent {
                 fileChangeReporter,
             };
             timing.phase("register");
+            this.backgroundWork.sync(sessionId, this.sessions[sessionId], this.foregroundState(sessionId));
             this.refreshContextWindowInBackground(sessionId, this.sessions[sessionId]);
             return {
                 sessionId,

package/dist/background-output.d.ts

@@ -0,0 +1,54 @@
+/** How often a running command's output file is read. */
+export declare const BACKGROUND_OUTPUT_POLL_MS = 500;
+/** The most bytes one read takes, so a burst of output does not block the loop. */
+export declare const BACKGROUND_OUTPUT_READ_BYTES: number;
+/**
+ * The most unread bytes that are still sent. A command that writes faster
+ * than the polls read falls behind. Past this, the reads skip to the file's
+ * last bytes, as a snapshot: a terminal shows the latest output, and a
+ * client keeps a bounded amount of it anyway.
+ */
+export declare const BACKGROUND_OUTPUT_MAX_BACKLOG_BYTES: number;
+/**
+ * Text that the file adds. A snapshot replaces the terminal's output so far:
+ * the first one replaces the placeholder of the Bash result, and a later one
+ * follows a skip or a file that shrank. Other text appends to it.
+ */
+export type BackgroundOutput = {
+    text: string;
+    replaces: boolean;
+};
+/**
+ * Follows the output file `path` of one background command and hands each
+ * piece of new text to `publish`, in order. Reads never overlap. A read that
+ * fails, for example because the file does not exist yet, is tried again at
+ * the next poll. `publish` must not reject: the next read waits for it.
+ */
+export declare class BackgroundOutputTail {
+    private readonly path;
+    private readonly publish;
+    private offset;
+    private decoder;
+    /** Whether the next text replaces the terminal's output. */
+    private replaces;
+    private stopped;
+    private reading;
+    private readonly timer;
+    constructor(path: string, publish: (output: BackgroundOutput) => Promise<void>);
+    /**
+     * Reads the rest of the file and stops. The command ended, so what the file
+     * holds is its whole output, and it goes out before the terminal's exit.
+     */
+    finish(): Promise<void>;
+    /** Stops without reading more: the session ended. */
+    stop(): void;
+    /**
+     * Reads what the file adds, one read of at most
+     * {@link BACKGROUND_OUTPUT_READ_BYTES} at a time, and publishes each read's
+     * text before the next. `toEnd` reads until the end of the file, and ends a
+     * character that the command cut off with a replacement character.
+     */
+    private read;
+    private send;
+}
+//# sourceMappingURL=background-output.d.ts.map

package/dist/background-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-output.d.ts","sourceRoot":"","sources":["../src/background-output.ts"],"names":[],"mappings":"AAcA,yDAAyD;AACzD,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C,mFAAmF;AACnF,eAAO,MAAM,4BAA4B,QAAa,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,mCAAmC,QAAc,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC;AAEnE;;;;;GAKG;AACH,qBAAa,oBAAoB;IAU7B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV1B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAA6B;IAC5C,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;gBAGpC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC;IAOvE;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B,qDAAqD;IACrD,IAAI,IAAI,IAAI;IAKZ;;;;;OAKG;IACH,OAAO,CAAC,IAAI;YA4CE,IAAI;CAKnB"}

package/dist/background-output.js

@@ -0,0 +1,122 @@
+/**
+ * The output of a command that went to the background, read from the file
+ * that Claude Code writes it to. Claude Code streams no output of such a
+ * command, so its display terminal would show only the placeholder of the
+ * Bash result ("Command running in background with ID …") until the command
+ * exits. ACP v2 asks an Agent to keep a listed terminal's output current
+ * whenever it can read it (the v2 prompt lifecycle, "Background work").
+ *
+ * The file is polled: watching a file is not reliable on every platform, and
+ * a missing file only means that nothing was written yet.
+ */
+import { open } from "node:fs/promises";
+import { StringDecoder } from "node:string_decoder";
+/** How often a running command's output file is read. */
+export const BACKGROUND_OUTPUT_POLL_MS = 500;
+/** The most bytes one read takes, so a burst of output does not block the loop. */
+export const BACKGROUND_OUTPUT_READ_BYTES = 256 * 1024;
+/**
+ * The most unread bytes that are still sent. A command that writes faster
+ * than the polls read falls behind. Past this, the reads skip to the file's
+ * last bytes, as a snapshot: a terminal shows the latest output, and a
+ * client keeps a bounded amount of it anyway.
+ */
+export const BACKGROUND_OUTPUT_MAX_BACKLOG_BYTES = 1024 * 1024;
+/**
+ * Follows the output file `path` of one background command and hands each
+ * piece of new text to `publish`, in order. Reads never overlap. A read that
+ * fails, for example because the file does not exist yet, is tried again at
+ * the next poll. `publish` must not reject: the next read waits for it.
+ */
+export class BackgroundOutputTail {
+    path;
+    publish;
+    offset = 0;
+    decoder = new StringDecoder("utf8");
+    /** Whether the next text replaces the terminal's output. */
+    replaces = true;
+    stopped = false;
+    reading = Promise.resolve();
+    timer;
+    constructor(path, publish) {
+        this.path = path;
+        this.publish = publish;
+        this.timer = setInterval(() => void this.read(false), BACKGROUND_OUTPUT_POLL_MS);
+        // A command that runs on must not keep the agent process alive.
+        this.timer.unref();
+    }
+    /**
+     * Reads the rest of the file and stops. The command ended, so what the file
+     * holds is its whole output, and it goes out before the terminal's exit.
+     */
+    async finish() {
+        clearInterval(this.timer);
+        await this.read(true);
+        this.stopped = true;
+    }
+    /** Stops without reading more: the session ended. */
+    stop() {
+        clearInterval(this.timer);
+        this.stopped = true;
+    }
+    /**
+     * Reads what the file adds, one read of at most
+     * {@link BACKGROUND_OUTPUT_READ_BYTES} at a time, and publishes each read's
+     * text before the next. `toEnd` reads until the end of the file, and ends a
+     * character that the command cut off with a replacement character.
+     */
+    read(toEnd) {
+        this.reading = this.reading.then(async () => {
+            if (this.stopped)
+                return;
+            let file;
+            try {
+                file = await open(this.path, "r");
+            }
+            catch {
+                // Nothing written yet, or the file is gone: try again at the next
+                // poll. At the end, the terminal keeps the output it has.
+                return;
+            }
+            try {
+                const { size } = await file.stat();
+                // A file that shrank is a new one: its output starts over. Past the
+                // backlog, the reads skip to the file's last bytes.
+                const start = size < this.offset ? 0 : this.offset;
+                const skipTo = Math.max(start, size - BACKGROUND_OUTPUT_MAX_BACKLOG_BYTES);
+                if (skipTo !== this.offset) {
+                    this.offset = skipTo;
+                    this.decoder = new StringDecoder("utf8");
+                    this.replaces = true;
+                }
+                const buffer = Buffer.alloc(BACKGROUND_OUTPUT_READ_BYTES);
+                let bytesRead;
+                do {
+                    ({ bytesRead } = await file.read(buffer, 0, buffer.length, this.offset));
+                    this.offset += bytesRead;
+                    const text = this.decoder.write(buffer.subarray(0, bytesRead));
+                    if (text !== "")
+                        await this.send(text);
+                } while (toEnd && bytesRead > 0);
+                if (toEnd) {
+                    const rest = this.decoder.end();
+                    // A command that wrote nothing still replaces the placeholder.
+                    if (rest !== "" || this.replaces)
+                        await this.send(rest);
+                }
+            }
+            catch {
+                // The read failed: try again at the next poll.
+            }
+            finally {
+                await file.close();
+            }
+        });
+        return this.reading;
+    }
+    async send(text) {
+        const replaces = this.replaces;
+        this.replaces = false;
+        await this.publish({ text, replaces });
+    }
+}