@roj-ai/sdk 0.1.13 → 0.1.15

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

@@ -613,6 +613,129 @@ describe('uploads plugin', () => {
 			await harness.shutdown()
 		})
 
+		// =========================================================================
+		// uploadAsync method
+		// =========================================================================
+
+		it('uploadAsync returns processing immediately, then statusChanged → ready', async () => {
+			const harness = new TestHarness({
+				presets: [createTestPreset()],
+				llmProvider: MockLLMProvider.withFixedResponse({ content: 'Ok', toolCalls: [] }),
+			})
+
+			const session = await harness.createSession('test')
+			const fileContent = Buffer.from('Hello, async world!')
+
+			const result = await session.callPluginMethod('uploads.uploadAsync', {
+				sessionId: String(session.sessionId),
+				filename: 'async.txt',
+				mimeType: 'text/plain',
+				size: fileContent.length,
+				fileBuffer: fileContent,
+			})
+
+			const data = okValue(
+				result,
+				z.object({ uploadId: z.string(), status: z.enum(['processing']) }),
+			)
+			expect(data.status).toBe('processing')
+
+			// Wait for the terminal statusChanged notification (ready or failed).
+			const terminal = await harness.notifications.waitFor((n) => {
+				if (n.pluginName !== 'uploads' || n.type !== 'uploadStatusChanged') return false
+				const p = n.payload as { uploadId: string; status: string }
+				return p.uploadId === data.uploadId && (p.status === 'ready' || p.status === 'failed')
+			})
+			expect((terminal.payload as { status: string }).status).toBe('ready')
+
+			// Two attachment_uploaded events were emitted: processing → ready.
+			const events = await session.getEventsByType(uploadEvents, 'attachment_uploaded')
+			const own = events.filter((e) => String(e.uploadId) === data.uploadId)
+			expect(own).toHaveLength(2)
+			expect(own[0].status).toBe('processing')
+			expect(own[1].status).toBe('ready')
+
+			// State only carries ready uploads — processing event is filtered by reducer.
+			const uploads = selectPluginState<UploadsState>(session.state, 'uploads')
+			if (!uploads) throw new Error('Expected uploads state')
+			expect(uploads.pending).toHaveLength(1)
+			expect(uploads.pending[0]?.uploadId).toBe(data.uploadId)
+			expect(uploads.pending[0]?.status).toBe('ready')
+
+			// First notification was processing.
+			const all = harness.notifications.getByType('uploads', 'uploadStatusChanged')
+			expect(all.length).toBeGreaterThanOrEqual(2)
+			expect((all[0]?.payload as { status: string }).status).toBe('processing')
+
+			await harness.shutdown()
+		})
+
+		it('uploadAsync rejects oversize file synchronously (no event)', async () => {
+			const harness = new TestHarness({
+				presets: [createTestPreset()],
+				llmProvider: MockLLMProvider.withFixedResponse({ content: 'Ok', toolCalls: [] }),
+			})
+
+			const session = await harness.createSession('test')
+
+			const result = await session.callPluginMethod('uploads.uploadAsync', {
+				sessionId: String(session.sessionId),
+				filename: 'huge.txt',
+				mimeType: 'text/plain',
+				size: 11 * 1024 * 1024,
+				fileBuffer: Buffer.from('tiny'),
+			})
+
+			expect(result.ok).toBe(false)
+			if (!result.ok) {
+				expect(result.error.message).toContain('File too large')
+			}
+
+			const events = await session.getEventsByType(uploadEvents, 'attachment_uploaded')
+			expect(events).toHaveLength(0)
+
+			await harness.shutdown()
+		})
+
+		it('uploadAsync — listPending exposes processing then ready', async () => {
+			const harness = new TestHarness({
+				presets: [createTestPreset()],
+				llmProvider: MockLLMProvider.withFixedResponse({ content: 'Ok', toolCalls: [] }),
+			})
+
+			const session = await harness.createSession('test')
+
+			const result = await session.callPluginMethod('uploads.uploadAsync', {
+				sessionId: String(session.sessionId),
+				filename: 'list-async.txt',
+				mimeType: 'text/plain',
+				size: 4,
+				fileBuffer: Buffer.from('data'),
+			})
+
+			const data = okValue(
+				result,
+				z.object({ uploadId: z.string(), status: z.enum(['processing']) }),
+			)
+
+			// Wait for terminal notification so the second meta.json write has landed.
+			await harness.notifications.waitFor((n) => {
+				if (n.pluginName !== 'uploads' || n.type !== 'uploadStatusChanged') return false
+				const p = n.payload as { uploadId: string; status: string }
+				return p.uploadId === data.uploadId && p.status === 'ready'
+			})
+
+			const listResult = await session.callPluginMethod('uploads.listPending', {
+				sessionId: String(session.sessionId),
+			})
+			const list = okValue(listResult, listPendingSchema)
+			const ours = list.uploads.find((u) => u.uploadId === data.uploadId)
+			expect(ours).toBeDefined()
+			expect(ours?.status).toBe('ready')
+
+			await harness.shutdown()
+		})
+
 		it('load deleted upload → error (not ready)', async () => {
 			const harness = new TestHarness({
 				presets: [createTestPreset()],

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
 	// =========================================================================

package/src/transport/http/routes/upload.ts

@@ -113,6 +113,93 @@ export function createUploadRoutes(): Hono<AppEnv> {
 		)
 	})
 
+	/**
+	 * POST /sessions/:sessionId/upload-async
+	 *
+	 * Async variant of /upload — returns immediately with status: 'processing'
+	 * and continues preprocessing in the background. Clients should listen for
+	 * the `uploads.uploadStatusChanged` notification to learn when the upload
+	 * becomes `ready` or `failed`, or fall back to polling `uploads.listPending`.
+	 *
+	 * Form fields: same as /upload.
+	 *
+	 * Response:
+	 * - 202: { uploadId, status: 'processing' }
+	 * - 400: Validation error
+	 * - 404: Session not found
+	 */
+	app.post('/:sessionId/upload-async', async (c: AppContext) => {
+		const { sessionRuntime, logger } = getServices(c)
+		const sessionId = SessionId(c.req.param('sessionId')!)
+
+		const sessionResult = await sessionRuntime.getSession(sessionId)
+		if (!sessionResult.ok) {
+			return c.json(
+				{ error: { type: 'session_not_found', message: `Session not found: ${sessionId}` } },
+				404,
+			)
+		}
+
+		let body: Record<string, string | File>
+		try {
+			body = await c.req.parseBody()
+		} catch {
+			return c.json(
+				{ error: { type: 'parse_error', message: 'Failed to parse multipart form data' } },
+				400,
+			)
+		}
+
+		const file = body.file
+		if (!file || !(file instanceof File)) {
+			return c.json(
+				{ error: { type: 'validation_error', message: 'No file provided' } },
+				400,
+			)
+		}
+
+		const fileBuffer = Buffer.from(await file.arrayBuffer())
+
+		const result = await sessionRuntime.callPluginMethod(sessionId, 'uploads.uploadAsync', {
+			sessionId: String(sessionId),
+			filename: file.name,
+			mimeType: file.type,
+			size: file.size,
+			fileBuffer,
+		})
+
+		if (!result.ok) {
+			return c.json(
+				{ error: { type: result.error.type, message: result.error.type === 'validation_error' ? result.error.message : 'Upload failed' } },
+				400,
+			)
+		}
+
+		const uploadResult = result.value
+		if (typeof uploadResult !== 'object' || uploadResult === null || !('uploadId' in uploadResult)) {
+			return c.json(
+				{ error: { type: 'internal_error', message: 'Plugin did not return expected result' } },
+				500,
+			)
+		}
+
+		logger.info('File upload accepted (async)', {
+			sessionId,
+			uploadId: uploadResult.uploadId,
+			filename: file.name,
+			mimeType: file.type,
+			size: file.size,
+		})
+
+		return c.json(
+			{
+				uploadId: uploadResult.uploadId,
+				status: 'status' in uploadResult ? uploadResult.status : 'processing',
+			},
+			202,
+		)
+	})
+
 	/**
 	 * POST /sessions/:sessionId/upload-from-url
 	 *