@namzu/sdk 1.4.0 → 3.0.0

package/src/tools/coordinator/index.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import type { PlanManager } from '../../manager/plan/lifecycle.js'
+import type { PendingAnswers, QuestionParkRecorder } from '../../runtime/query/question-park.js'
 import type { AgentRuntimeContext } from '../../types/agent/base.js'
 import type { TaskGateway } from '../../types/agent/gateway.js'
 import type { ResumeHandler, UserQuestionOption } from '../../types/hitl/index.js'
@@ -45,6 +46,27 @@ export interface CoordinatorToolsOptions {
 	 * runId the park request cannot be addressed.
 	 */
 	resumeHandler?: ResumeHandler
+
+	/**
+	 * Makes a question park durable and visible.
+	 *
+	 * Without it the park exists only as a suspended `await` inside one
+	 * process — nothing on disk says a human owes this run an answer, and a
+	 * remote host cannot observe the question at all. Optional because a
+	 * host driving the tools directly may have no checkpoint store.
+	 */
+	questionParks?: QuestionParkRecorder
+
+	/**
+	 * Answers carried in from a resumed run, keyed by `questionId`.
+	 *
+	 * Consulted BEFORE the park handler: a re-entered `ask_user_question`
+	 * must return the answer that was already given rather than asking
+	 * again. Without it, resuming re-parks a question the user answered —
+	 * and in a headless resume that either deadlocks or auto-answers with
+	 * the no-consent sentinel, discarding the real answer.
+	 */
+	pendingAnswers?: PendingAnswers
 }
 
 const approvePlanStepSchema = z.object({
@@ -93,6 +115,8 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		runId,
 		getPlanManager,
 		resumeHandler,
+		questionParks,
+		pendingAnswers,
 		// `onTaskLaunched` was the entry point for the old
 		// non-blocking + envelope-injection flow. create_task is now
 		// blocking, so the callback is no longer wired here.
@@ -154,16 +178,18 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				prompt,
 				workingDirectory: cwd,
 				runtimeContext: opts.runtimeContext,
+				// Hang the child run off THIS tool's span, so the delegation
+				// shows up inside the turn that asked for it.
+				...(_context.parentSpan ? { parentSpan: _context.parentSpan } : {}),
 			})
 
-			// Industrial-standard Anthropic tool pattern: tool returns
-			// its real result as the tool_result for the dispatching
-			// tool_use. Parallel fan-out happens at the executor layer
-			// — when the supervisor emits N create_task blocks in one
-			// assistant turn, the runtime runs them with Promise.all
-			// and delivers all N tool_results together. No async
-			// envelope injection, no second tool_result for the same
-			// tool_use_id (which Anthropic rejects with 400).
+			// The tool returns its real result as the `tool_result` for the
+			// dispatching `tool_use`. Parallel fan-out happens at the executor
+			// layer: when the supervisor emits N `create_task` blocks in one
+			// assistant turn, the runtime runs them together and delivers all
+			// N `tool_result`s at once. No async envelope injection, and no
+			// second `tool_result` for the same `tool_use_id` — providers
+			// reject a duplicated id outright.
 			const completed = await gateway.waitForTask(handle.taskId)
 			const success = completed.state === 'completed'
 			const resultText =
@@ -227,6 +253,28 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		},
 	})
 
+	const cancelTask = defineTool({
+		name: 'cancel_task',
+		description:
+			'Cancel a running agent task. Only use this with a task_id from a previous create_task.',
+		inputSchema: z.object({
+			task_id: z.string().describe('Agent task ID from a previous create_task'),
+		}),
+		category: 'custom',
+		permissions: [],
+		readOnly: false,
+		destructive: false,
+		concurrencySafe: true,
+		async execute({ task_id }) {
+			gateway.cancelTask(task_id as TaskId)
+			return {
+				success: true,
+				output: `Task ${task_id} cancelled`,
+				data: { task_id },
+			}
+		},
+	})
+
 	const agentTaskList = defineTool({
 		name: 'agent_task_list',
 		description:
@@ -283,17 +331,24 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		},
 	})
 
