@namzu/sdk 6.0.0 → 6.2.0

package/dist/gateway/__tests__/completion-inbox.test.js

@@ -0,0 +1,275 @@
+import { describe, expect, it, vi } from 'vitest';
+import { CompletionInbox, formatCompletionNotification } from '../completion-inbox.js';
+/**
+ * Who tells the supervisor a worker finished.
+ *
+ * Normally the `create_task` call does: it blocks, and the worker's output
+ * comes back as that call's `tool_result`. Two cases have no such call — a
+ * launch made in the background, and a blocking launch whose deadline passed
+ * while the worker kept going — and until this existed the result of those
+ * simply vanished. The gateway still held it; nothing ever read it.
+ *
+ * An earlier version of this channel was removed in `dc16d58` because it
+ * fired for completions the blocking tool had ALREADY delivered, so the
+ * supervisor saw every result twice: once as a `tool_result`, once as an
+ * orphan envelope. That removal is the reason the tests below care as much
+ * about what does NOT get delivered as about what does.
+ */
+function handleFor(taskId, result) {
+    return {
+        taskId: taskId,
+        agentId: 'reviewer',
+        state: 'completed',
+        createdAt: 1_000,
+        completedAt: 3_500,
+        ...(result !== undefined
+            ? { result: { status: 'completed', result } }
+            : {}),
+    };
+}
+/** A gateway that only does the one thing the inbox uses. */
+function fakeGateway() {
+    const listeners = new Set();
+    const gateway = {
+        onTaskCompleted(cb) {
+            listeners.add(cb);
+            return () => listeners.delete(cb);
+        },
+    };
+    return {
+        gateway,
+        settle: (h) => {
+            for (const cb of listeners)
+                cb(h);
+        },
+        get listeners() {
+            return listeners.size;
+        },
+    };
+}
+describe('a completion nobody waited for reaches the transcript', () => {
+    it('queues a settled task and hands it over once', () => {
+        const { gateway, settle } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        settle(handleFor('tsk_1', 'the report'));
+        expect(inbox.hasUnheard).toBe(true);
+        expect(inbox.drain().map((h) => h.taskId)).toEqual(['tsk_1']);
+        // Drained, not peeked: a notification that survives its own delivery
+        // is the duplicate bug wearing a different hat.
+        expect(inbox.drain()).toEqual([]);
+        expect(inbox.hasUnheard).toBe(false);
+    });
+    it('queues nothing at all when no task settles', () => {
+        const { gateway } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        expect(inbox.hasUnheard).toBe(false);
+        expect(inbox.drain()).toEqual([]);
+    });
+});
+describe('a completion the tool already delivered is never delivered twice', () => {
+    it('drops a claimed completion', () => {
+        // The `dc16d58` regression, pinned. `create_task` blocked, got the
+        // result, and returned it as its own tool_result — so the envelope
+        // must not also carry it.
+        const { gateway, settle } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        settle(handleFor('tsk_1', 'the report'));
+        inbox.claim('tsk_1');
+        expect(inbox.hasUnheard).toBe(false);
+        expect(inbox.drain()).toEqual([]);
+    });
+    it('drops it even when the claim beats the announcement', () => {
+        // Ordering is not guaranteed: the tool's own `waitForTask` can resolve
+        // before the gateway's completion listener runs. A claim that only
+        // worked after the announcement would leak a duplicate exactly in the
+        // races that are hardest to reproduce.
+        const { gateway, settle } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        inbox.claim('tsk_1');
+        settle(handleFor('tsk_1', 'the report'));
+        expect(inbox.drain()).toEqual([]);
+    });
+    it('still delivers the sibling that nobody claimed', () => {
+        // The mixed turn: one worker awaited to completion, one abandoned.
+        const { gateway, settle } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        settle(handleFor('tsk_awaited', 'delivered inline'));
+        settle(handleFor('tsk_abandoned', 'nobody heard this'));
+        inbox.claim('tsk_awaited');
+        expect(inbox.drain().map((h) => h.taskId)).toEqual(['tsk_abandoned']);
+    });
+    it('subscribes once no matter how often it is attached', () => {
+        // Two subscriptions would queue every completion twice and reproduce
+        // the duplicate delivery from the inside.
+        const { gateway, settle, ...rest } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        inbox.attach(gateway);
+        settle(handleFor('tsk_1', 'once'));
+        expect(inbox.drain()).toHaveLength(1);
+        void rest;
+    });
+    it('stops listening when closed', () => {
+        const { gateway, settle } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        inbox.close();
+        settle(handleFor('tsk_1', 'too late'));
+        expect(inbox.drain()).toEqual([]);
+    });
+});
+describe('a launch nobody is waiting for holds the run open', () => {
+    it('counts an expected task as pending work before it settles', () => {
+        // Without this the run settles while a background worker is still
+        // going and discards the result the launch existed to produce.
+        const { gateway } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        expect(inbox.hasPendingWork).toBe(false);
+        inbox.expect('tsk_1');
+        expect(inbox.hasPendingWork).toBe(true);
+    });
+    it('stops counting it once it settles', () => {
+        const { gateway, settle } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        inbox.expect('tsk_1');
+        settle(handleFor('tsk_1', 'done'));
+        // Still pending — as an UNHEARD completion now rather than an
+        // outstanding one, which is what the loop drains.
+        expect(inbox.hasPendingWork).toBe(true);
+        inbox.drain();
+        expect(inbox.hasPendingWork).toBe(false);
+    });
+    it('ignores a task already delivered inline', () => {
+        const { gateway } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        inbox.claim('tsk_1');
+        inbox.expect('tsk_1');
+        expect(inbox.hasPendingWork).toBe(false);
+    });
+    it('keeps a result that already arrived, even when the task is cancelled', () => {
+        // The window: a worker finishes, its completion is queued for the next
+        // drain, and the model — told nothing yet, and reading a tool that says
+        // it cancels a RUNNING task — cancels it. Clearing the queue here threw
+        // away work that was done and output that existed nowhere else.
+        //
+        // `forget` is about pending work. A finished result is not pending work.
+        const { gateway, settle } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        inbox.expect('tsk_1');
+        settle(handleFor('tsk_1', 'the worker finished before the cancel landed'));
+        inbox.forget('tsk_1');
+        const drained = inbox.drain();
+        expect(drained.map((h) => h.taskId), 'the finished result was discarded').toEqual(['tsk_1']);
+        expect(drained[0]?.result?.result).toBe('the worker finished before the cancel landed');
+    });
+    it('stops expecting a task that was cancelled', () => {
+        // `expect` is only cleared by a COMPLETION, so a cancelled worker used
+        // to keep the run open for the whole grace period, every time it tried
+        // to settle, waiting for a result that had been called off.
+        const { gateway } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        inbox.expect('tsk_1');
+        inbox.forget('tsk_1');
+        expect(inbox.hasPendingWork).toBe(false);
+    });
+    it('waits for an arrival and returns as soon as one lands', async () => {
+        const { gateway, settle } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        inbox.expect('tsk_1');
+        const waited = inbox.waitForArrival(5_000);
+        settle(handleFor('tsk_1', 'done'));
+        await waited;
+        expect(inbox.drain().map((h) => h.taskId)).toEqual(['tsk_1']);
+    });
+    it('does not wait at all when there is nothing outstanding', async () => {
+        const { gateway } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        // A deadline this long would hang the suite if it were honoured.
+        await inbox.waitForArrival(600_000);
+    });
+    it('gives up at the deadline rather than holding a run forever', async () => {
+        // The bound is the point: a worker that never finishes must not keep
+        // the run open indefinitely.
+        const { gateway } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        inbox.expect('tsk_never');
+        await inbox.waitForArrival(10);
+        expect(inbox.hasPendingWork).toBe(true);
+    });
+    it('releases a waiter when the inbox closes', async () => {
+        const { gateway } = fakeGateway();
+        const inbox = new CompletionInbox();
+        inbox.attach(gateway);
+        inbox.expect('tsk_1');
+        const waited = inbox.waitForArrival(600_000);
+        inbox.close();
+        await waited;
+    });
+});
+describe('the notification says which task and what it produced', () => {
+    it('carries the id, the agent, the state and the output', () => {
+        // All four matter. Without the id the supervisor cannot say which of
+        // five workers this was; without the output it has to make the extra
+        // call this mechanism exists to remove.
+        const text = formatCompletionNotification([handleFor('tsk_42', 'the findings')]);
+        expect(text).toContain('task_id: tsk_42');
+        expect(text).toContain('agent: reviewer');
+        expect(text).toContain('state: completed');
+        expect(text).toContain('duration_ms: 2500');
+        expect(text).toContain('the findings');
+    });
+    it('names the tool that fetches the rest when it truncates', () => {
+        const text = formatCompletionNotification([handleFor('tsk_42', 'x'.repeat(10_000))]);
+        expect(text).toContain('truncated');
+        // The id is repeated in the truncation notice, so the follow-up call
+        // does not require scrolling back up through 4 kB of output.
+        expect(text).toContain('wait_for_task with task_id "tsk_42"');
+        expect(text.length).toBeLessThan(4_500);
+    });
+    it('says so rather than going blank when a task produced nothing', () => {
+        const text = formatCompletionNotification([handleFor('tsk_42')]);
+        expect(text).toContain('task_id: tsk_42');
+        expect(text).toContain('produced no output');
+    });
+    it('groups a batch into one message', () => {
+        const text = formatCompletionNotification([
+            handleFor('tsk_1', 'first'),
+            handleFor('tsk_2', 'second'),
+        ]);
+        expect(text).toContain('2 tasks');
+        expect(text).toContain('tsk_1');
+        expect(text).toContain('tsk_2');
+    });
+    it('explains why it is arriving here and not as a tool result', () => {
+        // Otherwise the model has to guess whether it missed a call, and the
+        // guess it makes is to go looking — which is the polling loop again.
+        const text = formatCompletionNotification([handleFor('tsk_1', 'done')]);
+        expect(text).toContain('not waiting on it');
+    });
+});
+describe('the inbox does not require anything of a host gateway', () => {
+    it('uses only onTaskCompleted', () => {
+        // The whole point of attaching through the existing subscription: a
+        // host that implements TaskGateway keeps working untouched, and one
+        // that was already firing completions into an empty listener set now
+        // has a listener.
+        const onTaskCompleted = vi.fn(() => () => { });
+        const inbox = new CompletionInbox();
+        inbox.attach({ onTaskCompleted });
+        expect(onTaskCompleted).toHaveBeenCalledTimes(1);
+    });
+});
+//# sourceMappingURL=completion-inbox.test.js.map

