@namzu/sdk 2.0.0 → 3.1.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({
@@ -56,6 +78,59 @@ const approvePlanStepSchema = z.object({
 	depends_on: z.array(z.string()).optional().describe('Step descriptions this depends on'),
 })
 
+/**
+ * The single closed shape a capable provider constrains this call to.
+ *
+ * `options` arriving as a STRING is the failure this exists for: a model that
+ * serializes the array once tends to keep doing it, and the parse error it
+ * gets back never says the array was the problem.
+ * `additionalProperties: false` turns that into a refusal at generation time
+ * rather than a rejection after the fact.
+ */
+const askUserQuestionModelInputSchema: Record<string, unknown> = {
+	type: 'object',
+	properties: {
+		question: {
+			type: 'string',
+			description: 'Full question text — clear, specific, and ending with a question mark.',
+		},
+		header: {
+			type: 'string',
+			description: 'Optional very short topic label, no more than 24 characters.',
+		},
+		options: {
+			type: 'array',
+			description: 'A JSON array of 2-4 genuinely distinct, context-derived option objects.',
+			items: {
+				type: 'object',
+				properties: {
+					label: {
+						type: 'string',
+						description:
+							'Concise option label. Put the recommended option first and append " (Recommended)".',
+					},
+					description: {
+						type: 'string',
+						description: 'Optional one-line explanation of what changes if selected.',
+					},
+				},
+				required: ['label'],
+				additionalProperties: false,
+			},
+		},
+		multiSelect: {
+			type: 'boolean',
+			description: 'True only when several options can apply at once.',
+		},
+		allowFreeText: {
+			type: 'boolean',
+			description: 'Whether the user may answer in their own words.',
+		},
+	},
+	required: ['question', 'options'],
+	additionalProperties: false,
+}
+
 function normalizeApprovePlanSteps(value: unknown): unknown {
 	if (typeof value !== 'string') return value
 
@@ -93,6 +168,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 +231,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 +306,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 +384,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) {
@@ -382,47 +490,55 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			name: 'ask_user_question',
 			description:
 				'Ask the user ONE question ONLY when you are blocked on a decision that is genuinely theirs to make — one you cannot resolve from their request, your tools, the files you can read, or sensible defaults. The question must be the genuinely undecidable thing in THIS task. Never ask for information a tool can discover (do not ask what you can read, list, or search), never re-ask what the conversation already answers, and never ask meta-questions like "Shall I proceed?" — plan ratification goes through approve_plan. Provide 2-4 genuinely distinct options derived from the actual context — concrete paths, never generic placeholders (for example, asked to prepare a presentation, ask "Who is the audience?" with options like Board / Engineering team / Customer); keep labels short (1-5 words) and give each option a one-line description of what practically changes if it is chosen. Put your recommended option FIRST and append " (Recommended)" to its label. Set multiSelect: true only when several options can apply at once. A free-text "Something else" escape hatch is always shown automatically — do not add your own "Other" option. Ask ONE question per call and prefer at most one question per assistant turn; if several decisions block you, ask only the ones that materially change your next actions, in sequence — most work needs at most 2-3 questions, so prefer proceeding on stated defaults over interrogating the user. Never invent answers or synthetic content on the user\'s behalf unless they explicitly asked for a random/test scenario. The answer arrives as this tool\'s result; if the result says the user did not answer, do not ask this or any other question again — proceed on your best judgment without assuming consent.',
-			inputSchema: z.object({
-				question: z
-					.string()
-					.min(1)
-					.describe('Full question text — clear, specific, ends with a question mark.'),
-				header: z
-					.string()
-					.max(24)
-					.optional()
-					.describe('Very short topic label for the question (e.g. "Audience", "Auth method").'),
-				options: z
-					.array(
-						z.object({
-							label: z
-								.string()
-								.min(1)
-								.max(80)
-								.describe(
-									'Concise option label (1-5 words). Recommended option goes first with " (Recommended)" appended.',
-								),
-							description: z
-								.string()
-								.max(300)
-								.optional()
-								.describe('One line on what practically changes if this option is chosen.'),
-						}),
-					)
-					.min(2)
-					.max(4)
-					.describe('2-4 genuinely distinct, context-derived options.'),
-				multiSelect: z
-					.boolean()
-					.optional()
-					.default(false)
-					.describe('True only when several options can apply at once.'),
-				allowFreeText: z
-					.boolean()
-					.optional()
-					.default(true)
-					.describe('Whether the user may answer in their own words.'),
-			}),
+			inputSchema: z
+				.object({
+					question: z
+						.string()
+						.min(1)
+						.describe('Full question text — clear, specific, ends with a question mark.'),
+					header: z
+						.string()
+						.max(24)
+						.optional()
+						.describe('Very short topic label for the question (e.g. "Audience", "Auth method").'),
+					options: z
+						.array(
+							z
+								.object({
+									label: z
+										.string()
+										.min(1)
+										.max(80)
+										.describe(
+											'Concise option label (1-5 words). Recommended option goes first with " (Recommended)" appended.',
+										),
+									description: z
+										.string()
+										.max(300)
+										.optional()
+										.describe('One line on what practically changes if this option is chosen.'),
+								})
+								.strict(),
+						)
+						.min(2)
+						.max(4)
+						.describe('2-4 genuinely distinct, context-derived options.'),
+					multiSelect: z
+						.boolean()
+						.optional()
+						.default(false)
+						.describe('True only when several options can apply at once.'),
+					allowFreeText: z
+						.boolean()
+						.optional()
+						.default(true)
+						.describe('Whether the user may answer in their own words.'),
+				})
+				.strict(),
+			modelInputSchema: structuredClone(askUserQuestionModelInputSchema),
+			enforceModelInput: true,
+			validationErrorHint:
+				'Required shape: {"question":"...?","options":[{"label":"First (Recommended)","description":"What changes"},{"label":"Second","description":"What changes"}]}. "options" must be a JSON array of 2-4 objects, never a string.',
 			category: 'custom',
 			permissions: [],
 			readOnly: true,
@@ -454,19 +570,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

@@ -20,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>
 }
 
@@ -36,6 +52,10 @@ export function defineTool<S extends z.ZodType>(
 		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