@namzu/sdk 6.2.0 → 7.0.0

package/src/tools/coordinator/__tests__/wait-with-idle-bound.test.ts

@@ -0,0 +1,247 @@
+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 { describeWaitTimeout, waitForTaskWithBounds } from '../wait-with-idle-bound.js'
+
+/**
+ * A wall clock cannot tell a slow worker from a stuck one.
+ *
+ * The bound before this was an hour of elapsed time, and an hour has to do
+ * two incompatible jobs: be long enough for a child doing real work, and
+ * short enough to notice one that wedged. It cannot be both, so a worker
+ * stuck in minute two held the supervisor for another fifty-eight, and one
+ * making steady progress at minute fifty-nine was killed for being slow.
+ *
+ * These tests drive both clocks with a fake one, because the real bounds are
+ * measured in minutes and a test that actually waits them out is a test
+ * nobody runs.
+ */
+
+function gatewayFor(opts: {
+	/** Resolve the wait when this is called. */
+	settle?: (resolve: (h: TaskHandle) => void) => void
+	withProgress?: boolean
+}): { gateway: TaskGateway; progress: () => void; finish: () => void } {
+	let resolveWait: ((h: TaskHandle) => void) | undefined
+	const listeners = new Set<(id: TaskId) => void>()
+
+	const handle: TaskHandle = {
+		taskId: 'tsk_1' as TaskId,
+		agentId: 'worker',
+		state: 'completed',
+		createdAt: 0,
+		completedAt: 1,
+	}
+
+	const gateway = {
+		waitForTask: () =>
+			new Promise<TaskHandle>((resolve) => {
+				resolveWait = resolve
+				opts.settle?.(resolve)
+			}),
+		...(opts.withProgress === false
+			? {}
+			: {
+					onTaskProgress: (cb: (id: TaskId) => void) => {
+						listeners.add(cb)
+						return () => listeners.delete(cb)
+					},
+				}),
+	} as unknown as TaskGateway
+
+	return {
+		gateway,
+		progress: () => {
+			for (const cb of listeners) cb('tsk_1' as TaskId)
+		},
+		finish: () => resolveWait?.(handle),
+	}
+}
+
+/** A clock the test moves by hand. */
+function fakeClock(): { now: () => number; advance: (ms: number) => void } {
+	let t = 1_000_000
+	return {
+		now: () => t,
+		advance: (ms) => {
+			t += ms
+		},
+	}
+}
+
+describe('a worker that is still working is not killed for being slow', () => {
+	it('keeps waiting past the idle bound while progress keeps arriving', async () => {
+		vi.useFakeTimers()
+		try {
+			const clock = fakeClock()
+			const { gateway, progress, finish } = gatewayFor({})
+
+			const waiting = waitForTaskWithBounds(
+				gateway,
+				'tsk_1' as TaskId,
+				{ runMs: 60_000, idleMs: 5_000 },
+				clock.now,
+			)
+
+			// Four times the idle bound in elapsed time, but never quiet for
+			// more than half of it.
+			for (let i = 0; i < 8; i += 1) {
+				clock.advance(2_500)
+				progress()
+				await vi.advanceTimersByTimeAsync(1_000)
+			}
+
+			finish()
+			await vi.advanceTimersByTimeAsync(1_000)
+
+			expect((await waiting).kind, 'a working worker was cut off').toBe('completed')
+		} finally {
+			vi.useRealTimers()
+		}
+	})
+})
+
+describe('a worker that has gone quiet is reported as quiet', () => {
+	it('fires the idle bound and says which clock it was', async () => {
+		vi.useFakeTimers()
+		try {
+			const clock = fakeClock()
+			const { gateway } = gatewayFor({})
+
+			const waiting = waitForTaskWithBounds(
+				gateway,
+				'tsk_1' as TaskId,
+				{ runMs: 600_000, idleMs: 5_000 },
+				clock.now,
+			)
+
+			clock.advance(6_000)
+			await vi.advanceTimersByTimeAsync(1_100)
+
+			const outcome = await waiting
+			expect(outcome.kind).toBe('timeout')
+			if (outcome.kind !== 'timeout') return
+			// The distinction is the point: "went quiet" and "ran too long"
+			// are different diagnoses and the caller acts on the message.
+			expect(outcome.cause).toBe('idle')
+			expect(outcome.idleBoundArmed).toBe(true)
+		} finally {
+			vi.useRealTimers()
+		}
+	})
+
+	it('says it went quiet, and that the worker was not cancelled', () => {
+		const text = describeWaitTimeout({
+			kind: 'timeout',
+			cause: 'idle',
+			elapsedMs: 30_000,
+			idleBoundArmed: true,
+		})
+
+		expect(text).toContain('went quiet')
+		// A wait that ran out is a statement about the WAITER. Losing an
+		// eight-minute worker's output because a short clock expired is the
+		// bug this whole area has been unpicking.
+		expect(text).toContain('not been cancelled')
+	})
+})
+
+describe('the run bound still catches a worker that never stops', () => {
+	it('fires on elapsed time even while progress keeps arriving', async () => {
+		vi.useFakeTimers()
+		try {
+			const clock = fakeClock()
+			const { gateway, progress } = gatewayFor({})
+
+			const waiting = waitForTaskWithBounds(
+				gateway,
+				'tsk_1' as TaskId,
+				{ runMs: 10_000, idleMs: 5_000 },
+				clock.now,
+			)
+
+			for (let i = 0; i < 6; i += 1) {
+				clock.advance(2_000)
+				progress()
+				await vi.advanceTimersByTimeAsync(1_000)
+			}
+
+			const outcome = await waiting
+			expect(outcome.kind).toBe('timeout')
+			if (outcome.kind !== 'timeout') return
+			expect(outcome.cause).toBe('run')
+		} finally {
+			vi.useRealTimers()
+		}
+	})
+})
+
+describe('a gateway that cannot see its children', () => {
+	it('is bounded by the wall clock alone, as it was before', async () => {
+		vi.useFakeTimers()
+		try {
+			const clock = fakeClock()
+			const { gateway } = gatewayFor({ withProgress: false })
+
+			const waiting = waitForTaskWithBounds(
+				gateway,
+				'tsk_1' as TaskId,
+				{ runMs: 10_000, idleMs: 1_000 },
+				clock.now,
+			)
+
+			// Far past the idle bound, and it must NOT fire — there is no
+			// signal, so silence carries no information.
+			clock.advance(5_000)
+			await vi.advanceTimersByTimeAsync(1_100)
+			clock.advance(6_000)
+			await vi.advanceTimersByTimeAsync(1_100)
+
+			const outcome = await waiting
+			expect(outcome.kind).toBe('timeout')
+			if (outcome.kind !== 'timeout') return
+			expect(outcome.cause).toBe('run')
+			// And the degradation is visible rather than silent.
+			expect(outcome.idleBoundArmed).toBe(false)
+		} finally {
+			vi.useRealTimers()
+		}
+	})
+
+	it('says so, instead of implying the worker was stuck', () => {
+		const text = describeWaitTimeout({
+			kind: 'timeout',
+			cause: 'run',
+			elapsedMs: 3_600_000,
+			idleBoundArmed: false,
+		})
+
+		expect(text).toContain('cannot report progress')
+	})
+})
+
+describe('a completion always wins', () => {
+	it('returns the handle rather than a timeout when the task finishes first', async () => {
+		vi.useFakeTimers()
+		try {
+			const clock = fakeClock()
+			const { gateway, finish } = gatewayFor({})
+
+			const waiting = waitForTaskWithBounds(
+				gateway,
+				'tsk_1' as TaskId,
+				{ runMs: 10_000, idleMs: 5_000 },
+				clock.now,
+			)
+
+			finish()
+			await vi.advanceTimersByTimeAsync(10)
+
+			const outcome = await waiting
+			expect(outcome.kind).toBe('completed')
+		} finally {
+			vi.useRealTimers()
+		}
+	})
+})

