@namzu/sdk 6.0.0 → 6.2.0

package/src/agents/__tests__/supervisor-coordinator-registration.test.ts

@@ -55,6 +55,7 @@ const hostTool = (name: string) =>
 async function runWith(options: {
 	hostTools?: string[]
 	runtimeToolOverrides?: Record<string, 'active' | 'deferred' | 'disabled'>
+	allowDelegation?: boolean
 }) {
 	const agent = new SupervisorAgent({
 		id: 'supervisor',
@@ -80,6 +81,9 @@ async function runWith(options: {
 		{
 			provider,
 			agentIds: ['worker'],
+			...(options.allowDelegation !== undefined
+				? { allowDelegation: options.allowDelegation }
+				: {}),
 			agentManager: stubManager(),
 			tools,
 			systemPrompt: 'You coordinate.',
@@ -146,3 +150,36 @@ describe('supervisor coordinator-tool registration', () => {
 		expect(describedAs('create_task')).toBe(HOST_TOOL_DESCRIPTION)
 	})
 })
+
+/**
+ * The one hop between `SupervisorAgentConfig.allowDelegation` and the builder
+ * that acts on it.
+ *
+ * These go through `SupervisorAgent` rather than calling the builder directly,
+ * and that is the entire point. The builder has its own unit tests, and they
+ * pass whether or not the supervisor actually forwards the flag — measured:
+ * deleting the forward left the type-check clean and all 143 coordinator and
+ * agent tests green, with the field settable, documented, and read by nobody.
+ * That is the shape of a declaration this repository has had to go and delete
+ * before, so it gets a test that fails when the road is cut.
+ */
+describe('allowDelegation reaches the tool surface', () => {
+	it('withholds the delegation tools when the run declines to delegate', async () => {
+		const { names } = await runWith({ allowDelegation: false })
+
+		expect(names, 'the flag never reached buildCoordinatorTools').not.toContain('create_task')
+		expect(names).not.toContain('wait_for_task')
+		expect(names).not.toContain('cancel_task')
+	})
+
+	it('keeps the listing, so a non-delegating run can still see what is running', async () => {
+		expect((await runWith({ allowDelegation: false })).names).toContain('agent_task_list')
+	})
+
+	it('leaves an opting-in run exactly as it was', async () => {
+		const { names } = await runWith({ allowDelegation: true })
+
+		expect(names).toContain('create_task')
+		expect(names).toContain('agent_task_list')
+	})
+})

package/src/gateway/__tests__/completion-inbox.test.ts

@@ -0,0 +1,343 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { TaskGateway, TaskHandle } from '../../types/agent/gateway.js'
+import type { TaskId } from '../../types/ids/index.js'
+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: string, result?: string): TaskHandle {
+	return {
+		taskId: taskId as TaskId,
+		agentId: 'reviewer',
+		state: 'completed',
+		createdAt: 1_000,
+		completedAt: 3_500,
+		...(result !== undefined
+			? { result: { status: 'completed', result } as TaskHandle['result'] }
+			: {}),
+	}
+}
+
+/** A gateway that only does the one thing the inbox uses. */
+function fakeGateway(): {
+	gateway: TaskGateway
+	settle: (h: TaskHandle) => void
+	listeners: number
+} {
+	const listeners = new Set<(h: TaskHandle) => void>()
+	const gateway = {
+		onTaskCompleted(cb: (h: TaskHandle) => void) {
+			listeners.add(cb)
+			return () => listeners.delete(cb)
+		},
+	} as unknown as TaskGateway
+	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' as TaskId)
+
+		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' as TaskId)
+		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' as TaskId)
+
+		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' as TaskId)
+		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' as TaskId)
+
+		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' as TaskId)
+		inbox.expect('tsk_1' as TaskId)
+
+		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' as TaskId)
+
+		settle(handleFor('tsk_1', 'the worker finished before the cancel landed'))
+		inbox.forget('tsk_1' as TaskId)
+
+		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' as TaskId)
+
+		inbox.forget('tsk_1' as TaskId)
+
+		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' as TaskId)
+
+		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' as TaskId)
+
+		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' as TaskId)
+
+		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 } as unknown as TaskGateway)
+
+		expect(onTaskCompleted).toHaveBeenCalledTimes(1)
+	})
+})

package/src/gateway/completion-inbox.ts

@@ -0,0 +1,241 @@
+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 class CompletionInbox {
+	private readonly unheard = new Map<TaskId, TaskHandle>()
+	private readonly claimed = new Set<TaskId>()
+	/** Launched with nothing waiting on it, and not settled yet. */
+	private readonly outstanding = new Set<TaskId>()
+	private readonly arrivals = new Set<() => void>()
+	private detach?: () => void
+
+	/**
+	 * 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 {
+		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: TaskId): void {
+		if (this.claimed.has(taskId)) return
+		this.outstanding.add(taskId)
+	}
+
+	/** Whether anything is either waiting to be told or still running. */
+	get hasPendingWork(): boolean {
+		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: number): Promise<void> {
+		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)
+			// `unref` where the runtime has it, so a pending wait never keeps
+			// a process alive past the work it was waiting for.
+			;(timer as { unref?: () => void }).unref?.()
+
+			function finish(): void {
+				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: TaskId): void {
+		this.claimed.add(taskId)
+		this.unheard.delete(taskId)
+		this.outstanding.delete(taskId)
+	}
+
+	/** Whether anything is waiting to be told. */
+	get hasUnheard(): boolean {
+		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(): TaskHandle[] {
+		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: TaskId): void {
+		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(): void {
+		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: readonly TaskHandle[]): string {
+	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')}`
+}

package/src/public-runtime.ts

@@ -232,6 +232,10 @@ export {
 export { InMemoryThreadStore } from './store/thread/memory.js'
 
 export { LocalTaskGateway } from './gateway/local.js'
+// Exported because `buildCoordinatorTools` is: a host that builds the
+// coordinator surface itself needs the same inbox the loop drains, or its
+// abandoned completions go unheard exactly as they did before.
+export { CompletionInbox, formatCompletionNotification } from './gateway/completion-inbox.js'
 
 // ─── providers, sandbox, vault ───────────────────────────────────────────
 

package/src/registry/tool/__tests__/dialect.test.ts

@@ -69,16 +69,19 @@ describe('saying a schema in the dialect a wire parses', () => {
 		})
 	})
 
-	it('drops `additionalItems: false`, which both dialects already imply', () => {
-		// Not a lossy shortcut: once `prefixItems` is set, a closed tuple is the
-		// default in 2020-12, so emitting `items: false` would add a byte to
-		// every request to say what was already true.
+	it('keeps a closed tuple closed', () => {
+		// This assertion used to be its own opposite, and the comment under it
+		// was wrong about the dialect: it claimed a closed tuple is 2020-12's
+		// default once `prefixItems` is set. It is not — with no `items`,
+		// elements past the tuple are UNCONSTRAINED. Dropping the `false`
+		// turned a schema written to forbid a third element into one that
+		// allows any, which is a silent widening rather than a saved byte.
 		expect(
 			toSchemaDialect(
 				{ type: 'array', items: [{ type: 'integer' }], additionalItems: false },
 				'2020-12',
 			),
-		).toEqual({ type: 'array', prefixItems: [{ type: 'integer' }] })
+		).toEqual({ type: 'array', prefixItems: [{ type: 'integer' }], items: false })
 	})
 
 	it('ignores `additionalItems` with no tuple to qualify', () => {