-	// `continue_task` and model-facing per-task cancellation both
-	// belonged to the old non-blocking worker protocol. With
-	// `create_task` now blocking + tool_result returning the worker's
-	// final output, every worker is terminal by the time a later model
-	// turn learns its task id. The old cancel tool additionally called
-	// a void/no-op gateway method and manufactured "cancelled" even for
-	// a missing id. Host-owned run interruption still uses the gateway
-	// cancellation contract directly; it does not need a model tool.
-	// Keep only the follow-up definition for a future non-default
-	// gateway that deliberately preserves live workers between turns.
+	// `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
+	// Per-task cancellation belonged to the old non-blocking worker protocol.
+	// `create_task` blocks and returns the worker output as its tool_result, so
+	// every worker is terminal by the time a later turn learns its id — the tool
+	// could only ever manufacture a "cancelled" for something already done.
+	// Host-owned interruption still uses the gateway contract directly.
+	void cancelTask
 	const tools: ToolDefinition[] = [createTask, agentTaskList]
 
 	if (getPlanManager) {
@@ -454,19 +509,44 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 					...(opt.description !== undefined ? { description: opt.description } : {}),
 				}))
 
-				const decision = await parkHandler({
-					type: 'user_question',
-					runId: parkRunId,
-					checkpointId: `cp_question_${toolUseId}`,
-					question: {
-						questionId: toolUseId,
-						question,
-						...(header !== undefined ? { header } : {}),
-						options: questionOptions,
-						multiSelect,
-						allowFreeText,
-					},
-				})
+				const questionData = {
+					questionId: toolUseId,
+					question,
+					...(header !== undefined ? { header } : {}),
+					options: questionOptions,
+					multiSelect,
+					allowFreeText,
+				}
+
+				// An answer carried in from a resumed run. Checked before the
+				// park, because re-entering this tool is HOW the answer gets
+				// delivered: the batch is re-executed, and without this the
+				// re-execution would ask the user something they already
+				// answered — or, headless, auto-answer with the no-consent
+				// sentinel and throw the real answer away.
+				const carried = pendingAnswers?.take(toolUseId)
+
+				// A real checkpoint, not a synthetic id nothing ever wrote.
+				// Skipped when an answer is already in hand: parking a
+				// question that is answered would leave an outstanding record
+				// for a decision that has been made.
+				const parkedAt =
+					carried === undefined && questionParks ? await questionParks.record(questionData) : null
+
+				const decision =
+					carried ??
+					(await parkHandler({
+						type: 'user_question',
+						runId: parkRunId,
+						checkpointId: parkedAt ?? `cp_question_${toolUseId}`,
+						question: questionData,
+					}))
+
+				// Clear the park once the answer is in, so an approval queue
+				// stops serving a question that has been answered.
+				if (parkedAt !== null && questionParks) {
+					await questionParks.resolve(parkedAt, decision)
+				}
 
 				// The no-answer sentinel (explicitly NOT consent — fixes the
 				// "empty answer reads as approval" ambiguity): used for empty

package/src/tools/defineTool.ts

@@ -11,6 +11,8 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	name: string
 	description: string
 	inputSchema: S
+	modelInputSchema?: Record<string, unknown>
+	enforceModelInput?: boolean
 	validationErrorHint?: string
 	category: ToolDefinition['category']
 	permissions: ToolPermission[]
@@ -18,6 +20,22 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	destructive: boolean | ((input: z.infer<S>) => boolean)
 	concurrencySafe: boolean
 	tier?: string
+	/** Per-execution deadline; see {@link ToolDefinition.timeoutMs}. */
+	timeoutMs?: number
+	/**
+	 * In-loop retry budget for a FAILED execution; see
+	 * {@link ToolDefinition.maxRetries}.
+	 *
+	 * The executor has always read this field, and this builder — the
+	 * sanctioned way to author a tool — had no way to set it, so the
+	 * documented "the tool author opts in, per tool" was reachable only by
+	 * hand-writing the interface.
+	 */
+	maxRetries?: number
+	/** Return shape shown to the model; see {@link ToolDefinition.outputSchema}. */
+	outputSchema?: Record<string, unknown>
+	/** Settle the run with this tool's output; see {@link ToolDefinition.terminal}. */
+	terminal?: boolean
 	execute(input: z.infer<S>, context: ToolContext): Promise<ToolResult>
 }
 
