@lucascouts/claude-agent-acp-plus 0.25.3 → 0.27.0

package/dist/task-feed.js

@@ -27,9 +27,22 @@
  *
  * Neither class ever copies a command line (`SDKTaskStartedMessage.prompt`)
  * into an entry or a log line.
+ *
+ * Version 2 (story 041) adds `hasOutput` and `tail`. A shell task's output
+ * path — named by the Bash result while it runs, by `task_notification` when
+ * it ends — is kept beside the table, never on the wire. Once an ended shell
+ * task leaves the table, its path moves to a bounded registry so
+ * `_claude/tasks/output` can still serve it.
  */
+import { stat } from "node:fs/promises";
+import { readTail } from "./task-output.js";
 /** The `session_info_update._meta` key the snapshot is published under. */
 export const TASKS_META_KEY = "_claude/tasks";
+/** The `_claude/tasks` contract version advertised at `initialize`. Version 2
+ *  adds `hasOutput`, `tail` and `_claude/tasks/output`. */
+export const TASKS_CONTRACT_VERSION = 2;
+/** Ended shell outputs still servable per session, most recent kept. */
+export const ENDED_OUTPUTS_MAX = 256;
 /** How long a foreground shell task is held back before it is published. */
 export const FOREGROUND_SHELL_HOLD_MS = 5000;
 /** How long a running background task may be missing from the level before
@@ -104,6 +117,10 @@ export class TaskFeed {
     held = new Map();
     /** Shell task ids labelled by their tool call: a patch never relabels them. */
     toolDescribed = new Set();
