@namzu/sdk 1.0.0 → 1.1.0

package/src/tools/coordinator/index.ts

@@ -2,6 +2,7 @@ import { z } from 'zod'
 import type { PlanManager } from '../../manager/plan/lifecycle.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'
 import type { RunId, TaskId } from '../../types/ids/index.js'
 import type { TaskStore } from '../../types/task/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
@@ -36,6 +37,52 @@ export interface CoordinatorToolsOptions {
 	getPlanManager?: () => PlanManager | undefined
 
 	onTaskLaunched?: TaskLaunchedCallback
+
+	/**
+	 * HITL park channel for `ask_user_question`. The tool is registered
+	 * only when BOTH `resumeHandler` and `runId` are present — without a
+	 * handler there is no one to route the question to, and without a
+	 * runId the park request cannot be addressed.
+	 */
+	resumeHandler?: ResumeHandler
+}
+
+const approvePlanStepSchema = z.object({
+	description: z.string().describe('What this step does'),
+	agent_id: z
+		.string()
+		.optional()
+		.describe('Which agent handles this (omit for orchestrator-owned steps)'),
+	depends_on: z.array(z.string()).optional().describe('Step descriptions this depends on'),
+})
+
+function normalizeApprovePlanSteps(value: unknown): unknown {
+	if (typeof value !== 'string') return value
+
+	const trimmed = value.trim()
+	if (!trimmed) return []
+
+	if (trimmed.startsWith('[')) {
+		try {
+			return JSON.parse(trimmed)
+		} catch {
+			// Fall through to plain-text line parsing.
+		}
+	}
+
+	const lines = trimmed
+		.split(/\r?\n+/)
+		.map((line) =>
+			line
+				.trim()
+				.replace(/^(?:[-*•]|\d+[.)])\s*/, '')
+				.trim(),
+		)
+		.filter(Boolean)
+
+	return (lines.length ? lines : [trimmed]).map((description) => ({
+		description,
+	}))
 }
 
 export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefinition[] {
@@ -45,6 +92,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		taskStore,
 		runId,
 		getPlanManager,
+		resumeHandler,
 		// `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.
@@ -282,26 +330,18 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 					.describe('Short title for the plan (e.g. "TypeScript Security & Performance Review")'),
 				summary: z.string().describe('1-3 sentence summary of what you plan to do'),
 				steps: z
-					.array(
-						z.object({
-							description: z.string().describe('What this step does'),
-							agent_id: z
-								.string()
-								.optional()
-								.describe('Which agent handles this (omit for orchestrator-owned steps)'),
-							depends_on: z
-								.array(z.string())
-								.optional()
-								.describe('Step descriptions this depends on'),
-						}),
-					)
+					.preprocess(normalizeApprovePlanSteps, z.array(approvePlanStepSchema))
 					.describe('Ordered list of planned steps'),
 			}),
 			category: 'custom',
 			permissions: [],
 			readOnly: true,
 			destructive: false,
