@bridge4dev/runner 0.63.0 → 0.65.0

package/dist/adapters/agent-tasks.d.ts

@@ -0,0 +1,113 @@
+import type { AgentEvent, AgentTask } from './types.js';
+/** Longest a task title may be before the tray truncates it. */
+export declare const TASK_TITLE_LIMIT = 120;
+/** How many live tasks travel in one `agent_tasks` event. */
+export declare const TASK_LIST_CAP = 20;
+/**
+ * Floor between two `agent_tasks` publications.
+ *
+ * A twenty-agent fan-out changes membership dozens of times a minute and every
+ * running subagent adds a `task_progress` every ~30s. Each event is a row in
+ * `DevSessionEvent`, so the tray coalesces rather than narrating.
+ */
+export declare const TASK_PUBLISH_INTERVAL_MS = 1500;
+export type AgentTasksEvent = Extract<AgentEvent, {
+    type: 'agent_tasks';
+}>;
+export interface AgentTaskTrayOptions {
+    emit: (event: AgentTasksEvent) => void;
+    /**
+     * Read on every publication rather than told once: an adapter can end
+     * without passing through its own `stop()` (the Claude CLI exiting on its
+     * own), and a trailing timer must not fire into a closed output queue then.
+     */
+    isStopped: () => boolean;
+}
+export declare class AgentTaskTray {
+    private readonly opts;
+    private readonly tasks;
+    /** Ids currently in the agent's live set – the tray shows exactly these. */
+    private liveIds;
+    /**
+     * Which turn is being counted (#147).
+     *
+     * There are no `started` / `done` accumulators, and that is the whole fix.
+     * Two counters with different lifetimes could disagree, and did: the turn's
+     * end zeroed both while deliberately keeping the ROWS of tasks still running,
+     * so a background shell that outlived its turn was counted as finished in
+     * the next one without ever having been counted as started – «22 of 21
+     * done». Both numbers are derived from `tasks` in one pass, so `done <= total`
+     * holds by cardinality rather than by clamping.
+     */
+    private turnEpoch;
+    private publishTimer;
+    private publishedAt;
+    /** Last published snapshot, minus the ages – see `flush` (QA-111 M4). */
+    private lastFingerprint;
+    constructor(opts: AgentTaskTrayOptions);
+    has(id: string): boolean;
+    /**
+     * Replace the live set. REPLACE, not merge: the agent's own statement of
+     * what exists is the authority, so a missed start/stop pair cannot wedge a
+     * row in the tray forever.
+     */
+    setLive(ids: readonly string[]): void;
+    /**
+     * Drop a row and its place in the live set. Answers whether the live set
+     * changed, which is what decides that a frame is worth publishing.
+     */
+    forget(id: string): boolean;
+    /**
+     * Create-or-merge one task row, and count the TRANSITIONS while doing it.
+     *
+     * The counters live here rather than in the individual message handlers
+     * because «started» and «finished» are properties of the transition, not of
+     * whichever message happened to announce it (QA-111 M1). They were counted
+     * per-message, and both orderings the Claude SDK actually produces missed:
+     *
+     *   `background_tasks_changed` → `task_started`   → `total` stayed 0
+     *   `task_updated{completed}`  → `task_notification` → `done` stayed 0
+     *
+     * `startedAt` is stamped once and never moves.
+     */
+    touch(id: string, patch: Partial<AgentTask>): void;
+    /**
+     * The empty set, said once when the agent's process (re)starts (#113).
+     *
+     * The level is per PROCESS: the dashboard reads the newest `agent_tasks` in
+     * the stored feed, so without this a session killed mid-turn – the runner
+     * restarted, the machine rebooted – would come back showing the helpers of
+     * its previous life as though they were still running, right up until the
+     * next membership change.
+     */
+    announceEmpty(): void;
+    /**
+     * Publish the tray, at most once every `TASK_PUBLISH_INTERVAL_MS`.
+     *
+     * Every publication is a stored row in the session feed, and a wide fan-out
+     * changes membership dozens of times a minute. The trailing timer matters as
+     * much as the floor: the LAST change in a burst is the one that says the work
+     * is over, and dropping it would leave the tray running forever.
+     */
+    publish(): void;
+    /**
+     * The turn ended. Reset what belongs to the TURN – and only that.
+     *
+     * `done`/`total` are per-turn by definition and go back to zero. The live set
+     * does NOT: background work is precisely the work that outlives the turn that
+     * started it, which is the whole reason the tray exists. Caught on production
+     * (#113): the agent ended its turn with `sleep 40` still running in the
+     * background and a tray that cleared everything here showed nothing at
+     * exactly the moment somebody was reading the answer and wondering whether
+     * the deploy had finished.
+     *
+     * Finished rows are dropped here because only the live ids are ever rendered
+     * anyway, and keeping them would grow the map for the life of the session.
+     */
+    endTurn(): void;
+    /** A pending publication would fire into a closed output queue. */
+    close(): void;
+    private clearTimer;
+    private flush;
+}
+//# sourceMappingURL=agent-tasks.d.ts.map