package/dist/gateway/__tests__/completion-inbox.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-inbox.test.js","sourceRoot":"","sources":["../../../src/gateway/__tests__/completion-inbox.test.ts"],"names":[],"mappings":"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"}

package/dist/gateway/completion-inbox.d.ts

@@ -0,0 +1,113 @@
+import type { TaskGateway, TaskHandle } from '../types/agent/gateway.js';
+import type { TaskId } from '../types/ids/index.js';
+/**
+ * Completions that finished with nobody left to hear them.
+ *
+ * A worker's result reaches the supervisor as the `tool_result` of the
+ * `create_task` that launched it. That works whenever the launching call is
+ * still the live path — but it is not the only way a task ends:
+ *
+ *  - the launching tool hit its deadline and the executor returned
+ *    *"timed out… it may still be running"* to the model. The worker then
+ *    finished normally, holding a result nothing would ever read.
+ *  - the task was launched in the background on purpose, so there is no
+ *    call waiting on it by design.
+ *
+ * In both cases the completion exists, the gateway remembers it, and the
+ * model is never told. That is the gap this closes: the run subscribes once,
+ * every settled task lands here, and anything a tool did NOT hand over
+ * inline is drained into the transcript as a notification the next turn can
+ * read.
+ *
+ * The disambiguation is the whole design. An earlier version of the envelope
+ * path was removed (`dc16d58`) because it fired for completions the blocking
+ * tool had ALREADY delivered, so the supervisor saw every result twice —
+ * once correctly as a `tool_result`, once as an orphan envelope. Removing it
+ * fixed the duplicate and left the abandoned case with no channel at all.
+ * Claiming is what tells the two apart: a tool that delivers a completion
+ * says so, and only unclaimed completions become envelopes.
+ *
+ * It attaches through `onTaskCompleted`, which every `TaskGateway` already
+ * has, so a host gateway needs no change to take part — a host that was
+ * firing completions into a listener set with no listeners now has one.
+ */
+export declare class CompletionInbox {
+    private readonly unheard;
+    private readonly claimed;
+    /** Launched with nothing waiting on it, and not settled yet. */
+    private readonly outstanding;
+    private readonly arrivals;
+    private detach?;
+    /**
+     * Start listening.
+     *
+     * Returns a detach function; calling `attach` twice is a no-op rather
+     * than a second subscription, because a doubly-attached inbox would
+     * queue every completion twice and reproduce the exact duplicate this
+     * class exists to prevent.
+     */
+    attach(gateway: TaskGateway): () => void;
+    /**
+     * Say that a task was launched with nothing waiting on it.
+     *
+     * Without this the inbox can only see completions that have already
+     * happened, and a run whose supervisor launched a background worker and
+     * then answered would settle while the worker was still going — throwing
+     * away the very result the launch existed to produce. Knowing a task is
+     * outstanding is what lets the loop hold the run open for it.
+     */
+    expect(taskId: TaskId): void;
+    /** Whether anything is either waiting to be told or still running. */
+    get hasPendingWork(): boolean;
+    /**
+     * Wait for the next completion, or for the deadline, whichever comes first.
+     *
+     * Bounded on purpose. A worker that never finishes must not hold a run
+     * open forever, and the caller decides how long "long enough" is — the
+     * run's own budget is the only thing that knows.
+     */
+    waitForArrival(timeoutMs: number): Promise<void>;
+    /**
+     * Say that this completion reached the model as a `tool_result`.
+     *
+     * Idempotent, and safe to call before the completion is announced: the
+     * claim is remembered so a late announcement does not re-queue it.
+     */
+    claim(taskId: TaskId): void;
+    /** Whether anything is waiting to be told. */
+    get hasUnheard(): boolean;
+    /**
+     * Take every unheard completion, leaving the inbox empty.
+     *
+     * Draining rather than peeking: a notification that stays queued after
+     * being delivered is the duplicate-delivery bug in a different costume.
+     */
+    drain(): TaskHandle[];
+    /**
+     * Stop expecting a task that is never going to arrive.
+     *
+     * Cancelling is the case this exists for. `expect` puts a task on the
+     * outstanding list and only a COMPLETION takes it off, so a cancelled
+     * worker left `hasPendingWork` true for the rest of the run — and every
+     * attempt to settle then paid the full grace period waiting for a result
+     * that had been called off.
+     */
+    forget(taskId: TaskId): void;
+    /** Stop listening. Safe to call more than once. */
+    close(): void;
+}
+/**
+ * The message a supervisor reads when a worker it stopped waiting for
+ * finishes.
+ *
+ * It carries the task id, because without one the model cannot say which of
+ * five workers this was, and it carries the output, because a notification
+ * that only says "done" forces exactly the follow-up call this mechanism
+ * exists to remove. Long output is truncated with the task id repeated in
+ * the truncation notice, so the full text stays one `wait_for_task` away and
+ * the model knows which id to ask for — that tool takes a `task_id` and
+ * returns immediately for a task that has already finished, where the
+ * listing takes only a state filter and could not have been followed.
+ */
+export declare function formatCompletionNotification(handles: readonly TaskHandle[]): string;
+//# sourceMappingURL=completion-inbox.d.ts.map