-			concurrencySafe: true,
+			// Parks through the SAME runId-keyed host resume registry as
+			// ask_user_question — concurrent parks in one batch clobber the
+			// registry entry and deadlock the loser, so the executor must
+			// serialize this tool exactly like the question tool.
+			concurrencySafe: false,
 			async execute({ title, summary, steps }) {
 				const pm = getPlanManager()
 				if (!pm) {
@@ -330,17 +370,27 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 
 				if (response.approved) {
 					pm.startExecution()
+					// Approve-with-edits: when the user attached feedback to an
+					// approval, embed it in the model-visible output so the
+					// supervisor applies the edits during execution. A bare
+					// approve keeps the historical output byte-identical.
+					const output = response.feedback
+						? `Plan approved by user with required edits — apply them during execution:\n${response.feedback}\nProceed with execution — launch workers via create_task.`
+						: 'Plan approved by user. Proceed with execution — launch workers via create_task.'
 					return {
 						success: true,
-						output:
-							'Plan approved by user. Proceed with execution — launch workers via create_task.',
+						output,
 						data: { approved: true, feedback: response.feedback },
 					}
 				}
 
+				// Rejection guidance follows the FEEDBACK, not a baked-in
+				// revise loop: the old unconditional "revise … and call
+				// approve_plan again" contradicted stop-style feedback, so a
+				// user rejecting a plan got another plan instead of a halt.
 				return {
 					success: false,
-					output: `Plan rejected. User feedback: ${response.feedback ?? 'No feedback provided'}. Revise your plan based on this feedback and call approve_plan again, or ask the user for clarification.`,
+					output: `Plan rejected. User feedback: ${response.feedback ?? 'No feedback provided'}. Follow this feedback: if it requests changes, revise your plan and call approve_plan again; if it asks you to stop, acknowledge briefly and end your turn. If no feedback was provided, ask the user how to proceed before planning again.`,
 					data: { approved: false, feedback: response.feedback },
 				}
 			},
@@ -348,5 +398,165 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		tools.push(approvePlan)
 	}
 
+	if (resumeHandler && runId) {
+		const parkRunId = runId
+		const parkHandler = resumeHandler
+		const askUserQuestion = defineTool({
+			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.'),
+			}),
+			category: 'custom',
+			permissions: [],
+			readOnly: true,
+			destructive: false,
+			// MUST stay false: the executor serializes non-concurrency-safe
+			// tools in a single chain, so N question blocks in one assistant
+			// turn park strictly one-at-a-time. Hosts key their park/resolve
+			// registries by runId — concurrent parks on one run clobber each
+			// other and the first promise never resolves (run hangs to TTL).
+			concurrencySafe: false,
+			async execute({ question, header, options, multiSelect, allowFreeText }, context) {
+				const toolUseId = context.toolUseId
+				if (!toolUseId) {
+					// Without the executing tool_use_id the question has no
+					// stable identity: the host could never merge the awaiting
+					// card with its resolution, and answers could not be matched
+					// back. Hard-fail instead of parking an unmergeable id.
+					return {
+						success: false,
+						output: '',
+						error:
+							'ask_user_question requires an executor that threads ToolContext.toolUseId; the question cannot be tracked without it.',
+					}
+				}
+
+				const questionOptions: UserQuestionOption[] = options.map((opt, i) => ({
+					id: `opt_${i + 1}`,
+					label: opt.label,
+					...(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,
+					},
+				})
+
+				// The no-answer sentinel (explicitly NOT consent — fixes the
+				// "empty answer reads as approval" ambiguity): used for empty
+				// answers, misdirected legacy decisions (e.g. a stale replica
+				// resolving with approve/continue verbs), and answers that
+				// carry a different question's id.
+				const noAnswer = {
+					success: true,
+					output:
+						'The user did not answer this question. Do not assume a choice or consent; proceed on your best judgment or continue without this information.',
+					data: { question, answered: false },
+				}
+
+				if (decision.action === 'abort') {
+					return {
+						success: false,
+						output:
+							'The user declined to answer and asked to stop. Acknowledge briefly and end your turn.',
+						data: { question, answered: false, declined: true },
+					}
+				}
+
+				if (decision.action !== 'answer_question') return noAnswer
+				if (decision.questionId !== undefined && decision.questionId !== toolUseId) {
+					// Misdirection guard: this answer was meant for a different
+					// question parked under the same run (stale client). Never
+					// fabricate a selection against the wrong question.
+					return noAnswer
+				}
+
+				const stripRecommended = (label: string) =>
+					label.replace(/\s*\(recommended\)\s*$/i, '').trim()
+
+				const selected = decision.selectedOptionIds
+					.map((id) => questionOptions.find((opt) => opt.id === id))
+					.filter((opt): opt is UserQuestionOption => opt !== undefined)
+					.map((opt) => ({ id: opt.id, label: stripRecommended(opt.label) }))
+
+				const freeText = decision.freeText?.trim() ?? ''
+
+				if (selected.length === 0 && !freeText) return noAnswer
+
+				let output: string
+				if (selected.length > 0) {
+					const joined = selected.map((s) => `"${s.label}"`).join(', ')
+					output = `User answered "${question}": ${joined}`
+					if (freeText) {
+						output += `\nAdditional note from the user: "${freeText}"`
+					}
+				} else {
+					output = `User answered "${question}" in their own words: "${freeText}"`
+				}
+
+				return {
+					success: true,
+					output,
+					data: {
+						question,
+						selected,
+						...(freeText ? { freeText } : {}),
+						answered: true,
+					},
+				}
+			},
+		})
+		tools.push(askUserQuestion)
+	}
+
 	return tools
 }