@@ -30,8 +48,14 @@ export function defineTool<S extends z.ZodType>(
 		name: options.name,
 		description: options.description,
 		inputSchema: options.inputSchema,
+		modelInputSchema: options.modelInputSchema,
+		enforceModelInput: options.enforceModelInput,
 		validationErrorHint: options.validationErrorHint,
 		tier: options.tier,
+		...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+		...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
+		...(options.outputSchema !== undefined ? { outputSchema: options.outputSchema } : {}),
+		...(options.terminal !== undefined ? { terminal: options.terminal } : {}),
 		category: options.category,
 		permissions: options.permissions,
 		isReadOnly: () => options.readOnly,

package/src/tools/glob-match.ts

@@ -0,0 +1,50 @@
+/**
+ * Glob matching for the sandboxed filesystem tools.
+ *
+ * The host path hands its pattern to the runtime's own directory walker;
+ * inside a sandbox there is only a flat listing to filter, so the matching
+ * has to happen here. Written out rather than reached for from the
+ * platform: the runtime's glob matcher is still flagged experimental, and
+ * an SDK that ships into other people's runtimes should not depend on
+ * that.
+ *
+ * The subset is the one the tools document — `**` across separators, `*`
+ * and `?` within one segment. Every other character is escaped, so a
+ * pattern containing regex punctuation matches literally instead of
+ * quietly becoming a different query.
+ */
+
+const NEEDS_ESCAPE = /[.+^${}()|[\]\\]/
+
+export function globToRegExp(pattern: string): RegExp {
+	let out = ''
+	for (let i = 0; i < pattern.length; i++) {
+		const ch = pattern[i] as string
+		if (ch === '*') {
+			if (pattern[i + 1] === '*') {
+				if (pattern[i + 2] === '/') {
+					// `**/` matches zero directories too, so `**/x.ts` finds a
+					// top-level `x.ts` — which is what someone writing it means.
+					out += '(?:.*/)?'
+					i += 2
+				} else {
+					out += '.*'
+					i += 1
+				}
+			} else {
+				out += '[^/]*'
+			}
+			continue
+		}
+		if (ch === '?') {
+			out += '[^/]'
+			continue
+		}
+		out += NEEDS_ESCAPE.test(ch) ? `\\${ch}` : ch
+	}
+	return new RegExp(`^${out}$`)
+}
+
+export function matchesGlob(path: string, pattern: string): boolean {
+	return globToRegExp(pattern).test(path)
+}

package/src/tools/paths.ts

@@ -0,0 +1,44 @@
+import { isAbsolute, relative, resolve } from 'node:path'
+
+/**
+ * Resolve a caller-supplied path against a root, refusing anything that
+ * lands outside it.
+ *
+ * The containment rule existed, in one private function inside the local
+ * sandbox provider, and the filesystem tools never reached it. They called
+ * `resolve(workingDirectory, input.path)` bare — so `path: "../../.."`
+ * resolved to whatever is above the working directory and the tool read it
+ * happily. That holds with no sandbox configured at all, which is the
+ * common case, so the escape did not need a misconfiguration to reach: a
+ * model that asks for a parent directory gets one.
+ *
+ * `relative()` rather than a `startsWith` prefix test: a prefix test says
+ * `/workspace-backup` is inside `/workspace`, and the whole point is to be
+ * exact about the boundary.
+ */
+export function resolveWithin(root: string, candidate: string | undefined): string {
+	if (candidate === undefined || candidate === '') return resolve(root)
+
+	const resolvedRoot = resolve(root)
+	const resolved = resolve(resolvedRoot, candidate)
+	const rel = relative(resolvedRoot, resolved)
+
+	// An absolute `rel` means the two paths share no root at all (a
+	// different drive on Windows); a leading `..` means it climbed out.
+	if (rel.startsWith('..') || isAbsolute(rel)) {
+		throw new Error(
+			`Path escapes the working directory: ${candidate}. Tools may only reach inside ${resolvedRoot}.`,
+		)
+	}
+	return resolved
+}
+
+/** True when `candidate` resolves inside `root`. */
+export function isWithin(root: string, candidate: string): boolean {
+	try {
+		resolveWithin(root, candidate)
+		return true
+	} catch {
+		return false
+	}
+}

package/src/tools/posix-path.ts

@@ -0,0 +1,73 @@
+/**
+ * Path arithmetic in the SANDBOX's coordinate system.
+ *
+ * A sandbox is a POSIX filesystem whatever the host runs, so resolving its
+ * paths with the host's path module rewrites them whenever the two
+ * disagree: on a Windows host, `resolve('/workspace')` becomes
+ * `C:\workspace` and a container path stops being a container path. The
+ * tool then hands the model a string its own sandbox cannot open — which
+ * is the same class of failure as reporting host-relative paths from a
+ * sandboxed search, just one layer lower.
+ *
+ * These are deliberately small: join, relativise, and refuse an escape.
+ * Nothing here touches the host filesystem.
+ */
+
+function normalizeSegments(path: string): string[] {
+	const out: string[] = []
+	for (const segment of path.split('/')) {
+		if (segment === '' || segment === '.') continue
+		if (segment === '..') {
+			// Popping past the root is how a climb-out starts; the caller
+			// decides what to do about it via `resolveWithinPosix`.
+			if (out.length > 0 && out[out.length - 1] !== '..') out.pop()
+			else out.push('..')
+			continue
+		}
+		out.push(segment)
+	}
+	return out
+}
+
+/** Join, normalising `.` and `..`. Absolute in, absolute out. */
+export function joinPosix(base: string, ...parts: string[]): string {
+	const absolute = base.startsWith('/')
+	const segments = normalizeSegments([base, ...parts].join('/'))
+	return (absolute ? '/' : '') + segments.join('/')
+}
+
+/** `to` expressed relative to `from`, or `to` itself when unrelated. */
+export function relativePosix(from: string, to: string): string {
+	const fromSegments = normalizeSegments(from)
+	const toSegments = normalizeSegments(to)
+
+	let shared = 0
+	while (
+		shared < fromSegments.length &&
+		shared < toSegments.length &&
+		fromSegments[shared] === toSegments[shared]
+	) {
+		shared++
+	}
+
+	const up = fromSegments.slice(shared).map(() => '..')
+	return [...up, ...toSegments.slice(shared)].join('/')
+}
+
+/**
+ * Resolve `candidate` against `root`, refusing anything that lands
+ * outside. The sandbox-side twin of the host containment check.
+ */
+export function resolveWithinPosix(root: string, candidate: string | undefined): string {
+	if (candidate === undefined || candidate === '') return joinPosix(root)
+
+	// An absolute candidate is taken as sandbox-absolute, not appended.
+	const resolved = candidate.startsWith('/') ? joinPosix(candidate) : joinPosix(root, candidate)
+	const rel = relativePosix(root, resolved)
+	if (rel.startsWith('..')) {
+		throw new Error(
+			`Path escapes the working directory: ${candidate}. Tools may only reach inside ${root}.`,
+		)
+	}
+	return resolved
+}

package/src/types/advisory/config.ts

@@ -1,3 +1,4 @@
+import type { ModelPricing } from '../../utils/cost.js'
 import type { AgentPersona } from '../persona/index.js'
 import type { LLMProvider } from '../provider/index.js'
 import type { AdvisoryTrigger } from './trigger.js'
@@ -14,14 +15,31 @@ export interface AdvisorDefinition {
 	readonly useCompactedContext?: boolean
 	readonly maxResponseTokens?: number
 	readonly temperature?: number
+	/**
+	 * What this advisor's model costs. Absent means cost is not measured,
+	 * which is fine until a cost cap is set — see {@link AdvisoryBudget}.
+	 */
+	readonly pricing?: ModelPricing
 }
 
+/**
+ * Bounds on what a run may spend on advice.
+ *
+ * Every cap here is enforced. Per-SESSION caps used to be declared beside
+ * these and were not: the advisory stack is built once per run, so there was
+ * no accumulator that outlived one, and the field could only ever read as a
+ * promise. A host that wants a session bound holds it where sessions live.
+ */
 export interface AdvisoryBudget {
+	/** Advisory calls allowed in one run. Checked before each call. */
 	readonly maxCallsPerRun?: number
-	readonly maxCallsPerSession?: number
-	readonly maxCostPerCall?: number
+	/**
+	 * Total advisory spend allowed in one run, in the same units as
+	 * {@link ModelPricing}. Requires every advisor to carry `pricing`;
+	 * a run configured otherwise is refused rather than left uncapped.
+	 */
 	readonly maxCostPerRun?: number
-	readonly maxCostPerSession?: number
+	/** Response-token ceiling applied to each call, clamping the advisor's own. */
 	readonly maxTokensPerCall?: number
 }
 

package/src/types/advisory/result.ts

@@ -8,17 +8,22 @@ export interface AdvisoryRequest {
 	readonly includeContext?: boolean
 }
 
+/**
+ * What an advisor answered.
+ *
+ * Three more fields — a plan, a model suggestion, per-category tool guidance —
+ * were declared here with neither a producer nor a reader, so they described
+ * a shape the runtime never built and nothing ever branched on. The two that
+ * remain are produced by the parser and consumed: decisions land in working
+ * state and survive compaction, warnings are rendered back to the executing
+ * agent.
+ */
 export interface AdvisoryResult {
 	readonly advice: string
-	readonly plan?: Array<{ step: string; status?: string }>
+	/** Carried into working state, so they outlive the context they were given in. */
 	readonly decisions?: string[]
+	/** Rendered back to the executing agent under their own heading. */
 	readonly warnings?: string[]
-	readonly modelSuggestion?: string
-	readonly toolGuidance?: Array<{
-		readonly category: string
-		readonly recommendation: 'prefer' | 'avoid' | 'required'
-		readonly reason?: string
-	}>
 }
 
 export interface AdvisoryCallRecord {

package/src/types/agent/base.ts

@@ -23,6 +23,23 @@ export interface BaseAgentConfig {
 	permissionMode?: PermissionMode
 	env?: Record<string, string>
 
+	/**
+	 * Deduplicate a retried invocation instead of running it twice.
+	 *
+	 * The failure this exists for: a caller sends a request, the
+	 * connection drops, the caller retries. Without a key the retry is a
+	 * second full run — a second set of model calls, and a second set of
+	 * whatever the tools did. A duplicate arriving while the first is
+	 * still running awaits it and receives its result, error included.
+	 *
+	 * In-flight only. A retry that arrives after the first has settled
+	 * runs again, because keeping the answer would turn deduplication
+	 * into caching and staleness is the host's judgement, not the SDK's.
+	 * Instance-scoped, like the invocation lock: deduplicating across
+	 * processes needs somewhere durable to record the key.
+	 */
+	idempotencyKey?: string
+
 	/**
 	 * Long-lived goal scope for the run. Required at runtime — agents reject
 	 * configs missing this (`'X requires sessionId, projectId, and tenantId
@@ -58,6 +75,9 @@ export interface BaseAgentConfig {
 
 	/** Shared invocation state passed through agent hierarchies */
 	invocationState?: InvocationState
+
+	/** Span a delegated run hangs off. Absent for a top-level run. */
+	parentSpan?: import('@opentelemetry/api').Span
 }
 
 export type RuntimeToolOverrides = Record<string, ToolAvailability | 'disabled'>
@@ -68,8 +88,8 @@ export interface AgentRuntimeContext {
 	/**
 	 * Optional working/scratch directory the runtime exposes to the
 	 * agent — sibling to `outputDirectory`, invisible to the
-	 * output collector. Mirrors the Anthropic Cowork pattern
-	 * where `/home/claude` is scratch and `/mnt/user-data/outputs` is
+	 * output collector. Follows the same separation as the container layout
+	 * where the scratch bind is invisible and `/mnt/user-data/outputs` is
 	 * user-visible.
 	 */
 	scratchDirectory?: string

package/src/types/agent/factory.ts

@@ -15,8 +15,8 @@ export interface AgentDefinition {
 
 export interface AgentFactoryOptions {
 	/**
-	 * API key for providers that authenticate via key (OpenAI, Anthropic,
-	 * OpenRouter). Optional because BYO-provider flows (Bedrock IAM, custom
+	 * API key for providers that authenticate via a key. Optional because
+	 * BYO-provider flows (ambient cloud credentials, a custom
 	 * `ProviderRegistry.create(...)`) resolve credentials outside this object.
 	 * `configBuilder` implementations should treat an absent `apiKey` as the
 	 * BYO signal and use the provider passed via the agent config instead.
@@ -33,14 +33,20 @@ export interface AgentFactoryOptions {
 
 	systemPrompt?: string
 
-	provider?: 'openrouter' | 'bedrock'
+	/**
+	 * Which registered provider to build. Any type registered with
+	 * `ProviderRegistry` is valid — this was a closed two-member union
+	 * naming two specific services, which the registry has never been
+	 * limited to and which no caller could extend.
+	 */
+	provider?: string
 
-	bedrockConfig?: {
-		region?: string
-		accessKeyId?: string
-		secretAccessKey?: string
-		sessionToken?: string
-	}
+	/**
+	 * Extra construction config for the chosen provider, passed through
+	 * untouched. Replaces a field that existed for exactly one service and
+	 * had no construction site anywhere.
+	 */
+	providerConfig?: Record<string, unknown>
 
 	agentDefinitions?: AgentDefinition[]
 

package/src/types/agent/gateway.ts

@@ -11,7 +11,27 @@ export interface TaskHandle {
 	readonly completedAt?: number
 }
 
+/**
+ * What a failed child means for the siblings still running.
+ *
+ * `'continue'` — the default, and deliberately so. Partial results are
+ * usually worth having, and tearing down healthy siblings on any failure
+ * would let one flaky child waste four good ones.
+ *
+ * `'cancel-siblings'` — stop the rest. For a fan-out whose parts only mean
+ * something together: if one leg of a comparison dies, the others are
+ * spending budget on an answer nobody can use.
+ */
+export type SiblingFailurePolicy = 'continue' | 'cancel-siblings'
+
 export interface CreateTaskOptions {
+	/**
+	 * Span the spawned run should hang off — normally the executing tool's
+	 * own span, so the delegation shows up inside the turn that asked for
+	 * it rather than as a disconnected root trace.
+	 */
+	readonly parentSpan?: import('@opentelemetry/api').Span
+
 	agentId: string
 
 	prompt: string

package/src/types/agent/manager.ts

@@ -18,8 +18,27 @@ export interface AgentManagerContract {
 	cancel(taskId: TaskId): void
 	cancelAll(parentRunId: RunId): void
 
+	/**
+	 * Queue a message for a running task.
+	 *
+	 * **The runtime does not deliver it.** These three methods maintain a
+	 * per-task queue that nothing in the iteration loop reads: the consumer
+	 * that once drained it was removed, and the mid-run delivery handshake
+	 * that would replace it is a host concern, not a kernel one. A caller
+	 * who assumes `continueTask` reaches the agent is queuing into a buffer
+	 * only {@link drainMessages} empties.
+	 *
+	 * Kept, and documented rather than deleted, because `drainMessages` is
+	 * the only way a host can pick these up at all — removing it would take
+	 * away the escape hatch and leave the trap. Two delivery routes that DO
+	 * work today: reject/modify feedback rides inside a tool result, and
+	 * `prepareStep`'s `system` string is appended to the next model call
+	 * from a hook that sees live history.
+	 */
 	continueTask(taskId: TaskId, message: string): Promise<void>
+	/** See {@link continueTask} — queued, not delivered. */
 	queueMessage(taskId: TaskId, message: Message): void
+	/** Empty the queue {@link continueTask} fills. The host must call this. */
 	drainMessages(taskId: TaskId): Message[]
 
 	waitForCompletion(taskId: TaskId): Promise<void>