@roj-ai/sdk 0.1.14 → 0.1.15

package/src/plugins/context-compact/context-compactor.ts

@@ -2,14 +2,24 @@ import type { AgentId } from '~/core/agents/schema.js'
 import type { CompactedConversationMessage, ContextCompactedEvent } from '~/core/context/state.js'
 import { contextEvents } from '~/core/context/state.js'
 import { withSessionId } from '~/core/events/test-helpers.js'
-import type { LLMMessage, LLMProvider } from '~/core/llm/provider.js'
+import type { InferenceResponse, LLMError, LLMMessage } from '~/core/llm/provider.js'
 import type { ModelId } from '~/core/llm/schema.js'
 import { estimateMessagesTokens } from '~/core/llm/tokens.js'
 import type { SessionId } from '~/core/sessions/schema.js'
 import type { Result } from '~/lib/utils/result.js'
 import { Err, Ok } from '~/lib/utils/result.js'
 import type { Logger } from '../../lib/logger/logger.js'
-import { CONTEXT_SUMMARY_PROMPT, wrapContextSummary } from '../../prompts/index.js'
+import { wrapContextSummary } from '../../prompts/index.js'
+
+/**
+ * Callback used by the compactor to ask the host (an Agent) to run a side-channel
+ * inference reusing its own system prompt, tools, and conversation prefix.
+ *
+ * Implemented in practice by AgentContext.runAuxiliaryInference, which keeps the
+ * agent's prompt cache warm — only the trailing `extraMessages` and the response
+ * tokens are paid for; the rest of the prefix is served from cache.
+ */
+export type RunInferenceFn = (extraMessages: LLMMessage[]) => Promise<Result<InferenceResponse, LLMError>>
 
 // ============================================================================
 // Message formatting for summarization
