@lucascouts/claude-agent-acp-plus 0.23.6 → 0.25.0

package/dist/task-feed.js

@@ -0,0 +1,530 @@
+/**
+ * The agent's task feed: background shells, subagents, monitors and workflows,
+ * folded from the SDK's task messages into the `_claude/tasks` snapshot.
+ *
+ * The SDK reports tasks as a stream of bookends (`task_started`,
+ * `task_progress`, `task_updated`, `task_notification`) plus a level
+ * (`background_tasks_changed`). Zeo needs one table it can render, so
+ * `TaskFeed` keeps that table per session and renders it as a snapshot. The
+ * snapshot is a LEVEL, not a stream: every publish carries every live task,
+ * so a lost update is repaired by the next one, and the client replaces its
+ * list instead of merging.
+ *
+ * An ended task appears in exactly one successful snapshot with its final
+ * status, then drops out. `snapshot()` marks nothing; the publisher calls
+ * `markPublished()` only after the send carrying the endings succeeded, so a
+ * failed send never loses an ending.
+ *
+ * `TaskFeedPublisher` decides WHEN to publish: at most once per second during
+ * progress, at once on an ending, and once more after a burst so the latest
+ * values are not lost.
+ *
+ * A foreground shell task (`local_bash`, not backgrounded) is held back for
+ * `FOREGROUND_SHELL_HOLD_MS`: Claude Code registers every shell command as a
+ * task, so only one still running after the hold, or moved to the background,
+ * is published. One that ends while held is dropped without a trace. The feed
+ * stays clock-driven: the publisher's timer calls `promoteDue()`.
+ *
+ * Neither class ever copies a command line (`SDKTaskStartedMessage.prompt`)
+ * into an entry or a log line.
+ */
+/** The `session_info_update._meta` key the snapshot is published under. */
+export const TASKS_META_KEY = "_claude/tasks";
+/** 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
+ *  it is ended as `interrupted`. The level and the bookends race (the level
+ *  may arrive first), so a real ending gets this long to land. */
+export const RECONCILE_GRACE_MS = 2_000;
+/** Minimum gap between two progress publishes of one session. */
+export const PUBLISH_INTERVAL_MS = 1_000;
+const TASK_TYPES = {
+    local_bash: "shell",
+    local_agent: "subagent",
+    local_workflow: "workflow",
+    mcp_task: "mcp",
+    monitor: "monitor",
+};
+function normaliseType(raw) {
+    if (!raw)
+        return "shell";
+    return TASK_TYPES[raw] ?? raw;
+}
+/**
+ * The one place the SDK's ending vocabulary becomes the wire's. The same stop
+ * arrives as `task_updated.patch.status = "killed"` and as
+ * `task_notification.status = "stopped"`; both are `stopped`. Returns null for
+ * a non-terminal status (`pending`, `running`, `paused`).
+ */
+export function normaliseStatus(status, reason) {
+    if (reason === "worker_restart")
+        return "interrupted";
+    switch (status) {
+        case "completed":
+            return "completed";
+        case "failed":
+            return "failed";
+        case "killed":
+        case "stopped":
+            return "stopped";
+        default:
+            return null;
+    }
+}
+/** The SDK types usage as `number`; Zeo parses it as an unsigned integer and
+ *  rejects the whole snapshot on one fractional or negative value. */
+function wholeNumber(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.round(value)) : 0;
+}
+function usageOf(usage) {
+    if (!usage)
+        return null;
+    return {
+        tokens: wholeNumber(usage.total_tokens),
+        toolUses: wholeNumber(usage.tool_uses),
+        durationMs: wholeNumber(usage.duration_ms),
+    };
+}
+export class TaskFeed {
+    clock;
+    log;
+    sessionId;
+    tasks = new Map();
+    /** Ended tasks whose final snapshot was sent successfully: never shown again. */
+    published = new Set();
+    /** Ambient task ids: never shown, and their later messages are not news. */
+    ambient = new Set();
+    /** task id → its current life; bumped on every start. */
+    lives = new Map();
+    /** task id → the life the latest snapshot carried as ended. */
+    snapshotLives = new Map();
+    /** task id → time after which a missing bookend means `interrupted`. */
+    deadlines = new Map();
+    /** Foreground shell tasks not published yet: see `promoteDue`. */
+    held = new Map();
+    /** Shell task ids labelled by their tool call: a patch never relabels them. */
+    toolDescribed = new Set();
+    constructor(clock, log = {}, sessionId = "") {
+        this.clock = clock;
+        this.log = log;
+        this.sessionId = sessionId;
+    }
+    /**
+     * `toolDescription` is the spawning tool call's own `description` input. A
+     * shell task carries it when it is non-empty; otherwise the SDK's, which
+     * for a shell is the command text. Other task types keep the SDK's.
+     */
+    onStarted(msg, toolDescription) {
+        if (msg.ambient) {
+            this.ambient.add(msg.task_id);
+            return "none";
+        }
+        if (this.tasks.get(msg.task_id)?.status === "running" || this.held.has(msg.task_id)) {
+            return "none";
+        }
+        const shell = msg.task_type === "local_bash";
+        const fromTool = shell && typeof toolDescription === "string" && toolDescription.trim() !== "";
+        if (fromTool)
+            this.toolDescribed.add(msg.task_id);
+        else
+            this.toolDescribed.delete(msg.task_id);
+        const entry = {
+            id: msg.task_id,
+            toolCallId: msg.tool_use_id ?? null,
+            type: normaliseType(msg.task_type),
+            description: fromTool ? toolDescription : msg.description,
+            background: msg.is_backgrounded ?? false,
+            depth: msg.spawn_depth ?? 0,
+            status: "running",
+            startedAt: this.clock(),
+            endedAt: null,
+            usage: null,
+            lastTool: null,
+            summary: null,
+        };
+        if (shell && msg.is_backgrounded !== true) {
+            this.held.set(msg.task_id, entry);
+            return "held";
+        }
+        this.admit(entry);
+        return "progress";
+    }
+    /** Publishes every held shell task whose hold has run out. */
+    promoteDue() {
+        const now = this.clock();
+        let change = "none";
+        for (const [id, entry] of this.held) {
+            if (entry.startedAt + FOREGROUND_SHELL_HOLD_MS > now)
+                continue;
+            this.held.delete(id);
+            this.admit(entry);
+            change = "progress";
+        }
+        return change;
+    }
+    /** When the earliest held shell task is due for promotion; null if none is held. */
+    nextHoldDue() {
+        let next = null;
+        for (const entry of this.held.values()) {
+            const due = entry.startedAt + FOREGROUND_SHELL_HOLD_MS;
+            if (next === null || due < next)
+                next = due;
+        }
+        return next;
+    }
+    onProgress(msg) {
+        const heldEntry = this.held.get(msg.task_id);
+        const task = heldEntry ?? this.running(msg.task_id, "task_progress");
+        if (!task)
+            return "none";
+        task.usage = usageOf(msg.usage);
+        task.lastTool = msg.last_tool_name ?? task.lastTool;
+        task.summary = msg.summary ?? task.summary;
+        // Kept for the promotion, but nobody has been shown the task yet.
+        return heldEntry ? "none" : "progress";
+    }
+    onUpdated(msg) {
+        const heldEntry = this.held.get(msg.task_id);
+        if (heldEntry) {
+            if (msg.patch.is_backgrounded === true) {
+                // Moved to the background: published at once, then patched as usual.
+                this.held.delete(msg.task_id);
+                this.admit(heldEntry);
+            }
+            else {
+                if (normaliseStatus(msg.patch.status)) {
+                    this.held.delete(msg.task_id);
+                }
+                else {
+                    this.patch(heldEntry, msg.patch);
+                }
+                return "none";
+            }
+        }
+        const task = this.running(msg.task_id, "task_updated");
+        if (!task)
+            return "none";
+        const ending = normaliseStatus(msg.patch.status);
+        this.patch(task, msg.patch);
+        if (ending) {
+            this.end(task, ending);
+            return "terminal";
+        }
+        return "progress";
+    }
+    onNotification(msg) {
+        // A held shell task that ends was never shown: its ending is not news.
+        if (this.held.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;
+        const usage = usageOf(msg.usage);
+        if (usage)
+            task.usage = usage;
+        this.end(task, ending);
+        return "terminal";
+    }
+    /**
+     * The SDK's level: every live background task. It never adds or ends a task
+     * by itself — it may precede the `task_started` that names a task, or the
+     * bookend that ends one. A running background task the level omits gets a
+     * reconcile deadline; a level that lists it again clears it.
+     */
+    onLevel(level) {
+        const listed = new Set(level.map((t) => t.task_id));
+        const now = this.clock();
+        for (const task of this.tasks.values()) {
+            if (task.status !== "running" || !task.background)
+                continue;
+            if (listed.has(task.id))
+                this.deadlines.delete(task.id);
+            else if (!this.deadlines.has(task.id))
+                this.deadlines.set(task.id, now + RECONCILE_GRACE_MS);
+        }
+        return "none";
+    }
+    nextReconcileAt() {
+        let next = null;
+        for (const at of this.deadlines.values())
+            if (next === null || at < next)
+                next = at;
+        return next;
+    }
+    /** Ends as `interrupted` every task whose deadline passed with no bookend. */
+    reconcile(now) {
+        let change = "none";
+        for (const [id, at] of this.deadlines) {
+            if (at > now)
+                continue;
+            const task = this.tasks.get(id);
+            if (task?.status === "running") {
+                this.log.warn?.(`[tasks/reconcile] sessionId=${this.sessionId} taskId=${id} outcome=interrupted reason=missing_from_level`);
+                this.end(task, "interrupted", now);
+                change = "terminal";
+            }
+            this.deadlines.delete(id);
+        }
+        return change;
+    }
+    /** 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() {
+        this.held.clear();
+        let change = "none";
+        for (const task of this.tasks.values()) {
+            if (task.status !== "running")
+                continue;
+            this.end(task, "interrupted");
+            change = "terminal";
+        }
+        return change;
+    }
+    /** True when the feed holds `taskId` as running — the stop request's gate. */
+    isRunning(taskId) {
+        return this.tasks.get(taskId)?.status === "running";
+    }
+    /** Running tasks plus ended tasks not yet published, oldest start first.
+     *  Marks nothing: see `markPublished`. */
+    snapshot() {
+        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 }));
+        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);
+        return { snapshot: { tasks }, endedIds };
+    }
+    /** Called after the send carrying these endings succeeded. Their entries are
+     *  dropped; the ids are remembered so a late bookend cannot resurrect them. */
+    markPublished(endedIds) {
+        for (const id of endedIds) {
+            // Only the life the snapshot carried: a task that started again while
+            // the send was in flight is a new life the client has not seen end.
+            if (this.snapshotLives.get(id) !== this.lives.get(id))
+                continue;
+            if (this.tasks.get(id)?.status === "running")
+                continue;
+            this.snapshotLives.delete(id);
+            this.published.add(id);
+            this.tasks.delete(id);
+        }
+    }
+    running(taskId, kind) {
+        const task = this.tasks.get(taskId);
+        if (task?.status === "running")
+            return task;
+        if (!task && !this.published.has(taskId) && !this.ambient.has(taskId)) {
+            this.log.debug?.(`[tasks/feed] sessionId=${this.sessionId} taskId=${taskId} ignored=${kind}`);
+        }
+        return undefined;
+    }
+    /** Puts a running entry into the table. A known id starting again is a new
+     *  life of the same task — a resumed subagent is re-registered under its
+     *  agent id. It replaces the ended entry, published or not: the running
+     *  state supersedes an ending the client has not seen yet, and a published
+     *  id must be shown again. */
+    admit(entry) {
+        this.published.delete(entry.id);
+        this.lives.set(entry.id, (this.lives.get(entry.id) ?? 0) + 1);
+        this.tasks.set(entry.id, entry);
+    }
+    /** Applies a `task_updated` patch's label and placement; a label taken from
+     *  the tool call is never replaced. */
+    patch(task, patch) {
+        if (patch.description !== undefined && !this.toolDescribed.has(task.id)) {
+            task.description = patch.description;
+        }
+        if (patch.is_backgrounded !== undefined)
+            task.background = patch.is_backgrounded;
+    }
+    end(task, status, at = this.clock()) {
+        task.status = status;
+        task.endedAt = at;
+        this.deadlines.delete(task.id);
+    }
+}
+const realTimers = {
+    now: () => Date.now(),
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+export class TaskFeedPublisher {
+    feed;
+    send;
+    timers;
+    onSendError;
+    lastSendAt = Number.NEGATIVE_INFINITY;
+    /** One send at a time: a snapshot taken while another is in flight would
+     *  carry that one's endings again, and both would succeed. */
+    inFlight = false;
+    /** A publish requested while a send was in flight; `"terminal"` skips the
+     *  throttle when it runs. */
+    queued = "none";
+    /** The trailing publish or the retry after a failed send — never both. */
+    pending = null;
+    reconcileTimer = null;
+    reconcileAt = null;
+    /** Promotes held foreground shells: armed at the feed's `nextHoldDue()`. */
+    holdTimer = null;
+    holdAt = null;
+    closed = false;
+    /** Set by `dispose({ flush: true })`: a publish queued behind an in-flight
+     *  send still goes out once — a retirement's `interrupted` endings. */
+    flushOnSettle = false;
+    constructor(feed, send, timers = realTimers, onSendError = () => { }) {
+        this.feed = feed;
+        this.send = send;
+        this.timers = timers;
+        this.onSendError = onSendError;
+    }
+    notify(change) {
+        if (this.closed)
+            return;
+        if (change === "terminal") {
+            this.publishNow();
+        }
+        else if (change === "progress") {
+            const wait = this.lastSendAt + PUBLISH_INTERVAL_MS - this.timers.now();
+            if (wait <= 0)
+                this.publishNow();
+            else if (this.pending === null)
+                this.arm(wait);
+        }
+        else if (change === "held") {
+            this.armHold();
+        }
+        this.armReconcile();
+    }
+    dispose(options = {}) {
+        this.closed = true;
+        this.flushOnSettle = options.flush ?? false;
+        this.cancelPending();
+        if (this.reconcileTimer !== null)
+            this.timers.clearTimeout(this.reconcileTimer);
+        this.reconcileTimer = null;
+        this.reconcileAt = null;
+        if (this.holdTimer !== null)
+            this.timers.clearTimeout(this.holdTimer);
+        this.holdTimer = null;
+        this.holdAt = null;
+    }
+    publishNow() {
+        this.cancelPending();
+        if (this.inFlight) {
+            this.queued = "terminal";
+            return;
+        }
+        this.inFlight = true;
+        this.lastSendAt = this.timers.now();
+        const { snapshot, endedIds } = this.feed.snapshot();
+        // The SDK message loop calls notify; nothing here may throw into it — not
+        // a synchronous throw from `send`, and not a throwing error handler.
+        void Promise.resolve()
+            .then(() => this.send(snapshot))
+            .then(() => {
+            this.feed.markPublished(endedIds);
+            this.settle();
+        }, (error) => {
+            try {
+                this.onSendError(error);
+            }
+            catch {
+                // The retry below matters more than the log line.
+            }
+            this.settle();
+            if (!this.closed && !this.inFlight && this.pending === null) {
+                this.arm(PUBLISH_INTERVAL_MS);
+            }
+        });
+    }
+    settle() {
+        this.inFlight = false;
+        const queued = this.queued;
+        this.queued = "none";
+        if (queued === "none")
+            return;
+        if (!this.closed) {
+            this.notify(queued);
+        }
+        else if (this.flushOnSettle) {
+            // One last send, no retry: the publisher is closed.
+            this.flushOnSettle = false;
+            void Promise.resolve()
+                .then(() => this.send(this.feed.snapshot().snapshot))
+                .catch((error) => {
+                try {
+                    this.onSendError(error);
+                }
+                catch {
+                    // Nothing left to arm.
+                }
+            });
+        }
+    }
+    arm(ms) {
+        this.pending = this.timers.setTimeout(() => {
+            this.pending = null;
+            if (!this.closed)
+                this.publishNow();
+        }, ms);
+    }
+    cancelPending() {
+        if (this.pending !== null)
+            this.timers.clearTimeout(this.pending);
+        this.pending = null;
+    }
+    /** One timer for every held shell, at the earliest due time. A held shell
+     *  that ended early leaves the timer armed: it fires, promotes nothing, and
+     *  re-arms for the next one still held. */
+    armHold() {
+        const at = this.feed.nextHoldDue();
+        if (at === null)
+            return;
+        if (this.holdAt !== null && this.holdAt <= at)
+            return;
+        if (this.holdTimer !== null)
+            this.timers.clearTimeout(this.holdTimer);
+        this.holdAt = at;
+        this.holdTimer = this.timers.setTimeout(() => {
+            this.holdTimer = null;
+            this.holdAt = null;
+            if (this.closed)
+                return;
+            // Outside the SDK loop nobody handles an error: a failed send is
+            // caught in `publishNow`, and anything else thrown is reported here.
+            try {
+                this.notify(this.feed.promoteDue());
+            }
+            catch (error) {
+                try {
+                    this.onSendError(error);
+                }
+                catch {
+                    // Re-arming matters more than the log line.
+                }
+            }
+            if (!this.closed)
+                this.armHold();
+        }, Math.max(0, at - this.timers.now()));
+    }
+    armReconcile() {
+        const at = this.feed.nextReconcileAt();
+        if (at === null || at === this.reconcileAt)
+            return;
+        if (this.reconcileTimer !== null)
+            this.timers.clearTimeout(this.reconcileTimer);
+        this.reconcileAt = at;
+        this.reconcileTimer = this.timers.setTimeout(() => {
+            this.reconcileTimer = null;
+            this.reconcileAt = null;
+            if (this.closed)
+                return;
+            this.notify(this.feed.reconcile(this.timers.now()));
+        }, Math.max(0, at - this.timers.now()));
+    }
+}

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.23.6",
+  "version": "0.25.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",