@namzu/sdk 5.2.0 → 6.1.0

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

@@ -0,0 +1,320 @@
+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('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,227 @@
+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)
+		this.unheard.delete(taskId)
+		// Anyone waiting should re-check rather than sit out their deadline
+		// for a task that is no longer coming.
+		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/provider/__tests__/strict-schema.test.ts

@@ -80,12 +80,17 @@ describe('the violation report names the exact path', () => {
 		expect(findStrictSchemaViolations(schema)).toEqual([])
 	})
 
-	it('reports numeric and string bounds, which are also outside the subset', () => {
+	it('reports the bounds the wire refuses, and only those', () => {
+		// Measured against the live API rather than read off a page. The first
+		// version of this list was derived from documentation and was wrong in
+		// both directions: it refused `maxLength`, which the wire accepts, and
+		// permitted `prefixItems`, which it rejects.
 		const schema = {
 			type: 'object',
 			properties: {
 				n: { type: 'integer', minimum: 0 },
 				s: { type: 'string', maxLength: 10 },
+				a: { type: 'array', items: { type: 'string' }, maxItems: 3, minItems: 1 },
 			},
 		}
 
@@ -93,7 +98,58 @@ describe('the violation report names the exact path', () => {
 			findStrictSchemaViolations(schema)
 				.map((v) => v.keyword)
 				.sort(),
-		).toEqual(['maxLength', 'minimum'])
+		).toEqual(['maxItems', 'minimum'])
+	})
+
+	it('leaves string length alone, because strict accepts it', () => {
+		// The false positive that would have refused tools which work.
+		expect(
+			findStrictSchemaViolations({ s: { type: 'string', minLength: 1, maxLength: 9 } }),
+		).toEqual([])
+	})
+
+	it('catches a tuple in either spelling, because strict admits neither', () => {
+		// The interaction worth pinning, and the one a `prefixItems` entry alone
+		// got wrong. This check runs at REGISTRATION, on the schema as rendered
+		// — draft-07, where a tuple is `items: [a, b]` — while the wire sees the
+		// `prefixItems` the driver converts it to. So denying only `prefixItems`
+		// was a guard that could not fire on the path that produces tuples.
+		//
+		// Measured, strict rejects both, which is why a tool that is both strict
+		// and tuple-shaped cannot be expressed at all. Converting it only
+		// changes which error comes back.
+		for (const items of [
+			{ prefixItems: [{ type: 'integer' }, { type: 'integer' }] },
+			{ items: [{ type: 'integer' }, { type: 'integer' }] },
+		]) {
+			const violations = findStrictSchemaViolations({
+				properties: { range: { type: 'array', ...items } },
+			})
+
+			expect(violations, JSON.stringify(items)).toHaveLength(1)
+			expect(violations[0]?.remedy).toContain('tuple cannot be expressed')
+		}
+	})
+
+	it('leaves an ordinary array alone, where `items` is one schema', () => {
+		// The false positive the tuple rule must not become: `items` is the
+		// normal spelling for a homogeneous array and strict accepts it. Only
+		// the array-of-schemas form is a tuple.
+		expect(findStrictSchemaViolations({ type: 'array', items: { type: 'string' } })).toEqual([])
+	})
+
+	it('admits minItems at 0 or 1 and refuses it above, as the wire does', () => {
+		// A blanket denial here was a false positive with a real cost: it
+		// refuses `z.array(...).nonempty()`, which renders `minItems: 1` and
+		// which the wire accepts. The constraint is on the VALUE, and the
+		// vendor's error says so — "'minItems' values other than 0 or 1 are not
+		// supported".
+		expect(findStrictSchemaViolations({ type: 'array', minItems: 0 })).toEqual([])
+		expect(findStrictSchemaViolations({ type: 'array', minItems: 1 })).toEqual([])
+
+		const violations = findStrictSchemaViolations({ type: 'array', minItems: 2 })
+		expect(violations).toHaveLength(1)
+		expect(violations[0]?.keyword).toBe('minItems')
 	})
 
 	it('admits additionalProperties only as false', () => {