@@ -76,24 +86,44 @@ function formatToolInput(input: unknown): string {
 // ============================================================================
 
 export interface CompactionConfig {
-	/** Model ID to use for summarization (required) */
-	model: ModelId
-	/** Token threshold to trigger compaction */
+	/**
+	 * @deprecated No longer used. Summarization runs on the agent's own model via
+	 * the auxiliary inference callback so the agent's prompt cache is reused.
+	 * Kept in the interface so existing preset configs continue to type-check.
+	 */
+	model?: ModelId
+	/** Token threshold to trigger compaction. */
 	maxTokens: number
-	/** Number of recent messages to keep uncompacted */
+	/** Number of recent messages to keep uncompacted. */
 	keepRecentMessages: number
-	/** Max tokens for kept recent messages (whichever limit is hit first) */
+	/** Max tokens for kept recent messages (whichever limit is hit first). */
 	keepRecentTokens?: number
-	/** Target token count after compaction (informational) */
+	/** Target token count after compaction (informational). */
 	targetTokens?: number
-	/** System prompt for summarization */
+	/** Optional override for the trailing summarization instruction sent to the model. */
 	summaryPrompt?: string
-	/** Enable history offloading before compaction */
+	/** Enable history offloading before compaction. */
 	offloadHistory?: boolean
-	/** Path prefix for offloaded history (default: /session/.history/) */
+	/** Path prefix for offloaded history (default: /session/.history/). */
 	historyPathPrefix?: string
 }
 
+/**
+ * Trailing user-message instruction appended to the agent's full prefix when
+ * requesting a summary. The model sees its real system prompt, tools and full
+ * conversation, then this instruction last. Phrased to discourage tool calls
+ * — Sonnet-class models reliably emit a plain text response under this prompt.
+ */
+export const DEFAULT_SUMMARY_INSTRUCTION =
+	'[CONTEXT COMPACTION REQUEST]\n'
+	+ 'The conversation above is approaching the context budget. Produce a concise '
+	+ 'summary (under 600 words) of everything discussed and decided so far. Cover: '
+	+ 'completed tasks and their outcomes, key decisions and rationale, current state '
+	+ 'of any in-progress work, important file paths or identifiers, and outstanding '
+	+ 'questions.\n\n'
+	+ 'Reply with plain text only. Do NOT call any tools. Do NOT acknowledge this '
+	+ 'request — just emit the summary directly.'
+
 // ============================================================================
 // Compaction Result
 // ============================================================================
@@ -141,7 +171,6 @@ export interface HistoryOffloader {
 
 export class ContextCompactor {
 	constructor(
-		private readonly llmProvider: LLMProvider,
 		private readonly logger: Logger,
 		private readonly config: CompactionConfig,
 		private readonly historyOffloader?: HistoryOffloader,
@@ -179,10 +208,17 @@ export class ContextCompactor {
 	}
 
 	/**
-	 * Check if compaction is needed based on token count.
+	 * Check if compaction is needed.
+	 *
+	 * Prefers the provider-reported prompt token count from the previous turn
+	 * (authoritative — comes straight from the model's tokenizer). Falls back
+	 * to the in-process estimator when no previous metrics exist (first turn).
+	 *
+	 * The estimator under-counts JSON-heavy tool-result history by ~2x, so
+	 * relying on it alone causes the trigger to never fire in long sessions.
 	 */
-	needsCompaction(messages: LLMMessage[]): boolean {
-		const tokens = estimateMessagesTokens(messages)
+	needsCompaction(messages: LLMMessage[], lastActualPromptTokens?: number): boolean {
+		const tokens = lastActualPromptTokens ?? estimateMessagesTokens(messages)
 		return tokens > this.config.maxTokens
 	}
 
@@ -194,33 +230,42 @@ export class ContextCompactor {
 		sessionId: SessionId,
 		agentId: AgentId,
 		messages: LLMMessage[],
+		runInference: RunInferenceFn,
+		lastActualPromptTokens?: number,
 	): Promise<Result<CompactionResult | null, Error>> {
-		if (!this.needsCompaction(messages)) {
+		if (!this.needsCompaction(messages, lastActualPromptTokens)) {
 			return Ok(null)
 		}
 
-		return this.compact(sessionId, agentId, messages)
+		return this.compact(sessionId, agentId, messages, runInference, lastActualPromptTokens)
 	}
 
 	/**
-	 * Compact conversation history by summarizing older messages.
+	 * Compact conversation history by asking the agent's own model to summarize
+	 * the older portion. The summarization call reuses the agent's existing
+	 * prompt cache via `runInference`, paying only for the trailing instruction
+	 * (a few hundred tokens) and the summary output — not the whole conversation
+	 * a second time.
 	 */
 	async compact(
 		sessionId: SessionId,
 		agentId: AgentId,
 		messages: LLMMessage[],
+		runInference: RunInferenceFn,
+		lastActualPromptTokens?: number,
 	): Promise<Result<CompactionResult, Error>> {
-		const originalTokens = estimateMessagesTokens(messages)
+		const originalTokens = lastActualPromptTokens ?? estimateMessagesTokens(messages)
 
 		this.logger.info('Starting context compaction', {
 			sessionId,
 			agentId,
 			messageCount: messages.length,
-			estimatedTokens: originalTokens,
+			originalTokens,
+			actualTokensReported: lastActualPromptTokens !== undefined,
 		})
 
-		// Split messages: keep recent, compact older
-		// Respect both count limit and token budget (whichever is hit first)
+		// Split messages: keep recent, compact older.
+		// Respect both count limit and token budget (whichever is hit first).
 		const keepCount = this.computeKeepCount(messages)
 		const toCompact = messages.slice(0, messages.length - keepCount)
 		const toKeep = messages.slice(messages.length - keepCount)
@@ -236,20 +281,16 @@ export class ContextCompactor {
 			})
 		}
 
-		// Format messages for summarization
-		const conversationText = toCompact
-			.map(formatMessageForSummary)
-			.join('\n\n')
-
-		// Offload history if enabled
+		// Offload the dropped messages to disk for forensics / replay.
+		// Best-effort; failures are logged but don't block compaction.
 		let historyPath: string | undefined
 		if (this.config.offloadHistory && this.historyOffloader) {
 			try {
+				const conversationText = toCompact.map(formatMessageForSummary).join('\n\n')
 				const pathPrefix = this.config.historyPathPrefix ?? DEFAULT_HISTORY_PATH_PREFIX
 				historyPath = await this.historyOffloader.offload(agentId, conversationText, pathPrefix)
 				this.logger.info('History offloaded', { sessionId, agentId, historyPath })
 			} catch (error) {
-				// History offloading is best-effort, log and continue
 				this.logger.warn('Failed to offload history', {
 					sessionId,
 					agentId,
@@ -258,18 +299,14 @@ export class ContextCompactor {
 			}
 		}
 
-		// Generate summary using LLM
-		const summaryResult = await this.llmProvider.inference({
-			model: this.config.model,
-			systemPrompt: this.config.summaryPrompt ?? CONTEXT_SUMMARY_PROMPT,
-			messages: [
-				{
-					role: 'user',
-					content: `Please summarize this conversation:\n\n${conversationText}`,
-				},
-			],
-			tools: [],
-		})
+		// Inline summarization: append the instruction as a trailing user message
+		// and let the host run inference with the agent's full live prefix. The
+		// agent's prompt cache from the previous turn covers everything up to
+		// (but not including) this instruction.
+		const summaryInstruction = this.config.summaryPrompt ?? DEFAULT_SUMMARY_INSTRUCTION
+		const summaryResult = await runInference([
+			{ role: 'user', content: summaryInstruction },
+		])
 
 		if (!summaryResult.ok) {
 			const llmError = summaryResult.error
@@ -283,9 +320,17 @@ export class ContextCompactor {
 
 		const summary = summaryResult.value.content ?? ''
 
-		// Create summary message (with history reference if offloaded)
+		if (!summary.trim()) {
+			this.logger.warn('Summarization returned empty content', { sessionId, agentId })
+			return Err(new Error('Compaction failed: model returned empty summary'))
+		}
+
+		// Replace the compacted portion with a single user-role summary message.
+		// Using `user` role (not `system`) so the wrap reads as part of the
+		// conversation flow — Anthropic recommends user-role for arbitrary
+		// mid-conversation context blocks.
 		const summaryMessage: LLMMessage = {
-			role: 'system',
+			role: 'user',
 			content: wrapContextSummary(summary, historyPath),
 		}
 

package/src/plugins/context-compact/plugin.ts

@@ -10,36 +10,45 @@ import { type CompactionConfig, ContextCompactor, createContextCompactedEvent, t
 import { FileHistoryOffloader } from './history-offloader.js'
 
 /**
- * Plugin config — session-level compaction settings.
+ * Plugin config — session-level (default) compaction settings.
+ * Individual agents may override fields via `contextCompactPlugin.configureAgent({ ... })`.
  */
 export interface ContextCompactPluginConfig {
 	compaction: CompactionConfig
 }
 
+/**
+ * Per-agent override. Any field omitted falls back to the session-level config.
+ * Used for cases like "orchestrator gets a tighter 50k threshold while subagents
+ * keep the default 200k".
+ */
+export type ContextCompactAgentConfig = Partial<CompactionConfig>
+
 export const contextCompactPlugin = definePlugin('context-compact')
 	.pluginConfig<ContextCompactPluginConfig>()
+	.agentConfig<ContextCompactAgentConfig>()
 	.context(async (ctx, pluginConfig) => {
 		const historyOffloader: HistoryOffloader | undefined = pluginConfig.compaction.offloadHistory
 			? new FileHistoryOffloader(ctx.environment.sessionDir, ctx.platform.fs)
 			: undefined
 
-		const compactor = new ContextCompactor(
-			ctx.llm,
-			ctx.logger,
-			pluginConfig.compaction,
-			historyOffloader,
-		)
-
-		return { compactor }
+		return { historyOffloader, sessionConfig: pluginConfig.compaction }
 	})
 	.hook('beforeInference', async (ctx) => {
-		const compactor = ctx.pluginContext.compactor
+		const { historyOffloader, sessionConfig } = ctx.pluginContext
+		const agentOverrides = ctx.pluginAgentConfig ?? {}
+		const effectiveConfig: CompactionConfig = { ...sessionConfig, ...agentOverrides }
+
+		const compactor = new ContextCompactor(ctx.logger, effectiveConfig, historyOffloader)
 		const historyLLMMessages = ctx.agentState.conversationHistory
+		const lastActualPromptTokens = ctx.agentState.lastInferenceMetrics?.promptTokens
 
 		const result = await compactor.compactIfNeeded(
 			ctx.sessionId,
 			ctx.agentId,
 			historyLLMMessages,
+			ctx.runAuxiliaryInference,
+			lastActualPromptTokens,
 		)
 
 		if (result.ok && result.value !== null) {

package/src/plugins/filesystem/filesystem.integration.test.ts

@@ -22,6 +22,14 @@ beforeAll(() => {
 	fs.writeFileSync(path.join(fixtureDir, 'hello.txt'), 'Hello, world!')
 	fs.writeFileSync(path.join(fixtureDir, 'multiline.txt'), Array.from({ length: 20 }, (_, i) => `Line ${i + 1}`).join('\n'))
 
+	// Create a minimal 1x1 PNG for image tests
+	const onePixelPng = Buffer.from(
+		'89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c489000000'
+			+ '0a49444154789c6300010000000500010d0a2db40000000049454e44ae426082',
+		'hex',
+	)
+	fs.writeFileSync(path.join(fixtureDir, 'pixel.png'), onePixelPng)
+
 	// Create subdirectory with files
 	fs.mkdirSync(path.join(fixtureDir, 'subdir'), { recursive: true })
 	fs.writeFileSync(path.join(fixtureDir, 'subdir', 'nested.txt'), 'Nested content')
@@ -154,6 +162,42 @@ describe('filesystem plugin', () => {
 			await harness.shutdown()
 		})
 
+		it('read image file → file:// URL uses agent-visible input path, not resolved real path', async () => {
+			// Regression: previously read_file returned file://<realPath>, which the
+			// sandboxed FileStore then rejected when re-resolving on the next inference
+			// (it only accepts agent-visible paths like /home/user/session/...). The URL
+			// must echo input.path so it stays resolvable through fileStore.realPath().
+			const filePath = path.join(fixtureDir, 'pixel.png')
+			const harness = createFsHarness({
+				presets: [createFsPreset()],
+				llmProvider: MockLLMProvider.withSequence([
+					{
+						toolCalls: [{
+							id: ToolCallId('tc1'),
+							name: 'read_file',
+							input: { path: filePath },
+						}],
+					},
+					{ content: 'Done', toolCalls: [] },
+				]),
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('Read image')
+
+			const callHistory = harness.llmProvider.getCallHistory()
+			const toolMessages = callHistory[1].messages.filter((m) => m.role === 'tool')
+			expect(toolMessages).toHaveLength(1)
+			const content = toolMessages[0].content
+			expect(Array.isArray(content)).toBe(true)
+			const blocks = content as Array<{ type: string; text?: string; imageUrl?: { url: string } }>
+			const imageBlock = blocks.find((b) => b.type === 'image_url')
+			expect(imageBlock).toBeDefined()
+			expect(imageBlock?.imageUrl?.url).toBe(`file://${filePath}`)
+
+			await harness.shutdown()
+		})
+
 		it('read a directory path → "is not a file" error', async () => {
 			const dirPath = path.join(fixtureDir, 'subdir')
 			const harness = createFsHarness({

package/src/plugins/filesystem/plugin.ts

@@ -158,16 +158,18 @@ export const filesystemPlugin = definePlugin('filesystem')
 						})
 					}
 
-					// Image files → return as multimodal image content
+					// Image files → return as multimodal image content.
+					// Store the agent-visible input.path (not the resolved real path):
+					// the URL survives into conversationHistory and gets re-resolved
+					// via fileStore.realPath() on every subsequent inference. In
+					// sandboxed mode, realPath() rejects already-resolved disk paths
+					// (only accepts the virtual prefix), so storing realPath would
+					// surface as "[Image unavailable: …]" on every later turn.
 					const mimeType = getImageMimeType(input.path)
 					if (mimeType) {
-						const realPathResult = fileStore.realPath(input.path)
-						if (!realPathResult.ok) {
-							return Err({ message: realPathResult.error, recoverable: false })
-						}
 						return Ok([
 							{ type: 'text', text: `Image: ${input.path} (${mimeType}, ${stats.size} bytes)` },
-							{ type: 'image_url', imageUrl: { url: `file://${realPathResult.value}` } },
+							{ type: 'image_url', imageUrl: { url: `file://${input.path}` } },
 						])
 					}
 

package/src/plugins/mailbox/mailbox.integration.test.ts

@@ -581,7 +581,7 @@ describe('mailbox plugin', () => {
 			await harness.shutdown()
 		})
 
-		it('empty-stop LLM response → agent retries; persistent empty → onError reports to parent', async () => {
+		it('empty-stop LLM response → agent retries; persistent empty → coalesces to WAITING, no error', async () => {
 			let workerCalls = 0
 			let orchestratorCalls = 0
 
@@ -603,31 +603,25 @@ describe('mailbox plugin', () => {
 						return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
 					}
 					workerCalls++
-					// Always empty-stop → triggers retry until exhausted, then onError
+					// Always empty-stop → triggers retry until exhausted, then coalesces to WAITING
 					return { content: null, toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
 				},
 			})
 
 			const session = await harness.createSession('test')
-			await session.sendMessage('Start')
-
-			// Worker ends up errored (not idle); poll for the error message to parent.
-			const deadline = Date.now() + 5000
-			let errMsg: { message: { content: string; from: unknown } } | undefined
-			while (Date.now() < deadline) {
-				const events = await session.getEventsByType(mailboxEvents, 'mailbox_message')
-				errMsg = events.find(e =>
-					e.message.from === AgentId('worker_1')
-					&& typeof e.message.content === 'string'
-					&& e.message.content.startsWith('Agent encountered an error:'),
-				)
-				if (errMsg) break
-				await new Promise((r) => setTimeout(r, 50))
-			}
+			await session.sendAndWaitForIdle('Start')
 
 			// Initial + 2 retries = 3 worker LLM calls
 			expect(workerCalls).toBe(3)
-			expect(errMsg).toBeDefined()
+
+			// No error message to parent — exhaustion coalesces to WAITING, not failure
+			const events = await session.getEventsByType(mailboxEvents, 'mailbox_message')
+			const errMsg = events.find(e =>
+				e.message.from === AgentId('worker_1')
+				&& typeof e.message.content === 'string'
+				&& e.message.content.startsWith('Agent encountered an error:'),
+			)
+			expect(errMsg).toBeUndefined()
 
 			await harness.shutdown()
 		})

package/src/plugins/resources/plugin.ts

@@ -112,7 +112,10 @@ export const resourcesPlugin = definePlugin('resources')
 				await fs.writeFile(tempPath, input.fileBuffer)
 
 				try {
-					await exec('unzip', ['-o', '-q', tempPath, '-d', targetDir])
+					// `-x .git .git/*` so a stray .git entry in the ZIP can't overwrite the
+					// worktree's gitdir pointer (which silently breaks every subsequent git
+					// command in the workspace).
+					await exec('unzip', ['-o', '-q', tempPath, '-d', targetDir, '-x', '.git', '.git/*'])
 				} catch (error) {
 					const message = error instanceof Error ? error.message : String(error)
 					// unzip returns exit code 1 for warnings — still usable

package/src/plugins/user-chat/plugin.ts

@@ -208,6 +208,12 @@ const askUserFlatInputSchema = z.object({
 		.optional()
 		.describe("Placeholder text for text input"),
 	multiline: z.boolean().optional().describe("Allow multiline text input"),
+	allowAttachments: z
+		.boolean()
+		.optional()
+		.describe(
+			"Render a file-attach control alongside the text field (text inputType only). Use when the answer needs to come with a file the user already has on hand — logo, brand PDF, source docs, supporting screenshots. Uploaded files reach you the same way as drag-drop attachments in plain chat.",
+		),
 	// rating options
 	min: z
 		.number()
@@ -248,6 +254,7 @@ function transformToAskUserInputType(
 				type: "text",
 				placeholder: input.placeholder,
 				multiline: input.multiline,
+				allowAttachments: input.allowAttachments,
 			};
 		case "confirm":
 			return {
@@ -303,6 +310,56 @@ function formatPendingForLLM(pending: PendingInboundMessage[]): string {
 	return parts.join("\n");
 }
 
+// Some models (notably routed through OpenRouter — Gemini/Llama/Qwen) emit
+// non-ASCII tool argument strings as double-escaped JSON: the wire form is
+// `"\\u0159"`, which JSON.parse turns into a literal 6-char `ř` instead
+// of `ř`. The user then sees raw escape sequences in their UI. Applied only
+// to user-facing display fields (question, placeholder, labels, message body)
+// — never to identifiers like `option.value` (must round-trip back to the LLM
+// unchanged) or to code-bearing inputs of other tools.
+function decodeUnicodeEscapes(value: string): string;
+function decodeUnicodeEscapes(value: string | undefined): string | undefined;
+function decodeUnicodeEscapes(value: string | undefined): string | undefined {
+	if (value === undefined) return undefined;
+	if (!value.includes("\\u")) return value;
+	return value.replace(/\\u([0-9a-fA-F]{4})/g, (_, hex) =>
+		String.fromCharCode(parseInt(hex, 16)),
+	);
+}
+
+function decodeAskUserDisplayStrings(input: AskUserInputType): AskUserInputType {
+	switch (input.type) {
+		case "text":
+			return { ...input, placeholder: decodeUnicodeEscapes(input.placeholder) };
+		case "single_choice":
+		case "multi_choice":
+			return {
+				...input,
+				options: input.options.map((o) => ({
+					...o,
+					label: decodeUnicodeEscapes(o.label),
+					description: decodeUnicodeEscapes(o.description),
+				})),
+			};
+		case "confirm":
+			return {
+				...input,
+				confirmLabel: decodeUnicodeEscapes(input.confirmLabel),
+				cancelLabel: decodeUnicodeEscapes(input.cancelLabel),
+			};
+		case "rating":
+			return input.labels
+				? {
+					...input,
+					labels: {
+						min: decodeUnicodeEscapes(input.labels.min),
+						max: decodeUnicodeEscapes(input.labels.max),
+					},
+				}
+				: input;
+	}
+}
+
 // ============================================================================
 // Plugin
 // ============================================================================
@@ -687,7 +744,7 @@ export const userChatPlugin = definePlugin("user-chat")
 					const format = input.format ?? "text";
 					const result = await ctx.self.tellUser({
 						agentId: context.agentId,
-						message: input.message,
+						message: decodeUnicodeEscapes(input.message),
 						format,
 					});
 					if (!result.ok)
@@ -710,8 +767,8 @@ export const userChatPlugin = definePlugin("user-chat")
 					const inputType = transformToAskUserInputType(input);
 					const result = await ctx.self.askQuestion({
 						agentId: context.agentId,
-						question: input.question,
-						inputType,
+						question: decodeUnicodeEscapes(input.question),
+						inputType: decodeAskUserDisplayStrings(inputType),
 					});
 					if (!result.ok)
 						return Err({ message: result.error.message, recoverable: false });

package/src/plugins/user-chat/schema.ts

@@ -19,9 +19,17 @@ export type AskUserOption = {
 
 /**
  * Input type for ask_user tool - defines how the user should respond.
+ *
+ * `text.allowAttachments` opts the question into an inline file-attach control
+ * next to the text field — used when the agent needs the answer to come with a
+ * file (logo, brand PDF, supporting docs). Attachments piggy-back on the
+ * existing pending-attachments machinery: clients reuse `uploadFile()` /
+ * `pendingAttachments`, so the answer payload itself stays a plain string and
+ * the agent sees uploaded files via the normal `<attachment>` blocks in its
+ * inbox alongside the question answer.
  */
 export type AskUserInputType =
-	| { type: 'text'; placeholder?: string; multiline?: boolean }
+	| { type: 'text'; placeholder?: string; multiline?: boolean; allowAttachments?: boolean }
 	| { type: 'single_choice'; options: AskUserOption[] }
 	| {
 		type: 'multi_choice'
@@ -47,6 +55,7 @@ export const askUserInputTypeSchema = z.discriminatedUnion('type', [
 		type: z.literal('text'),
 		placeholder: z.string().optional(),
 		multiline: z.boolean().optional(),
+		allowAttachments: z.boolean().optional(),
 	}),
 	z.object({
 		type: z.literal('single_choice'),

package/src/plugins/user-chat/user-chat.integration.test.ts

@@ -564,6 +564,105 @@ describe('user-chat plugin', () => {
 		})
 	})
 
+	// =========================================================================
+	// Unicode escape decoding (defensive fix for models that double-escape
+	// non-ASCII in tool argument JSON — see plugin.ts decodeUnicodeEscapes).
+	// =========================================================================
+
+	describe('unicode escape decoding in user-facing fields', () => {
+		it('ask_user (text) → literal \\uXXXX in question/placeholder is decoded', async () => {
+			const harness = new TestHarness({
+				presets: [createTestPreset()],
+				llmProvider: MockLLMProvider.withSequence([
+					{
+						toolCalls: [{
+							id: ToolCallId('tc1'),
+							name: 'ask_user',
+							input: {
+								question: 'Pro\\u010d ne?',
+								inputType: 'text',
+								placeholder: 'Nap\\u0159. ano',
+							},
+						}],
+					},
+					{ content: 'Done', toolCalls: [] },
+				]),
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('Hi')
+
+			const askNotifications = harness.notifications.getByType('user-chat', 'askUser')
+			expect(askNotifications[0].payload).toMatchObject({
+				question: 'Proč ne?',
+				inputType: { type: 'text', placeholder: 'Např. ano' },
+			})
+
+			await harness.shutdown()
+		})
+
+		it('ask_user (single_choice) → option labels decoded, values left intact', async () => {
+			const harness = new TestHarness({
+				presets: [createTestPreset()],
+				llmProvider: MockLLMProvider.withSequence([
+					{
+						toolCalls: [{
+							id: ToolCallId('tc1'),
+							name: 'ask_user',
+							input: {
+								question: 'Pick',
+								inputType: 'single_choice',
+								options: [
+									{ value: 'kun_ze_\\u0159adu', label: 'K\\u016f\\u0148 ze \\u0159adu' },
+								],
+							},
+						}],
+					},
+					{ content: 'Done', toolCalls: [] },
+				]),
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('Hi')
+
+			const askNotifications = harness.notifications.getByType('user-chat', 'askUser')
+			expect(askNotifications[0].payload).toMatchObject({
+				inputType: {
+					type: 'single_choice',
+					// Value preserved verbatim so answer round-trip stays consistent
+					// with what the LLM emitted.
+					options: [{ value: 'kun_ze_\\u0159adu', label: 'Kůň ze řadu' }],
+				},
+			})
+
+			await harness.shutdown()
+		})
+
+		it('tell_user → literal \\uXXXX in message is decoded', async () => {
+			const harness = new TestHarness({
+				presets: [createTestPreset()],
+				llmProvider: MockLLMProvider.withSequence([
+					{
+						toolCalls: [{
+							id: ToolCallId('tc1'),
+							name: 'tell_user',
+							input: { message: 'Ahoj sv\\u011bte' },
+						}],
+					},
+					{ content: 'Done', toolCalls: [] },
+				]),
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('Hi')
+
+			const msgs = harness.notifications.getByType('user-chat', 'agentMessage')
+			expect(msgs[0].payload).toMatchObject({ content: 'Ahoj světe' })
+
+			await harness.shutdown()
+		})
+	})
+
 	// =========================================================================
 	// XML mode
 	// =========================================================================