package/src/types/agent/index.ts

@@ -9,3 +9,4 @@ export * from './gateway.js'
 export * from './task.js'
 export * from './lifecycle-event.js'
 export * from './manager.js'
+export * from './working-memory.js'

package/src/types/agent/reactive.ts

@@ -1,3 +1,4 @@
+import type { CompactionConfig } from '../../config/runtime.js'
 import type { AdvisoryConfig } from '../advisory/index.js'
 import type { AgentPersona } from '../persona/index.js'
 import type { LLMProvider } from '../provider/index.js'
@@ -6,6 +7,7 @@ import type { Skill } from '../skills/index.js'
 import type { ToolRegistryContract } from '../tool/index.js'
 import type { VerificationGateConfig } from '../verification/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from './base.js'
+import type { WorkingMemoryProvider } from './working-memory.js'
 
 export interface ReactiveAgentConfig extends BaseAgentConfig {
 	systemPrompt?: string
@@ -42,6 +44,21 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 	 * on top of the provider keeps the underlying container alive.
 	 */
 	sandboxProvider?: SandboxProvider
+
+	/**
+	 * Optional structured-compaction config. Omitted ⇒ byte-identical run path
+	 * (no `WorkingStateManager`, compaction early-returns). Mirrors the field
+	 * on `SupervisorAgentConfig` so a child specialist can share the
+	 * supervisor's compaction settings.
+	 */
+	compactionConfig?: CompactionConfig
+
+	/**
+	 * Optional neutral working-memory seam — same contract as the field on
+	 * `SupervisorAgentConfig`. Absent ⇒ no block injected. A child specialist
+	 * sharing the supervisor's output dir passes the same provider.
+	 */
+	workingMemoryProvider?: WorkingMemoryProvider
 }
 
 export interface ReactiveAgentResult extends BaseAgentResult {

package/src/types/agent/supervisor.ts

@@ -1,3 +1,4 @@
+import type { CompactionConfig } from '../../config/runtime.js'
 import type { AdvisoryConfig } from '../advisory/index.js'
 import type { ResumeHandler } from '../hitl/index.js'
 import type { LLMProvider } from '../provider/index.js'
@@ -10,6 +11,7 @@ import type { BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { AgentFactoryOptions } from './factory.js'
 import type { TaskGateway } from './gateway.js'
 import type { AgentManagerContract } from './manager.js'
+import type { WorkingMemoryProvider } from './working-memory.js'
 
 export interface SupervisorAgentConfig extends BaseAgentConfig {
 	provider: LLMProvider
@@ -68,6 +70,24 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 * + children share one ephemeral container per task.
 	 */
 	sandboxProvider?: SandboxProvider
+
+	/**
+	 * Optional structured-compaction config. When omitted, `query()` never
+	 * builds a `WorkingStateManager` and compaction early-returns — the run
+	 * path is byte-identical to a non-compacting run. Hosts opt in (e.g. with
+	 * a `contextWindowTokens`) to keep a long single run alive instead of
+	 * silently truncating.
+	 */
+	compactionConfig?: CompactionConfig
+
+	/**
+	 * Optional neutral working-memory seam. When set, the SDK re-renders the
+	 * provider's string into a single pinned leading system message every
+	 * iteration (the primacy-edge, compaction-preserved slot). Absent ⇒ no
+	 * block is ever injected. The SDK only positions the string; the host owns
+	 * its content and trust framing.
+	 */
+	workingMemoryProvider?: WorkingMemoryProvider
 }
 
 export interface AgentTaskResult {

package/src/types/agent/working-memory.ts

@@ -0,0 +1,29 @@
+/**
+ * Per-turn context the SDK is allowed to hand a working-memory provider.
+ *
+ * NEUTRAL by construction: opaque strings + a number, NO host/Postgres/disk
+ * types. It mirrors `AgentRuntimeContext.notes: readonly string[]` and the
+ * `web-search` seam discipline — the host closes over everything else
+ * (threadId, output dir, tenancy) when it builds the provider, so the SDK
+ * never learns a domain type. The SDK only POSITIONS the returned string at
+ * the primacy edge; the host OWNS the content and its authority framing.
+ */
+export interface WorkingMemoryTurnContext {
+	/** The active run id (opaque). */
+	readonly runId: string
+	/** 1-based iteration counter for this run. */
+	readonly iteration: number
+}
+
+/**
+ * Returns a rendered, already-sanitized working-memory block to pin at the
+ * primacy edge (a single leading system message, refreshed every iteration).
+ *
+ * The SDK does no parsing of the returned string — it stores it verbatim under
+ * a sentinel header and re-pins it each turn. An empty/blank return ⇒ no block
+ * is injected (the byte-identical-when-empty property). Async so the host can
+ * `stat` the output dir / read the registry each turn. Failure-isolated by the
+ * SDK: a throwing/slow provider degrades to "no refresh this turn", never
+ * breaks the run.
+ */
+export type WorkingMemoryProvider = (ctx: WorkingMemoryTurnContext) => string | Promise<string>

package/src/types/common/index.ts

@@ -22,6 +22,25 @@ export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage):
 	}
 }
 