package/dist/adapters/agent-tasks.js

@@ -0,0 +1,260 @@
+import { clip } from './questions.js';
+// The task tray every adapter publishes through (ticket #113, made common for
+// #382).
+//
+// «Is anybody still working beside the conversation» is ONE rule: the
+// supervisor counts the running rows of an `agent_tasks` frame, keeps the
+// number on the session and sends it with every status, and every reader on
+// the API and the dashboard asks `@devbridge/shared` about it. No reader
+// branches on the agent. What differs between CLIs is only how each one SAYS
+// that a helper started or stopped – so an adapter's own code decides
+// membership, and this file decides everything about publishing it: the floor
+// between frames, the de-duplication, the cap on the list, the per-turn
+// counters and the frame at the end of a turn. It used to live inside the
+// Claude adapter, which is why Codex never had it (#382).
+//
+// A new CLI joins by translating its own events into `touch` / `setLive` /
+// `endTurn`, and nothing else: see `docs/devbridge/knowledge/10-agent-profiles.md`.
+/** Longest a task title may be before the tray truncates it. */
+export const TASK_TITLE_LIMIT = 120;
+/** How many live tasks travel in one `agent_tasks` event. */
+export const TASK_LIST_CAP = 20;
+/**
+ * Floor between two `agent_tasks` publications.
+ *
+ * A twenty-agent fan-out changes membership dozens of times a minute and every
+ * running subagent adds a `task_progress` every ~30s. Each event is a row in
+ * `DevSessionEvent`, so the tray coalesces rather than narrating.
+ */
+export const TASK_PUBLISH_INTERVAL_MS = 1_500;
+const EMPTY_FINGERPRINT = JSON.stringify({ done: 0, total: 0, tasks: [] });
+export class AgentTaskTray {
+    opts;
+    tasks = new Map();
+    /** Ids currently in the agent's live set – the tray shows exactly these. */
+    liveIds = [];
+    /**
+     * Which turn is being counted (#147).
+     *
+     * There are no `started` / `done` accumulators, and that is the whole fix.
+     * Two counters with different lifetimes could disagree, and did: the turn's
+     * end zeroed both while deliberately keeping the ROWS of tasks still running,
+     * so a background shell that outlived its turn was counted as finished in
+     * the next one without ever having been counted as started – «22 of 21
+     * done». Both numbers are derived from `tasks` in one pass, so `done <= total`
+     * holds by cardinality rather than by clamping.
+     */
+    turnEpoch = 0;
+    publishTimer = null;
+    publishedAt = 0;
+    /** Last published snapshot, minus the ages – see `flush` (QA-111 M4). */
+    lastFingerprint = '';
+    constructor(opts) {
+        this.opts = opts;
+    }
+    has(id) {
+        return this.tasks.has(id);
+    }
+    /**
+     * Replace the live set. REPLACE, not merge: the agent's own statement of
+     * what exists is the authority, so a missed start/stop pair cannot wedge a
+     * row in the tray forever.
+     */
+    setLive(ids) {
+        this.liveIds = [...ids];
+    }
+    /**
+     * Drop a row and its place in the live set. Answers whether the live set
+     * changed, which is what decides that a frame is worth publishing.
+     */
+    forget(id) {
+        this.tasks.delete(id);
+        const before = this.liveIds.length;
+        this.liveIds = this.liveIds.filter((live) => live !== id);
+        return this.liveIds.length !== before;
+    }
+    /**
+     * Create-or-merge one task row, and count the TRANSITIONS while doing it.
+     *
+     * The counters live here rather than in the individual message handlers
+     * because «started» and «finished» are properties of the transition, not of
+     * whichever message happened to announce it (QA-111 M1). They were counted
+     * per-message, and both orderings the Claude SDK actually produces missed:
+     *
+     *   `background_tasks_changed` → `task_started`   → `total` stayed 0
+     *   `task_updated{completed}`  → `task_notification` → `done` stayed 0
+     *
+     * `startedAt` is stamped once and never moves.
+     */
+    touch(id, patch) {
+        const existing = this.tasks.get(id);
+        if (existing) {
+            const settledAs = existing.status === 'running' ? null : existing.status;
+            Object.assign(existing, patch);
+            if (patch.title)
+                existing.title = clip(patch.title, TASK_TITLE_LIMIT);
+            if (patch.summary)
+                existing.summary = clip(patch.summary, TASK_TITLE_LIMIT);
+            // Settling is one-way. A task that has stopped cannot start again under
+            // the same id: the only messages that could say so are a late update
+            // carrying a status the adapter does not recognise, or a frame
+            // redelivered after a reconnect – neither of which is news that the work
+            // resumed. Letting either through would make the derived `done` count
+            // downwards on screen. An agent that genuinely hands the same helper new
+            // work (Codex does) says so by `forget` first: that is a new row.
+            if (settledAs && existing.status === 'running')
+                existing.status = settledAs;
+            return;
+        }
+        this.tasks.set(id, {
+            ...patch,
+            id,
+            kind: patch.kind ?? 'task',
+            title: clip(patch.title ?? 'Working…', TASK_TITLE_LIMIT),
+            status: patch.status ?? 'running',
+            turnEpoch: this.turnEpoch,
+            startedAt: Date.now(),
+            // The only free-text field an agent writes with no length of its own:
+            // a subagent's closing `summary` runs to kilobytes, and twenty of them
+            // push the event past the payload cap, which replaces the WHOLE payload
+            // with `{truncated:true}` and blinks the tray out (QA-111 m1).
+            ...(patch.summary ? { summary: clip(patch.summary, TASK_TITLE_LIMIT) } : {}),
+        });
+    }
+    /**
+     * The empty set, said once when the agent's process (re)starts (#113).
+     *
+     * The level is per PROCESS: the dashboard reads the newest `agent_tasks` in
+     * the stored feed, so without this a session killed mid-turn – the runner
+     * restarted, the machine rebooted – would come back showing the helpers of
+     * its previous life as though they were still running, right up until the
+     * next membership change.
+     */
+    announceEmpty() {
+        this.lastFingerprint = EMPTY_FINGERPRINT;
+        this.opts.emit({ type: 'agent_tasks', tasks: [], done: 0, total: 0 });
+    }
+    /**
+     * Publish the tray, at most once every `TASK_PUBLISH_INTERVAL_MS`.
+     *
+     * Every publication is a stored row in the session feed, and a wide fan-out
+     * changes membership dozens of times a minute. The trailing timer matters as
+     * much as the floor: the LAST change in a burst is the one that says the work
+     * is over, and dropping it would leave the tray running forever.
+     */
+    publish() {
+        if (this.opts.isStopped())
+            return;
+        const wait = TASK_PUBLISH_INTERVAL_MS - (Date.now() - this.publishedAt);
+        if (wait > 0) {
+            if (!this.publishTimer) {
+                this.publishTimer = setTimeout(() => {
+                    this.publishTimer = null;
+                    this.flush();
+                }, wait);
+                this.publishTimer.unref();
+            }
+            return;
+        }
+        this.flush();
+    }
+    /**
+     * The turn ended. Reset what belongs to the TURN – and only that.
+     *
+     * `done`/`total` are per-turn by definition and go back to zero. The live set
+     * does NOT: background work is precisely the work that outlives the turn that
+     * started it, which is the whole reason the tray exists. Caught on production
+     * (#113): the agent ended its turn with `sleep 40` still running in the
+     * background and a tray that cleared everything here showed nothing at
+     * exactly the moment somebody was reading the answer and wondering whether
+     * the deploy had finished.
+     *
+     * Finished rows are dropped here because only the live ids are ever rendered
+     * anyway, and keeping them would grow the map for the life of the session.
+     */
+    endTurn() {
+        this.clearTimer();
+        const live = new Set(this.liveIds);
+        for (const id of [...this.tasks.keys()]) {
+            if (!live.has(id))
+                this.tasks.delete(id);
+        }
+        this.turnEpoch += 1;
+        // Straight through `flush` rather than an empty frame of its own, and with
+        // the de-duplication disarmed for this one frame (plan `workflow-mode-fixes`
+        // S1 p.10). The turn's counters usually changed, but not always: a task
+        // started in an earlier turn and still running, and a turn that started
+        // nothing new, produce exactly the frame the last turn ended on – and the
+        // end of a turn is the moment the API and the tray most need to hear what
+        // is still running, whether or not it is news. The supervisor
+        // de-duplicates the COUNT on its own side; this frame is the tray's
+        // freshness, not the database's.
+        this.publishedAt = 0;
+        this.lastFingerprint = '';
+        this.flush();
+    }
+    /** A pending publication would fire into a closed output queue. */
+    close() {
+        this.clearTimer();
+    }
+    clearTimer() {
+        if (!this.publishTimer)
+            return;
+        clearTimeout(this.publishTimer);
+        this.publishTimer = null;
+    }
+    flush() {
+        if (this.opts.isStopped())
+            return;
+        this.publishedAt = Date.now();
+        const now = Date.now();
+        // Only what the agent still calls live. A task that finished keeps its row
+        // in `tasks` for the counters, but the tray is about NOW.
+        const tasks = this.liveIds
+            .map((id) => this.tasks.get(id))
+            .filter((t) => Boolean(t))
+            .slice(0, TASK_LIST_CAP)
+            // How long it has been running, measured HERE (QA-111 m2). `startedAt` is
+            // this machine's clock and the browser's is a different one – subtracting
+            // across them put the dev server's clock skew straight into the number,
+            // so a host ten minutes behind showed «10m 03s» on a task one second old.
+            .map(({ turnEpoch: _turnEpoch, ...task }) => ({
+            ...task,
+            ageMs: Math.max(0, now - task.startedAt),
+        }));
+        // Both numbers, one pass, one map (#147). `done` counts a SUBSET of what
+        // `total` counts, so `done <= total` is a property of set cardinality and
+        // cannot be broken by a message ordering, a redelivery, a re-title, a row
+        // being deleted or a turn boundary.
+        //
+        // Tasks that outlived an earlier turn keep that turn's epoch: they still
+        // render as live rows – background work outliving its turn is the whole
+        // point of the tray – but they belong to neither number here.
+        let total = 0;
+        let done = 0;
+        for (const task of this.tasks.values()) {
+            if (task.turnEpoch !== this.turnEpoch)
+                continue;
+            total += 1;
+            if (task.status !== 'running')
+                done += 1;
+        }
+        const payload = { type: 'agent_tasks', tasks, done, total };
+        // A frame that says exactly what the last one said is not worth a row in
+        // the session feed (QA-111 M4). Progress reports fire every ~30s per running
+        // subagent and usually carry nothing new, and with twenty of them that
+        // alone is the throttle's whole budget. `ageMs` is excluded from the
+        // comparison on purpose – it changes every time by definition, and including
+        // it would make every frame unique and the check pointless.
+        const fingerprint = JSON.stringify({
+            done: payload.done,
+            total: payload.total,
+            tasks: tasks.map(({ ageMs: _ageMs, ...rest }) => rest),
+        });
+        if (fingerprint === this.lastFingerprint)
+            return;
+        this.lastFingerprint = fingerprint;
+        this.opts.emit(payload);
+    }
+}
+//# sourceMappingURL=agent-tasks.js.map