+    /** Shell task id → its output file, while the task is in the table. */
+    outputs = new Map();
+    /** Ended shell outputs that left the table, oldest first; see `ENDED_OUTPUTS_MAX`. */
+    endedOutputs = new Map();
     constructor(clock, log = {}, sessionId = "") {
         this.clock = clock;
         this.log = log;
@@ -141,6 +158,8 @@ export class TaskFeed {
             usage: null,
             lastTool: null,
             summary: null,
+            hasOutput: false,
+            tail: null,
         };
         if (shell && msg.is_backgrounded !== true) {
             this.held.set(msg.task_id, entry);
@@ -194,6 +213,7 @@ export class TaskFeed {
             else {
                 if (normaliseStatus(msg.patch.status)) {
                     this.held.delete(msg.task_id);
+                    this.outputs.delete(msg.task_id);
                 }
                 else {
                     this.patch(heldEntry, msg.patch);
@@ -214,14 +234,19 @@ export class TaskFeed {
     }
     onNotification(msg) {
         // A held shell task that ends was never shown: its ending is not news.
-        if (this.held.delete(msg.task_id))
+        if (this.held.delete(msg.task_id)) {
+            this.outputs.delete(msg.task_id);
             return "none";
+        }
         const task = this.running(msg.task_id, "task_notification");
         if (!task)
             return "none";
         const ending = normaliseStatus(msg.status, msg.reason) ?? "completed";
         if (msg.summary)
             task.summary = msg.summary;
+        if (task.type === "shell" && typeof msg.output_file === "string" && msg.output_file !== "") {
+            this.outputs.set(task.id, msg.output_file);
+        }
         const usage = usageOf(msg.usage);
         if (usage)
             task.usage = usage;
@@ -273,6 +298,8 @@ export class TaskFeed {
     /** The CLI process restarted: whatever was running did not survive it. A
      *  held shell task was never shown, so it is dropped rather than ended. */
     onProcessRestart() {
+        for (const id of this.held.keys())
+            this.outputs.delete(id);
         this.held.clear();
         let change = "none";
         for (const task of this.tasks.values()) {
@@ -283,6 +310,69 @@ export class TaskFeed {
         }
         return change;
     }
+    /**
+     * Records the output file a Bash result named for a known shell task. Any
+     * other task, or an unknown id, is ignored: only a shell writes an output
+     * file, and only one the adapter recorded is ever read (R2.5).
+     */
+    onOutputPath(taskId, path) {
+        const task = this.tasks.get(taskId) ?? this.held.get(taskId);
+        if (!task || task.type !== "shell" || task.status !== "running") {
+            this.log.debug?.(`[tasks/feed] sessionId=${this.sessionId} taskId=${taskId} ignored=output_path`);
+            return "none";
+        }
+        this.outputs.set(taskId, path);
+        return "progress";
+    }
+    /**
+     * Sets a shell task's tail and whether its output reads. A running task
+     * keeps `lines`; an ended one keeps none, so this only confirms its output.
+     * Returns `"none"` when nothing changed, so an idle file publishes nothing.
+     */
+    setTail(taskId, lines, readable) {
+        const task = this.tasks.get(taskId);
+        if (!task || task.type !== "shell")
+            return "none";
+        // An ended task's output is decided by the ending's check alone: a poller
+        // tick that started before the ending and failed after it must not undo it.
+        if (task.status !== "running" && !readable)
+            return "none";
+        const tail = task.status === "running" && readable ? lines : null;
+        if (task.hasOutput === readable && sameLines(task.tail, tail))
+            return "none";
+        task.hasOutput = readable;
+        task.tail = tail === null ? null : [...tail];
+        return "progress";
+    }
+    /**
+     * The file the ending's existence check reads (R1.7), or null when there is
+     * nothing to check: `taskId` must be a running shell in the table. A non-empty
+     * `output_file` from the ending (the CLI's own) wins over the path the Bash result named.
+     * The caller checks BEFORE folding the ending in, so the snapshot that
+     * carries the ending already says whether the output can be served.
+     */
+    endingOutputPath(taskId, outputFile) {
+        const task = this.tasks.get(taskId);
+        if (!task || task.type !== "shell" || task.status !== "running")
+            return null;
+        if (typeof outputFile === "string" && outputFile !== "")
+            return outputFile;
+        return this.outputs.get(taskId) ?? null;
+    }
+    /** Running shell tasks with a recorded output file: the tail poller's work. */
+    runningOutputs() {
+        const work = [];
+        for (const [taskId, path] of this.outputs) {
+            const task = this.tasks.get(taskId);
+            if (task?.status === "running" && task.type === "shell")
+                work.push({ taskId, path });
+        }
+        return work;
+    }
+    /** The output file `_claude/tasks/output` may read for `taskId`, or null. */
+    outputPathFor(taskId) {
+        return this.outputs.get(taskId) ?? this.endedOutputs.get(taskId) ?? null;
+    }
     /** True when the feed holds `taskId` as running — the stop request's gate. */
     isRunning(taskId) {
         return this.tasks.get(taskId)?.status === "running";
@@ -293,7 +383,11 @@ export class TaskFeed {
         const tasks = [...this.tasks.values()]
             .filter((t) => t.status === "running" || !this.published.has(t.id))
             .sort((a, b) => a.startedAt - b.startedAt)
-            .map((t) => ({ ...t, usage: t.usage ? { ...t.usage } : null }));
+            .map((t) => ({
+            ...t,
+            usage: t.usage ? { ...t.usage } : null,
+            tail: t.tail ? [...t.tail] : null,
+        }));
         const endedIds = tasks.filter((t) => t.status !== "running").map((t) => t.id);
         for (const id of endedIds)
             this.snapshotLives.set(id, this.lives.get(id) ?? 0);
@@ -312,6 +406,7 @@ export class TaskFeed {
             this.snapshotLives.delete(id);
             this.published.add(id);
             this.tasks.delete(id);
+            this.retireOutput(id);
         }
     }
     running(taskId, kind) {
@@ -329,6 +424,12 @@ export class TaskFeed {
      *  state supersedes an ending the client has not seen yet, and a published
      *  id must be shown again. */
     admit(entry) {
+        // A new life writes a new file: the previous life's is not this one's. A
+        // held shell being promoted is the same life, and keeps the path it has.
+        if (this.tasks.has(entry.id) || this.published.has(entry.id)) {
+            this.outputs.delete(entry.id);
+            this.endedOutputs.delete(entry.id);
+        }
         this.published.delete(entry.id);
         this.lives.set(entry.id, (this.lives.get(entry.id) ?? 0) + 1);
         this.tasks.set(entry.id, entry);
@@ -345,8 +446,32 @@ export class TaskFeed {
     end(task, status, at = this.clock()) {
         task.status = status;
         task.endedAt = at;
+        // An ended task has no tail, and its output is claimed again only once the
+        // file was checked (R1.7).
+        task.tail = null;
+        task.hasOutput = false;
         this.deadlines.delete(task.id);
     }
+    /** Moves a task that left the table to the ended registry, newest last. */
+    retireOutput(taskId) {
+        const path = this.outputs.get(taskId);
+        this.outputs.delete(taskId);
+        if (path === undefined)
+            return;
+        this.endedOutputs.delete(taskId);
+        this.endedOutputs.set(taskId, path);
+        while (this.endedOutputs.size > ENDED_OUTPUTS_MAX) {
+            const oldest = this.endedOutputs.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.endedOutputs.delete(oldest);
+        }
+    }
+}
+function sameLines(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    return a.length === b.length && a.every((line, i) => line === b[i]);
 }
 const realTimers = {
     now: () => Date.now(),
@@ -528,3 +653,136 @@ export class TaskFeedPublisher {
         }, Math.max(0, at - this.timers.now()));
     }
 }
+/** The longest the ending's existence check may hold the SDK message loop. */
+export const ENDING_CHECK_TIMEOUT_MS = 2_000;
+/** How often the tail poller looks at running shells' output files (R1.4). */
+export const TAIL_POLL_INTERVAL_MS = 1_000;
+const realPollerTimers = {
+    setInterval: (fn, ms) => setInterval(fn, ms),
+    clearInterval: (handle) => clearInterval(handle),
+};
+/** A log field value with no whitespace or `=` to forge a second field. */
+function field(value) {
+    return value.replace(/[\s=]+/g, "_");
+}
+function codeOf(error) {
+    return typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string"
+        ? error.code
+        : "unknown";
+}
+/**
+ * Publishes a running shell task's tail (story 041, R1.4, R1.5). One interval
+ * while any shell output is known; each tick `stat`s every file and reads the
+ * tail only when its size changed, shrinking included. A read error publishes
+ * `tail: null, hasOutput: false` and logs once per task until the file reads
+ * again. A tick never overlaps the previous one, and no rejection escapes it:
+ * the interval runs outside every caller that could handle one, and Node exits
+ * on an unhandled rejection.
+ */
+export class TailPoller {
+    feed;
+    publisher;
+    timers;
+    readTailFn;
+    log;
+    sessionId;
+    interval = null;
+    busy = false;
+    closed = false;
+    /** task id → the file size the last published tail was read at. */
+    sizes = new Map();
+    /** Task ids whose file failed to read: logged once, until it reads again. */
+    failing = new Set();
+    constructor(feed, publisher, timers = realPollerTimers, readTailFn = readTail, log = () => { }, sessionId = "") {
+        this.feed = feed;
+        this.publisher = publisher;
+        this.timers = timers;
+        this.readTailFn = readTailFn;
+        this.log = log;
+        this.sessionId = sessionId;
+    }
+    /** Arms the interval when there is output to watch. Called after a path is recorded. */
+    kick() {
+        if (this.closed || this.interval !== null)
+            return;
+        if (this.feed.runningOutputs().length === 0)
+            return;
+        this.interval = this.timers.setInterval(() => void this.tick(), TAIL_POLL_INTERVAL_MS);
+    }
+    /**
+     * The ending's existence check (R1.7): true when `path` reads as a regular
+     * file within `ENDING_CHECK_TIMEOUT_MS`. Never rejects.
+     */
+    async checkOutput(path) {
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), ENDING_CHECK_TIMEOUT_MS);
+        });
+        try {
+            return await Promise.race([
+                this.readTailFn(path).then(() => true, () => false),
+                timeout,
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    dispose() {
+        this.closed = true;
+        this.stop();
+    }
+    stop() {
+        if (this.interval !== null)
+            this.timers.clearInterval(this.interval);
+        this.interval = null;
+    }
+    async tick() {
+        if (this.busy || this.closed)
+            return;
+        this.busy = true;
+        try {
+            const work = this.feed.runningOutputs();
+            if (work.length === 0) {
+                this.stop();
+                this.sizes.clear();
+                this.failing.clear();
+                return;
+            }
+            for (const { taskId, path } of work) {
+                if (this.closed)
+                    return;
+                let lines = null;
+                let readable = false;
+                try {
+                    const size = (await stat(path)).size;
+                    if (this.sizes.get(taskId) === size)
+                        continue;
+                    lines = await this.readTailFn(path);
+                    this.sizes.set(taskId, size);
+                    this.failing.delete(taskId);
+                    readable = true;
+                }
+                catch (error) {
+                    this.sizes.delete(taskId);
+                    if (!this.failing.has(taskId)) {
+                        this.failing.add(taskId);
+                        this.log(`[tasks/tail] level=warn sessionId=${field(this.sessionId)} taskId=${field(taskId)} code=${field(codeOf(error))}`);
+                    }
+                }
+                if (this.closed)
+                    return;
+                this.publisher.notify(this.feed.setTail(taskId, lines, readable));
+            }
+        }
+        catch (error) {
+            this.log(`[tasks/tail] level=warn sessionId=${field(this.sessionId)} outcome=tick_failed code=${field(codeOf(error))}`);
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+}

package/dist/task-output.d.ts

@@ -0,0 +1,32 @@
+/** The most `_claude/tasks/output` ever serves, whatever the client asks for (R2.3). */
+export declare const OUTPUT_MAX_BYTES = 1048576;
+/** Lines kept in a running task's `tail` (R1.2). */
+export declare const TAIL_MAX_LINES = 10;
+/** Code points kept per tail line; a longer line ends in `…` (R1.3). */
+export declare const TAIL_MAX_CHARS = 240;
+/** Bytes read from the end of the file to build a tail. */
+export declare const TAIL_READ_BYTES = 16384;
+/** A file that could not be read. `code` is the fs code, or `not_regular`. */
+export declare class OutputUnavailable extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+/** The end of `file`, at most `min(maxBytes, OUTPUT_MAX_BYTES)` bytes (R2.1, R2.3). */
+export declare function readOutput(file: string, maxBytes: number): Promise<{
+    content: string;
+    totalBytes: number;
+    truncated: boolean;
+}>;
+/** The last `TAIL_MAX_LINES` lines of `file`, sanitized (R1.2, R1.3). */
+export declare function readTail(file: string): Promise<string[]>;
+/** One tail line as a terminal would leave it, without escapes or controls (R1.3). */
+export declare function sanitizeLine(line: string): string;
+/**
+ * The output path a Bash result names for `taskId`, or null. Only an absolute, normalized path
+ * whose file name is exactly `<taskId>.output` is accepted (R1.6): anything else could be
+ * another task's file, or no task's.
+ */
+export declare function outputPathFromBashResult(text: string, taskId: string): string | null;
+/** True for an absolute, normalized path whose file name is exactly `<taskId>.output`. */
+export declare function isOutputPathFor(candidate: string, taskId: string): boolean;
+//# sourceMappingURL=task-output.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"task-output.d.ts","sourceRoot":"","sources":["../src/task-output.ts"],"names":[],"mappings":"AAgBA,wFAAwF;AACxF,eAAO,MAAM,gBAAgB,UAAY,CAAC;AAC1C,oDAAoD;AACpD,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,wEAAwE;AACxE,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,2DAA2D;AAC3D,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC,8EAA8E;AAC9E,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;CAKzB;AAwDD,uFAAuF;AACvF,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC,CAMtE;AAED,yEAAyE;AACzE,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAK9D;AASD,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUjD;AAMD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGpF;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAM1E"}

package/dist/task-output.js

@@ -0,0 +1,135 @@
+// Reading a shell task's output file — story 041.
+//
+// The CLI writes a background shell's output to `<task id>.output` and names that path in the
+// Bash result. This module reads the end of such a file safely, for two consumers: the tail the
+// task feed publishes while the task runs, and `_claude/tasks/output` after it ends.
+//
+// Safety rules, each one a test in `tests/task-output.test.ts`:
+// - only a regular file is read, opened with `O_NOFOLLOW` so a symlink planted at the recorded
+//   path is refused (Node's flag covers only the last component, hence the `isFile()` check on
+//   the handle as well);
+// - a cut lands on a line boundary, never inside a line or a UTF-8 sequence;
+// - an error carries the fs code and never the file's content.
+import { constants, open } from "node:fs/promises";
+import path from "node:path";
+/** The most `_claude/tasks/output` ever serves, whatever the client asks for (R2.3). */
+export const OUTPUT_MAX_BYTES = 1_048_576;
+/** Lines kept in a running task's `tail` (R1.2). */
+export const TAIL_MAX_LINES = 10;
+/** Code points kept per tail line; a longer line ends in `…` (R1.3). */
+export const TAIL_MAX_CHARS = 240;
+/** Bytes read from the end of the file to build a tail. */
+export const TAIL_READ_BYTES = 16_384;
+/** A file that could not be read. `code` is the fs code, or `not_regular`. */
+export class OutputUnavailable extends Error {
+    code;
+    constructor(code) {
+        super(`task output unavailable (${code})`);
+        this.name = "OutputUnavailable";
+        this.code = code;
+    }
+}
+function unavailable(error) {
+    if (error instanceof OutputUnavailable)
+        return error;
+    const code = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+        ? error.code
+        : "unknown";
+    return new OutputUnavailable(code);
+}
+/**
+ * Reads the last `maxBytes` of `file`, cut on a line boundary. When the file is longer, one byte
+ * before the window is read too: everything up to and including the first `\n` is dropped, so a
+ * window that already starts on a line keeps that line. A window holding no `\n` is kept whole.
+ */
+async function readWindow(file, maxBytes) {
+    let handle;
+    try {
+        // O_NONBLOCK: opening a FIFO for reading would otherwise wait for a writer
+        // forever; with it the open returns, and `isFile()` below refuses the FIFO.
+        handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        throw unavailable(error);
+    }
+    try {
+        const stats = await handle.stat();
+        if (!stats.isFile())
+            throw new OutputUnavailable("not_regular");
+        const totalBytes = stats.size;
+        const truncated = totalBytes > maxBytes;
+        const start = truncated ? totalBytes - maxBytes - 1 : 0;
+        const length = totalBytes - start;
+        const buffer = Buffer.alloc(length);
+        let read = 0;
+        while (read < length) {
+            const { bytesRead } = await handle.read(buffer, read, length - read, start + read);
+            if (bytesRead === 0)
+                break; // the file shrank between fstat and read
+            read += bytesRead;
+        }
+        let bytes = buffer.subarray(0, read);
+        if (truncated) {
+            const newline = bytes.indexOf(0x0a);
+            bytes = newline === -1 ? bytes.subarray(1) : bytes.subarray(newline + 1);
+        }
+        return { bytes, totalBytes, truncated };
+    }
+    catch (error) {
+        throw unavailable(error);
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}
+const decode = (bytes) => new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+/** The end of `file`, at most `min(maxBytes, OUTPUT_MAX_BYTES)` bytes (R2.1, R2.3). */
+export async function readOutput(file, maxBytes) {
+    const { bytes, totalBytes, truncated } = await readWindow(file, Math.min(maxBytes, OUTPUT_MAX_BYTES));
+    return { content: decode(bytes), totalBytes, truncated };
+}
+/** The last `TAIL_MAX_LINES` lines of `file`, sanitized (R1.2, R1.3). */
+export async function readTail(file) {
+    const { bytes } = await readWindow(file, TAIL_READ_BYTES);
+    const lines = decode(bytes).split("\n");
+    if (lines.at(-1) === "")
+        lines.pop();
+    return lines.slice(-TAIL_MAX_LINES).map(sanitizeLine);
+}
+/* eslint-disable no-control-regex -- these patterns exist to match terminal control bytes */
+const CSI = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+const OSC = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+const OTHER_ESCAPE = /\x1b[\s\S]?/g;
+const CONTROL = /[\x00-\x08\x0b-\x1f\x7f]/g;
+/* eslint-enable no-control-regex */
+/** One tail line as a terminal would leave it, without escapes or controls (R1.3). */
+export function sanitizeLine(line) {
+    const redrawn = line.slice(line.lastIndexOf("\r") + 1);
+    const clean = redrawn
+        .replace(OSC, "")
+        .replace(CSI, "")
+        .replace(OTHER_ESCAPE, "")
+        .replace(CONTROL, "");
+    const chars = [...clean];
+    if (chars.length <= TAIL_MAX_CHARS)
+        return clean;
+    return chars.slice(0, TAIL_MAX_CHARS - 1).join("") + "…";
+}
+// The CLI ends the sentence with a period (2.1.285: "…/tasks/<id>.output."), so
+// one trailing punctuation mark is not part of the path.
+const OUTPUT_NOTICE = /Output is being written to: (\S+?)[.,;:]?(?:\s|$)/;
+/**
+ * The output path a Bash result names for `taskId`, or null. Only an absolute, normalized path
+ * whose file name is exactly `<taskId>.output` is accepted (R1.6): anything else could be
+ * another task's file, or no task's.
+ */
+export function outputPathFromBashResult(text, taskId) {
+    const candidate = text.match(OUTPUT_NOTICE)?.[1];
+    return candidate !== undefined && isOutputPathFor(candidate, taskId) ? candidate : null;
+}
+/** True for an absolute, normalized path whose file name is exactly `<taskId>.output`. */
+export function isOutputPathFor(candidate, taskId) {
+    return (path.isAbsolute(candidate) &&
+        path.normalize(candidate) === candidate &&
+        path.basename(candidate) === `${taskId}.output`);
+}

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.25.3",
+  "version": "0.27.0",
   "description": "Claude Code in Zed and other ACP clients with the VS Code extension's UX — multi-select questions, refusal consent, live quota windows, background tasks, Ultracode effort and session notices. Fork of claude-agent-acp.",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",