package/src/tools/coordinator/index.ts

@@ -11,6 +11,7 @@ import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { wrapUntrusted } from '../untrusted-envelope.js'
 import { resolvePlanDependencies } from './plan-dependencies.js'
+import { describeWaitTimeout, waitForTaskWithBounds } from './wait-with-idle-bound.js'
 
 export type TaskLaunchedCallback = (
 	agentTaskId: TaskId,
@@ -259,6 +260,33 @@ const LISTED_RESULT_LIMIT = 2_000
  */
 export const DELEGATION_TIMEOUT_MS = 60 * 60 * 1000
 
+/**
+ * How long a delegated worker may say nothing before the wait gives up.
+ *
+ * The hour above answers "how long is too long". It cannot also answer
+ * "how quiet is too quiet", because it has to be generous enough for a
+ * child doing real work — which makes it useless as a stall detector. A
+ * worker wedged in its second minute held the supervisor for another
+ * fifty-eight under that number alone.
+ *
+ * Five minutes of silence, because a worker between tool calls can be
+ * quiet for a while legitimately — a long model turn emits nothing until
+ * it starts streaming — and the cost of guessing low is killing a wait on
+ * a worker that was fine. Guessing high only delays a diagnosis. Set
+ * `NAMZU_DELEGATION_IDLE_MS` to change it.
+ *
+ * Only armed when the gateway can report progress at all; see
+ * `TaskGateway.onTaskProgress`.
+ */
+export const DELEGATION_IDLE_MS = readPositiveIntEnv('NAMZU_DELEGATION_IDLE_MS', 5 * 60 * 1000)
+
+function readPositiveIntEnv(key: string, fallback: number): number {
+	const value = process.env[key]?.trim()
+	if (!value) return fallback
+	const parsed = Number(value)
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
+}
+
 export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefinition[] {
 	const {
 		gateway,
@@ -379,7 +407,23 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			// assistant turn, the runtime runs them together and delivers all
 			// N `tool_result`s at once. No second `tool_result` for the
 			// same `tool_use_id` — providers reject a duplicated id outright.
-			const completed = await gateway.waitForTask(handle.taskId)
+			// Bounded by two clocks rather than one. The wait gives up on a
+			// worker that has gone quiet long before the hour is out, and says
+			// which of the two ran out — the caller acts on that difference.
+			// Giving up does NOT cancel the child: it keeps going, and its
+			// result still reaches the supervisor as a notification.
+			const outcome = await waitForTaskWithBounds(gateway, handle.taskId, {
+				runMs: DELEGATION_TIMEOUT_MS,
+				idleMs: DELEGATION_IDLE_MS,
+			})
+			if (outcome.kind === 'timeout') {
+				return {
+					success: false,
+					output: describeWaitTimeout(outcome),
+					data: { task_id: handle.taskId, agent_id, timed_out: outcome.cause },
+				}
+			}
+			const completed = outcome.handle
 
 			// Whether this call is still the live path decides who delivers the
 			// result. If the executor already gave up on us — its deadline
@@ -450,55 +494,6 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		},
 	})
 