package/dist/gateway/completion-inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-inbox.d.ts","sourceRoot":"","sources":["../../src/gateway/completion-inbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,MAAM,CAAC,CAAY;IAE3B;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,IAAI;IAcxC;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK5B,sEAAsE;IACtE,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED;;;;;;OAMG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BhD;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAM3B,8CAA8C;IAC9C,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;;;OAKG;IACH,KAAK,IAAI,UAAU,EAAE;IAQrB;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAsB5B,mDAAmD;IACnD,KAAK,IAAI,IAAI;CAUb;AAKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CA8BnF"}

package/dist/gateway/completion-inbox.js

@@ -0,0 +1,225 @@
+/**
+ * Completions that finished with nobody left to hear them.
+ *
+ * A worker's result reaches the supervisor as the `tool_result` of the
+ * `create_task` that launched it. That works whenever the launching call is
+ * still the live path — but it is not the only way a task ends:
+ *
+ *  - the launching tool hit its deadline and the executor returned
+ *    *"timed out… it may still be running"* to the model. The worker then
+ *    finished normally, holding a result nothing would ever read.
+ *  - the task was launched in the background on purpose, so there is no
+ *    call waiting on it by design.
+ *
+ * In both cases the completion exists, the gateway remembers it, and the
+ * model is never told. That is the gap this closes: the run subscribes once,
+ * every settled task lands here, and anything a tool did NOT hand over
+ * inline is drained into the transcript as a notification the next turn can
+ * read.
+ *
+ * The disambiguation is the whole design. An earlier version of the envelope
+ * path was removed (`dc16d58`) because it fired for completions the blocking
+ * tool had ALREADY delivered, so the supervisor saw every result twice —
+ * once correctly as a `tool_result`, once as an orphan envelope. Removing it
+ * fixed the duplicate and left the abandoned case with no channel at all.
+ * Claiming is what tells the two apart: a tool that delivers a completion
+ * says so, and only unclaimed completions become envelopes.
+ *
+ * It attaches through `onTaskCompleted`, which every `TaskGateway` already
+ * has, so a host gateway needs no change to take part — a host that was
+ * firing completions into a listener set with no listeners now has one.
+ */
+export class CompletionInbox {
+    unheard = new Map();
+    claimed = new Set();
+    /** Launched with nothing waiting on it, and not settled yet. */
+    outstanding = new Set();
+    arrivals = new Set();
+    detach;
+    /**
+     * Start listening.
+     *
+     * Returns a detach function; calling `attach` twice is a no-op rather
+     * than a second subscription, because a doubly-attached inbox would
+     * queue every completion twice and reproduce the exact duplicate this
+     * class exists to prevent.
+     */
+    attach(gateway) {
+        if (this.detach)
+            return this.detach;
+        this.detach = gateway.onTaskCompleted((handle) => {
+            // A completion claimed before it was announced — a tool that
+            // finished its wait faster than the listener ran — is already
+            // delivered. Nothing to queue.
+            this.outstanding.delete(handle.taskId);
+            if (this.claimed.has(handle.taskId))
+                return;
+            this.unheard.set(handle.taskId, handle);
+            for (const wake of this.arrivals)
+                wake();
+        });
+        return this.detach;
+    }
+    /**
+     * Say that a task was launched with nothing waiting on it.
+     *
+     * Without this the inbox can only see completions that have already
+     * happened, and a run whose supervisor launched a background worker and
+     * then answered would settle while the worker was still going — throwing
+     * away the very result the launch existed to produce. Knowing a task is
+     * outstanding is what lets the loop hold the run open for it.
+     */
+    expect(taskId) {
+        if (this.claimed.has(taskId))
+            return;
+        this.outstanding.add(taskId);
+    }
+    /** Whether anything is either waiting to be told or still running. */
+    get hasPendingWork() {
+        return this.unheard.size > 0 || this.outstanding.size > 0;
+    }
+    /**
+     * Wait for the next completion, or for the deadline, whichever comes first.
+     *
+     * Bounded on purpose. A worker that never finishes must not hold a run
+     * open forever, and the caller decides how long "long enough" is — the
+     * run's own budget is the only thing that knows.
+     */
+    waitForArrival(timeoutMs) {
+        if (this.unheard.size > 0)
+            return Promise.resolve();
+        if (this.outstanding.size === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const timer = setTimeout(finish, timeoutMs);
+            timer.unref?.();
+            function finish() {
+                clearTimeout(timer);
+                wake.done = true;
+                resolve();
+            }
+            const wake = Object.assign(() => {
+                if (!wake.done) {
+                    this.arrivals.delete(wake);
+                    finish();
+                }
+            }, { done: false });
+            this.arrivals.add(wake);
+        });
+    }
+    /**
+     * Say that this completion reached the model as a `tool_result`.
+     *
+     * Idempotent, and safe to call before the completion is announced: the
+     * claim is remembered so a late announcement does not re-queue it.
+     */
+    claim(taskId) {
+        this.claimed.add(taskId);
+        this.unheard.delete(taskId);
+        this.outstanding.delete(taskId);
+    }
+    /** Whether anything is waiting to be told. */
+    get hasUnheard() {
+        return this.unheard.size > 0;
+    }
+    /**
+     * Take every unheard completion, leaving the inbox empty.
+     *
+     * Draining rather than peeking: a notification that stays queued after
+     * being delivered is the duplicate-delivery bug in a different costume.
+     */
+    drain() {
+        if (this.unheard.size === 0)
+            return [];
+        const handles = [...this.unheard.values()];
+        this.unheard.clear();
+        for (const handle of handles)
+            this.claimed.add(handle.taskId);
+        return handles;
+    }
+    /**
+     * Stop expecting a task that is never going to arrive.
+     *
+     * Cancelling is the case this exists for. `expect` puts a task on the
+     * outstanding list and only a COMPLETION takes it off, so a cancelled
+     * worker left `hasPendingWork` true for the rest of the run — and every
+     * attempt to settle then paid the full grace period waiting for a result
+     * that had been called off.
+     */
+    forget(taskId) {
+        this.outstanding.delete(taskId);
+        // `unheard` is deliberately NOT touched.
+        //
+        // The two sets mean different things. `outstanding` is pending WORK,
+        // and cancelling is exactly the statement that it should stop being
+        // waited for. `unheard` is a RESULT that already exists — the worker
+        // finished, the completion arrived, and it is queued for the next
+        // drain. Clearing it here destroyed that.
+        //
+        // The window is small and entirely reachable: nothing has told the
+        // model the worker finished, and `cancel_task` says it cancels a
+        // running task, so cancelling one that has just completed is the
+        // obvious move rather than a mistake. The run then reports "cancelled"
+        // over work that was done and output that no longer exists anywhere.
+        //
+        // Note the asymmetry with `claim`, which does clear `unheard` — and is
+        // right to, because there a tool has just handed the model the same
+        // result. This one hands over nothing.
+        for (const wake of [...this.arrivals])
+            wake();
+    }
+    /** Stop listening. Safe to call more than once. */
+    close() {
+        this.detach?.();
+        this.detach = undefined;
+        this.unheard.clear();
+        this.outstanding.clear();
+        // Release anyone still waiting. A closed inbox would otherwise hold
+        // them to their own deadline for a completion that can no longer come.
+        for (const wake of [...this.arrivals])
+            wake();
+        this.arrivals.clear();
+    }
+}
+/** How much of a worker's output rides in the notification itself. */
+const NOTIFICATION_OUTPUT_LIMIT = 4_000;
+/**
+ * The message a supervisor reads when a worker it stopped waiting for
+ * finishes.
+ *
+ * It carries the task id, because without one the model cannot say which of
+ * five workers this was, and it carries the output, because a notification
+ * that only says "done" forces exactly the follow-up call this mechanism
+ * exists to remove. Long output is truncated with the task id repeated in
+ * the truncation notice, so the full text stays one `wait_for_task` away and
+ * the model knows which id to ask for — that tool takes a `task_id` and
+ * returns immediately for a task that has already finished, where the
+ * listing takes only a state filter and could not have been followed.
+ */
+export function formatCompletionNotification(handles) {
+    const blocks = handles.map((handle) => {
+        const durationMs = handle.completedAt ? handle.completedAt - handle.createdAt : undefined;
+        const output = handle.result?.result ?? handle.result?.lastError ?? '';
+        const truncated = output.length > NOTIFICATION_OUTPUT_LIMIT
+            ? // `wait_for_task`, not `agent_task_list` — the listing takes only a
+                // state filter, so an instruction to call it "with task_id" named
+                // a parameter that does not exist and could not be followed. On an
+                // already-finished task the wait returns immediately.
+                `${output.slice(0, NOTIFICATION_OUTPUT_LIMIT)}\n… truncated. Call wait_for_task with task_id "${handle.taskId}" for the full output.`
+            : output;
+        const lines = [
+            `task_id: ${handle.taskId}`,
+            `agent: ${handle.agentId}`,
+            `state: ${handle.state}`,
+            ...(durationMs !== undefined ? [`duration_ms: ${durationMs}`] : []),
+            '',
+            truncated.length > 0 ? truncated : '(the task produced no output)',
+        ];
+        return `<task-notification>\n${lines.join('\n')}\n</task-notification>`;
+    });
+    const preamble = handles.length === 1
+        ? 'A task you launched has finished. This is its result — you were not waiting on it, so it arrives here rather than as a tool result.'
+        : `${handles.length} tasks you launched have finished. These are their results — you were not waiting on them, so they arrive here rather than as tool results.`;
+    return `${preamble}\n\n${blocks.join('\n\n')}`;
+}
+//# sourceMappingURL=completion-inbox.js.map