+/**
+ * Merge two usage snapshots seen WITHIN a single streamed turn. Provider usage
+ * frames over one stream are cumulative/monotonic (input set once early, output
+ * grows), but a late frame can OMIT a field (report 0) — e.g. Anthropic's
+ * `message_delta` may carry only output tokens. A naive last-write-wins
+ * (`usage = chunk.usage`) then drops the earlier prompt/cache counts and
+ * under-reports the turn. Taking the per-field high-water mark preserves every
+ * field. DISTINCT from {@link accumulateTokenUsage}, which SUMS across turns.
+ */
+export function mergeTokenUsage(current: TokenUsage, next: TokenUsage): TokenUsage {
+	return {
+		promptTokens: Math.max(current.promptTokens, next.promptTokens),
+		completionTokens: Math.max(current.completionTokens, next.completionTokens),
+		totalTokens: Math.max(current.totalTokens, next.totalTokens),
+		cachedTokens: Math.max(current.cachedTokens, next.cachedTokens),
+		cacheWriteTokens: Math.max(current.cacheWriteTokens, next.cacheWriteTokens),
+	}
+}
+
 export interface CostInfo {
 	inputCostPer1M: number
 	outputCostPer1M: number

package/src/types/common/usage-merge.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+
+import { type TokenUsage, accumulateTokenUsage, mergeTokenUsage } from './index.js'
+
+const zero: TokenUsage = {
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
+/**
+ * M7: within one streamed turn, usage frames are cumulative/monotonic but a
+ * late frame may omit fields. `mergeTokenUsage` keeps the per-field high-water
+ * mark so a trailing output-only frame does not zero the earlier prompt/cache
+ * counts (the under-report the audit flagged).
+ */
+describe('mergeTokenUsage (within-turn, per-field max)', () => {
+	it('preserves prompt/cache tokens when a later frame reports only output', () => {
+		// message_start-like frame: input + cache set, output still 0.
+		const early: TokenUsage = {
+			...zero,
+			promptTokens: 1200,
+			cachedTokens: 800,
+			cacheWriteTokens: 200,
+		}
+		// message_delta-like frame: only output tokens, input/cache dropped to 0.
+		const lateOutputOnly: TokenUsage = { ...zero, completionTokens: 350 }
+
+		const merged = mergeTokenUsage(early, lateOutputOnly)
+		expect(merged.promptTokens).toBe(1200) // NOT zeroed by the late frame
+		expect(merged.cachedTokens).toBe(800)
+		expect(merged.cacheWriteTokens).toBe(200)
+		expect(merged.completionTokens).toBe(350)
+	})
+
+	it('takes the growing (max) completion count across frames', () => {
+		const a: TokenUsage = { ...zero, promptTokens: 100, completionTokens: 10 }
+		const b: TokenUsage = { ...zero, promptTokens: 100, completionTokens: 42 }
+		expect(mergeTokenUsage(a, b).completionTokens).toBe(42)
+		// Order-independent (a late smaller frame never regresses the max).
+		expect(mergeTokenUsage(b, a).completionTokens).toBe(42)
+	})
+
+	it('is distinct from accumulateTokenUsage (which sums across turns)', () => {
+		const t1: TokenUsage = { ...zero, promptTokens: 100, completionTokens: 20 }
+		const t2: TokenUsage = { ...zero, promptTokens: 100, completionTokens: 30 }
+		// merge = max within a turn; accumulate = sum across turns.
+		expect(mergeTokenUsage(t1, t2).promptTokens).toBe(100)
+		expect(accumulateTokenUsage(t1, t2).promptTokens).toBe(200)
+	})
+})

package/src/types/connector/mcp.ts

@@ -6,7 +6,9 @@ import type {
 	ConnectorInstance,
 } from './definition.js'
 
-export type MCPTransportType = 'stdio' | 'http-sse'
+export type MCPStreamableHttpTransportType = 'streamable_http' | 'streamable-http'
+
+export type MCPTransportType = 'stdio' | 'http-sse' | MCPStreamableHttpTransportType
 
 export interface MCPTransportConfigBase {
 	type: MCPTransportType
@@ -27,7 +29,17 @@ export interface MCPHttpSseTransportConfig extends MCPTransportConfigBase {
 	timeoutMs?: number
 }
 
-export type MCPTransportUnion = MCPStdioTransportConfig | MCPHttpSseTransportConfig
+export interface MCPStreamableHttpTransportConfig extends MCPTransportConfigBase {
+	type: MCPStreamableHttpTransportType
+	url: string
+	headers?: Record<string, string>
+	timeoutMs?: number
+}
+
+export type MCPTransportUnion =
+	| MCPStdioTransportConfig
+	| MCPHttpSseTransportConfig
+	| MCPStreamableHttpTransportConfig
 
 export interface MCPJsonRpcError {
 	code: number

package/src/types/hitl/index.ts

@@ -7,11 +7,27 @@ export type { CheckpointId }
 
 export type HITLResumeDecision =
 	| { action: 'continue' }
-	| { action: 'approve_plan' }
+	| { action: 'approve_plan'; feedback?: string }
 	| { action: 'reject_plan'; feedback: string }
 	| { action: 'approve_tools' }
 	| { action: 'modify_tools'; modifications: ToolModification[] }
 	| { action: 'reject_tools'; feedback: string }
+	| {
+			action: 'answer_question'
+			selectedOptionIds: string[]
+			freeText?: string
+			/**
+			 * Echo of `UserQuestionData.questionId` — the misdirection
+			 * guard. The park/resolve registry on hosts is typically
+			 * keyed by run, so a stale client can answer question N
+			 * after question N+1 re-parked under the same run. When
+			 * present and it does not match the asking tool's own
+			 * questionId, the tool treats the decision as unanswered
+			 * instead of fabricating a selection against the wrong
+			 * question.
+			 */
+			questionId?: string
+	  }
 	| { action: 'pause'; reason: string }
 	| { action: 'abort'; reason: string }
 
@@ -24,6 +40,7 @@ export type HITLDecisionRequest =
 			checkpointId: CheckpointId
 			summary: CheckpointSummary
 	  }
+	| { type: 'user_question'; runId: RunId; checkpointId: CheckpointId; question: UserQuestionData }
 
 export type ResumeHandler = (request: HITLDecisionRequest) => Promise<HITLResumeDecision>
 
@@ -40,6 +57,29 @@ export interface ToolModification {
 	modifiedInput?: unknown
 }
 
+export interface UserQuestionOption {
+	id: string
+	label: string
+	description?: string
+}
+
+/**
+ * A model-authored question for the user, parked through the
+ * `ResumeHandler` exactly like a plan approval. `questionId` equals
+ * the asking `tool_use_id` so the host can mint stable, mergeable
+ * activity ids per question and so answers can be matched back to
+ * the question that asked them (see
+ * `HITLResumeDecision['answer_question'].questionId`).
+ */
+export interface UserQuestionData {
+	questionId: string
+	question: string
+	header?: string
+	options: UserQuestionOption[]
+	multiSelect: boolean
+	allowFreeText: boolean
+}
+
 export interface PlanApprovalData {
 	planId: PlanId
 	title: string
@@ -108,6 +148,17 @@ export function autoApproveHandler(request: HITLDecisionRequest): Promise<HITLRe
 			return Promise.resolve({ action: 'approve_tools' })
 		case 'iteration_checkpoint':
 			return Promise.resolve({ action: 'continue' })
+		case 'user_question':
+			// Headless runs must never deadlock on a question and must
+			// never fabricate a user choice: answer with an explicit
+			// no-selection sentinel so the asking tool renders "the user
+			// did not answer" rather than consent.
+			return Promise.resolve({
+				action: 'answer_question',
+				selectedOptionIds: [],
+				freeText: 'No user is available to answer. Proceed using your best judgment.',
+				questionId: request.question.questionId,
+			})
 		default: {
 			const _exhaustive: never = request
 			throw new Error(`Unhandled HITL request type: ${(_exhaustive as HITLDecisionRequest).type}`)

package/src/types/provider/chat.ts

@@ -28,6 +28,16 @@ export interface ChatCompletionParams {
 	stream?: boolean
 	stop?: string[]
 
+	/**
+	 * Per-call cancellation. Aborting it tears down the in-flight model
+	 * request (the provider passes it to the underlying fetch / SDK) AND the
+	 * runtime races the stream consumer against it, so a Stop stops the
+	 * CURRENT turn mid-flight — not only between turns. Optional and inert
+	 * when unset: a non-aborted signal is behaviourally identical to omitting
+	 * it, so existing callers are unaffected.
+	 */
+	signal?: AbortSignal
+
 	toolChoice?: ToolChoice
 	parallelToolCalls?: boolean
 

package/src/version.ts

@@ -1,6 +1,28 @@
-import { createRequire } from 'node:module'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
-const require = createRequire(import.meta.url)
-const pkg = require('../package.json') as { version: string }
+/**
+ * The SDK's package version, read from package.json relative to this module.
+ *
+ * Wrapped in try/catch (mirroring the CLI's readPackageVersion): a bundler
+ * like esbuild collapses the whole dist tree into a single file, so at runtime
+ * `../package.json` no longer resolves next to the bundle. Without the guard,
+ * this module's top-level read throws at import time and takes the entire
+ * process down — which is exactly what broke the bundled desktop runtime
+ * (`Cannot find module '../package.json'` on any code path that touches the
+ * SDK runtime). The version string is cosmetic, so a placeholder is fine.
+ */
+function readVersion(): string {
+	try {
+		const here = dirname(fileURLToPath(import.meta.url))
+		const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')) as {
+			version?: unknown
+		}
+		return typeof pkg.version === 'string' ? pkg.version : '0.0.0'
+	} catch {
+		return '0.0.0'
+	}
+}
 
-export const VERSION: string = pkg.version
+export const VERSION: string = readVersion()