-	const continueTask = defineTool({
-		name: 'continue_task',
-		description:
-			"Send a follow-up message to a previously completed task and await the agent's next reply. BLOCKING: returns the agent's new output as this call's tool_result, the same shape as create_task. Only use this with a task_id from a previous create_task. To run multiple follow-ups in parallel, call this tool multiple times in a single assistant turn.",
-		inputSchema: z.object({
-			task_id: z.string().describe('Agent task ID from a previous create_task'),
-			message: z.string().describe('Follow-up instruction for the agent'),
-		}),
-		category: 'custom',
-		permissions: [],
-		readOnly: false,
-		destructive: false,
-		concurrencySafe: true,
-		// It waits on a child exactly as create_task does, so it inherits
-		// the same bound rather than the file-read default.
-		timeoutMs: DELEGATION_TIMEOUT_MS,
-		async execute({ task_id, message }, _context) {
-			await gateway.continueTask(task_id as TaskId, message)
-			// Mirror create_task's blocking pattern: await the new
-			// completion and return the agent's output inline. The
-			// previous non-blocking shape ('You will receive a
-			// task-notification…') relied on a global
-			// onTaskCompleted listener that the iteration loop
-			// no longer registers (envelope path is dead).
-			const completed = await gateway.waitForTask(task_id as TaskId)
-			// Same reasoning as create_task: the model already has a timeout
-			// for this call, so leaving the completion unclaimed is what sends
-			// it to the transcript as a notification.
-			if (_context.abortSignal?.aborted) {
-				return {
-					success: false,
-					output: `This wait was abandoned before task ${task_id} finished; its result will arrive separately as a task notification.`,
-					data: { task_id, abandoned: true },
-				}
-			}
-			completionInbox?.claim(task_id as TaskId)
-			const success = completed.state === 'completed'
-			const resultText =
-				completed.result?.result ??
-				completed.result?.lastError ??
-				`Task finished with state: ${completed.state}`
-			return {
-				success,
-				output: resultText,
-				data: { task_id, state: completed.state },
-			}
-		},
-	})
-
 	/**
 	 * Join a task already running, without sending it anything.
 	 *
@@ -533,7 +528,18 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				}
 			}
 
-			const completed = await gateway.waitForTask(task_id as TaskId)
+			const outcome = await waitForTaskWithBounds(gateway, task_id as TaskId, {
+				runMs: DELEGATION_TIMEOUT_MS,
+				idleMs: DELEGATION_IDLE_MS,
+			})
+			if (outcome.kind === 'timeout') {
+				return {
+					success: false,
+					output: describeWaitTimeout(outcome),
+					data: { task_id, timed_out: outcome.cause },
+				}
+			}
+			const completed = outcome.handle
 			if (_context.abortSignal?.aborted) {
 				return {
 					success: false,
@@ -675,18 +681,32 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		},
 	})
 
-	// `continue_task` was a follow-up channel for a still-alive worker
-	// task. With `create_task` now blocking + tool_result returning
-	// the worker's final output, every worker reaches a terminal
-	// state by the time the supervisor wants to follow up — and the
-	// agent manager rejects `continue` on terminal tasks. The
-	// industrial pattern is to issue a fresh `create_task` that
-	// references the prior worker's output path, so we drop
-	// `continue_task` from the registered surface entirely. The
-	// definition stays in this file for now in case a future
-	// non-default gateway (one that keeps the worker process alive
-	// for follow-ups) wants to re-register it.
-	void continueTask
+	// `continue_task` is gone, and the reasoning is worth keeping because
+	// the obvious argument for bringing it back does not survive contact.
+	//
+	// It was dropped on the grounds that a blocking `create_task` leaves every
+	// worker terminal before a later turn learns its id, and the manager
+	// refuses `continue` on a terminal task. `background: true` reinstated that
+	// precondition — a live id is reachable now — so the question was reopened.
+	//
+	// Measured rather than assumed, and it fails on the other side. On a LIVE
+	// task the manager accepts the call and pushes onto `pendingMessages`,
+	// and NOTHING drains that queue during a run. This codebase already
+	// knows: `runtime/query/steering.ts` says in as many words that
+	// `queueMessage`/`drainMessages` were never read by the iteration loop,
+	// and `SteeringChannel` exists BECAUSE of that — it delivers guidance on a
+	// tool result instead, since a `tool_use` must be answered by a
+	// `tool_result` with the same id and there is no legal slot for a user
+	// message mid-batch.
+	//
+	// So the tool had no state it worked in: terminal tasks refuse it, live
+	// tasks accept it into a queue nobody reads. Registering it would have
+	// handed the model a call that silently does nothing — worse than the
+	// unregistered definition it replaced, because a defined-but-unreachable
+	// tool at least cannot be called.
+	//
+	// If follow-ups on a live worker are wanted, the work is a consumer for
+	// the queue or a steering channel that reaches a child, not this tool.
 	// `cancel_task` is registered again, and the reasoning that dropped it is
 	// worth keeping because it was sound at the time and is not any more.
 	//

package/src/tools/coordinator/wait-with-idle-bound.ts

@@ -0,0 +1,142 @@
+import type { TaskGateway, TaskHandle } from '../../types/agent/gateway.js'
+import type { TaskId } from '../../types/ids/index.js'
+
+/**
+ * Waiting on a delegated worker, bounded by two different questions.
+ *
+ * A wall clock alone is the wrong instrument. It has to be long enough to
+ * serve as the outer bound for a child doing real work — an hour, here — and
+ * that is far too long to notice a child that wedged in its second minute.
+ * The same number cannot be both "how long is too long" and "how quiet is too
+ * quiet", so this keeps them apart:
+ *
+ *  - the **run bound** counts elapsed time and is never refreshed. It exists
+ *    for a worker that stays busy forever.
+ *  - the **idle bound** counts time since the worker last did anything, and
+ *    resets whenever it does. It exists for a worker that stopped.
+ *
+ * Whichever fires first ends the wait, and the result says WHICH — because
+ * "it went quiet" and "it ran too long" are different diagnoses and lead to
+ * different next moves. Telling a caller its worker timed out when the worker
+ * was making steady progress is the failure this replaces.
+ *
+ * The idle bound is only armed when the gateway can report progress.
+ * `onTaskProgress` is optional on the contract, because hosts implement
+ * `TaskGateway` and not all of them can observe their children — so a gateway
+ * without it is bounded by the wall clock alone, exactly as before. That is a
+ * real degradation and it is deliberately visible in the result rather than
+ * silent: `idleBoundArmed` says whether the quieter half was ever watching.
+ */
+export type WaitOutcome =
+	| { readonly kind: 'completed'; readonly handle: TaskHandle }
+	| {
+			readonly kind: 'timeout'
+			/** Which clock ran out. */
+			readonly cause: 'idle' | 'run'
+			readonly elapsedMs: number
+			/** False when the gateway cannot report progress, so only the wall clock applied. */
+			readonly idleBoundArmed: boolean
+	  }
+
+export interface WaitBounds {
+	/** Elapsed-time ceiling, never refreshed. */
+	readonly runMs: number
+	/**
+	 * Time-without-progress ceiling, refreshed on every progress signal.
+	 *
+	 * Omit to bound by the run clock alone.
+	 */
+	readonly idleMs?: number
+}
+
+/**
+ * Await a task under both bounds.
+ *
+ * Note what this does NOT do: it does not cancel the worker. A wait that ran
+ * out is a statement about the waiter, not about the work — the child keeps
+ * going, its completion still reaches the inbox, and the supervisor is still
+ * told what it produced. Killing a child because a parent stopped waiting was
+ * never asked for, and losing an eight-minute worker's output because a
+ * two-minute clock expired is the exact shape of the bug this whole area has
+ * been unpicking.
+ */
+export async function waitForTaskWithBounds(
+	gateway: TaskGateway,
+	taskId: TaskId,
+	bounds: WaitBounds,
+	now: () => number = Date.now,
+): Promise<WaitOutcome> {
+	const startedAt = now()
+	let lastProgressAt = startedAt
+	let settled = false
+
+	const detach = gateway.onTaskProgress?.((id) => {
+		if (id === taskId) lastProgressAt = now()
+	})
+	const idleBoundArmed = detach !== undefined && bounds.idleMs !== undefined
+
+	try {
+		const completion = gateway.waitForTask(taskId).then(
+			(handle): WaitOutcome => ({ kind: 'completed', handle }),
+			// A gateway that rejects has answered the question; let it through
+			// rather than reporting a timeout that did not happen.
+			(err) => {
+				throw err
+			},
+		)
+
+		const expiry = new Promise<WaitOutcome>((resolve) => {
+			// Polled rather than scheduled, because the idle deadline MOVES: a
+			// timer armed for it would have to be cleared and rearmed on every
+			// tick of progress, and the one that slipped through would be the
+			// one that mattered. A coarse tick is enough — these bounds are
+			// minutes, and being a second late to notice silence costs nothing.
+			const tick = setInterval(() => {
+				if (settled) return
+				const elapsed = now() - startedAt
+				if (elapsed >= bounds.runMs) {
+					clearInterval(tick)
+					resolve({ kind: 'timeout', cause: 'run', elapsedMs: elapsed, idleBoundArmed })
+					return
+				}
+				if (idleBoundArmed && bounds.idleMs !== undefined) {
+					const quietFor = now() - lastProgressAt
+					if (quietFor >= bounds.idleMs) {
+						clearInterval(tick)
+						resolve({ kind: 'timeout', cause: 'idle', elapsedMs: elapsed, idleBoundArmed })
+					}
+				}
+			}, POLL_INTERVAL_MS)
+			// Never the reason a process stays alive. This one is safe to unref
+			// where the park recorder was not, because nothing AWAITS it alone:
+			// it races a real completion promise, so the wait is held open by
+			// work that is genuinely outstanding rather than by this timer.
+			;(tick as { unref?: () => void }).unref?.()
+		})
+
+		return await Promise.race([completion, expiry])
+	} finally {
+		settled = true
+		detach?.()
+	}
+}
+
+/**
+ * How often the bounds are checked.
+ *
+ * Coarse on purpose: both bounds are measured in minutes, so a second of
+ * latency in noticing is irrelevant, and a tight interval would spend a timer
+ * wakeup per second per in-flight worker for nothing.
+ */
+const POLL_INTERVAL_MS = 1_000
+
+/** What to tell the model, in the words that fit what actually happened. */
+export function describeWaitTimeout(outcome: Extract<WaitOutcome, { kind: 'timeout' }>): string {
+	const seconds = Math.round(outcome.elapsedMs / 1000)
+	if (outcome.cause === 'idle') {
+		return `This worker went quiet: nothing has come from it for a while, after ${seconds}s. It has not been cancelled and may still finish — its result will arrive as a task notification if it does. Check agent_task_list, or start a different approach.`
+	}
+	return outcome.idleBoundArmed
+		? `This worker has been running for ${seconds}s without finishing, though it was still doing something. It has not been cancelled — its result will arrive as a task notification if it finishes.`
+		: `This worker has been running for ${seconds}s without finishing. This gateway cannot report progress, so there is no way to tell a busy worker from a stuck one here. It has not been cancelled — its result will arrive as a task notification if it finishes.`
+}