package/dist/gateway/completion-inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-inbox.js","sourceRoot":"","sources":["../../src/gateway/completion-inbox.ts"],"names":[],"mappings":"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"}

package/dist/public-runtime.d.ts

@@ -50,6 +50,7 @@ export { discoverAllPluginDirs, discoverPlugins, loadPluginManifest, PluginLifec
 export { AgentManager, EmergencySaveManager, PlanManager, RunPersistence, ThreadManager, } from './manager/index.js';
 export { InMemoryThreadStore } from './store/thread/memory.js';
 export { LocalTaskGateway } from './gateway/local.js';
+export { CompletionInbox, formatCompletionNotification } from './gateway/completion-inbox.js';
 export { classifyProviderError, DEFAULT_PROVIDER_RETRY, DuplicateProviderError, isAbortError, isProviderError, LazyProviderLoadError, LazyProviderSyncCreateError, MOCK_CAPABILITIES, MockLLMProvider, parseRetryAfterMs, PERMISSIVE_PROVIDER_CAPABILITIES, ProviderError, ProviderRegistry, ProviderRequestError, registerMock, resolveProviderCapabilities, UnknownProviderError, withProviderRetry, } from './provider/index.js';
 export type { ProviderRetryConfig, WithProviderRetryOptions } from './provider/index.js';
 export { assertIsolation, describeIsolation, isolationOf, LocalSandboxProvider, missingIsolation, SandboxProviderFactory, } from './sandbox/index.js';