package/src/types/agent/base.ts

@@ -24,6 +24,23 @@ export interface BaseAgentConfig {
 	permissionMode?: PermissionMode
 	env?: Record<string, string>
 
+	/**
+	 * Thinking mode and response-effort level for every model call this agent
+	 * makes. See {@link import('../run/config.js').AgentRunConfig} for what
+	 * each one controls and why they are siblings.
+	 *
+	 * They are declared HERE, on the shared base, rather than on each agent
+	 * config that happens to want them. Every agent builds its `AgentRunConfig`
+	 * by hand-listing fields, and a field absent from a hand-listed literal is
+	 * dropped in silence — which is exactly how `thinking` came to be settable
+	 * only through the raw kernel entry point while every ergonomic one quietly
+	 * ignored it. Putting them on the base is what makes "did you forget to
+	 * forward it" a type error in the places that matter rather than a support
+	 * question.
+	 */
+	thinking?: import('../provider/index.js').ThinkingConfig
+	effort?: import('../provider/index.js').ReasoningEffort
+
 	/**
 	 * Deduplicate a retried invocation instead of running it twice.
 	 *

package/src/types/agent/gateway.ts

@@ -57,4 +57,28 @@ export interface TaskGateway {
 	listTasks(): TaskHandle[]
 
 	onTaskCompleted(callback: (handle: TaskHandle) => void): () => void
+
+	/**
+	 * Tell me when a task does something, not just when it finishes.
+	 *
+	 * This is what an idle bound is measured against. A wall clock says
+	 * nothing about whether a worker is working: an hour is long enough to
+	 * be useless as a stall detector, and short enough to kill a child that
+	 * is making steady progress at minute fifty-nine. Time-without-progress
+	 * is the quantity that separates "stuck" from "slow", and only the
+	 * gateway can see it.
+	 *
+	 * OPTIONAL, and the absence is meaningful rather than an oversight: a
+	 * gateway that cannot observe its children still works, and its waits
+	 * are bounded by the wall clock alone — which is exactly the behaviour
+	 * before this existed. It is optional because `TaskGateway` is
+	 * implemented by hosts, and a required method would break every one of
+	 * them for a capability not all of them can provide.
+	 *
+	 * Anything the worker did counts: a tool call, an emitted token, a state
+	 * change. What must NOT count is the supervisor's own activity — the
+	 * point is to notice a child that has gone quiet, and a parent polling
+	 * about it is not the child speaking.
+	 */
+	onTaskProgress?(callback: (taskId: TaskId) => void): () => void
 }

package/src/types/agent/lifecycle-event.ts

@@ -11,6 +11,13 @@ export type AgentLifecycleEvent =
 			depth: number
 	  }
 	| { type: 'running'; taskId: TaskId }
+	/**
+	 * **Never emitted.** Nothing constructs this variant, so a host that
+	 * switches on it has written a branch that cannot run — and a host that
+	 * relies on progress arriving will wait for an event that never comes.
+	 *
+	 * @deprecated No producer. Removed in the next major.
+	 */
 	| { type: 'progress_updated'; taskId: TaskId; progress: AgentTaskProgress }
 	| { type: 'completed'; taskId: TaskId; result: BaseAgentResult }
 	| { type: 'failed'; taskId: TaskId; error: string }

package/src/types/agent/task.ts

@@ -106,6 +106,11 @@ export interface AgentTask {
 	context: AgentTaskContext
 	state: AgentTaskState
 	result?: BaseAgentResult
+	/**
+	 * **Never populated.** Nothing in the SDK writes task progress.
+	 *
+	 * @deprecated No producer. Removed in the next major.
+	 */
 	progress?: AgentTaskProgress
 
 	/**

package/src/types/hitl/index.ts

@@ -180,6 +180,16 @@ export interface IterationCheckpoint {
 	messages: Message[]
 	tokenUsage: TokenUsage
 	costInfo: CostInfo
+	/**
+	 * **Never set.** No checkpoint is written with a plan status.
+	 *
+	 * It matters more than an unused field usually would: a host restoring a
+	 * checkpoint and reading this to decide whether the plan was approved
+	 * gets `undefined` for every run, approved or not, and cannot tell the
+	 * two apart. Ask the plan manager instead.
+	 *
+	 * @deprecated No producer. Removed in the next major.
+	 */
 	planStatus?: PlanStatus
 
 	/**