@roj-ai/sdk 0.1.13 → 0.1.14

package/src/plugins/uploads/preprocessors/image-classifier.test.ts

@@ -0,0 +1,142 @@
+import { afterAll, beforeAll, describe, expect, it } from 'bun:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { SessionFileStore } from '~/core/file-store/file-store.js'
+import { MockLLMProvider } from '~/core/llm/mock.js'
+import { Semaphore } from '~/lib/utils/concurrency.js'
+import { silentLogger } from '../../../lib/logger/logger.js'
+import { createNodePlatform } from '../../../testing/node-platform.js'
+import { ImageClassifierPreprocessor } from './image-classifier.js'
+
+function defer<T = void>(): { promise: Promise<T>; resolve: (v: T) => void } {
+	let resolve!: (v: T) => void
+	const promise = new Promise<T>((res) => {
+		resolve = res
+	})
+	return { promise, resolve }
+}
+
+describe('ImageClassifierPreprocessor.gate', () => {
+	const platform = createNodePlatform()
+	let workDir: string
+
+	beforeAll(async () => {
+		workDir = await mkdtemp(join(tmpdir(), 'roj-classifier-gate-'))
+	})
+
+	afterAll(async () => {
+		await rm(workDir, { recursive: true, force: true }).catch(() => {})
+	})
+
+	it('caps concurrent vision LLM calls when a gate is provided', async () => {
+		const N = 8
+		const LIMIT = 3
+
+		// Track concurrency inside the mock LLM handler — each call increments
+		// `active` on entry, awaits a release barrier, then decrements on exit.
+		let active = 0
+		let peak = 0
+		const release = defer()
+
+		const llmProvider = new MockLLMProvider(async () => {
+			active++
+			peak = Math.max(peak, active)
+			await release.promise
+			active--
+			return {
+				content: 'desc',
+				toolCalls: [],
+				finishReason: 'stop',
+				metrics: MockLLMProvider.defaultMetrics(),
+			}
+		})
+
+		const gate = new Semaphore(LIMIT)
+		const classifier = new ImageClassifierPreprocessor({
+			llmProvider,
+			logger: silentLogger,
+			fs: platform.fs,
+			gate,
+		})
+
+		// Create N tiny dummy image files — content doesn't matter, classifier
+		// only stats them and hands the path to the (mocked) LLM.
+		const imagePaths = await Promise.all(
+			Array.from({ length: N }, async (_, i) => {
+				const p = join(workDir, `img-${i}.png`)
+				await writeFile(p, Buffer.from([0x89, 0x50, 0x4e, 0x47]))
+				return p
+			}),
+		)
+
+		const fileStore = new SessionFileStore(workDir, undefined, false, platform.fs, 'session')
+
+		const tasks = imagePaths.map((p, i) =>
+			classifier.process(p, 'image/png', { files: fileStore.scoped(`img-${i}-meta`) }),
+		)
+
+		// Let the workers queue up; the first LIMIT should be in-flight.
+		await new Promise(r => setTimeout(r, 20))
+		expect(active).toBeLessThanOrEqual(LIMIT)
+		expect(active).toBe(LIMIT)
+
+		// Release everyone; wait for completion and check peak.
+		release.resolve()
+		const results = await Promise.all(tasks)
+
+		expect(peak).toBe(LIMIT)
+		expect(active).toBe(0)
+		expect(llmProvider.getCallCount()).toBe(N)
+		for (const r of results) {
+			expect(r.ok).toBe(true)
+		}
+	})
+
+	it('does not gate when no semaphore is provided (all run concurrently)', async () => {
+		const N = 6
+		let active = 0
+		let peak = 0
+		const release = defer()
+
+		const llmProvider = new MockLLMProvider(async () => {
+			active++
+			peak = Math.max(peak, active)
+			await release.promise
+			active--
+			return {
+				content: 'desc',
+				toolCalls: [],
+				finishReason: 'stop',
+				metrics: MockLLMProvider.defaultMetrics(),
+			}
+		})
+
+		const classifier = new ImageClassifierPreprocessor({
+			llmProvider,
+			logger: silentLogger,
+			fs: platform.fs,
+		})
+
+		const imagePaths = await Promise.all(
+			Array.from({ length: N }, async (_, i) => {
+				const p = join(workDir, `nogate-${i}.png`)
+				await writeFile(p, Buffer.from([0x89, 0x50, 0x4e, 0x47]))
+				return p
+			}),
+		)
+
+		const fileStore = new SessionFileStore(workDir, undefined, false, platform.fs, 'session')
+
+		const tasks = imagePaths.map((p, i) =>
+			classifier.process(p, 'image/png', { files: fileStore.scoped(`nogate-${i}-meta`) }),
+		)
+
+		await new Promise(r => setTimeout(r, 20))
+		expect(active).toBe(N)
+
+		release.resolve()
+		await Promise.all(tasks)
+		expect(peak).toBe(N)
+	})
+})

package/src/plugins/uploads/preprocessors/image-classifier.ts

@@ -7,6 +7,7 @@
 
 import type { LLMProvider } from '~/core/llm/provider.js'
 import { ModelId } from '~/core/llm/schema.js'
+import type { Semaphore } from '~/lib/utils/concurrency.js'
 import type { Result } from '~/lib/utils/result.js'
 import { Err, Ok } from '~/lib/utils/result.js'
 import type { FileSystem } from '~/platform/fs.js'
@@ -28,6 +29,13 @@ export interface ImageClassifierConfig {
 	fs: FileSystem
 	/** Whether to skip vision and just return metadata */
 	skipVision?: boolean
+	/**
+	 * Optional semaphore to bound concurrent vision LLM calls. All callers
+	 * sharing one instance compete for the same set of permits — useful when
+	 * recursive preprocessors (ZIP → docs → images) would otherwise fan out
+	 * into many simultaneous inferences.
+	 */
+	gate?: Semaphore
 }
 
 // ============================================================================
@@ -47,6 +55,7 @@ export class ImageClassifierPreprocessor implements Preprocessor {
 	private readonly logger: Logger
 	private readonly fs: FileSystem
 	private readonly skipVision: boolean
+	private readonly gate: Semaphore | undefined
 
 	constructor(config: ImageClassifierConfig) {
 		this.llmProvider = config.llmProvider
@@ -54,6 +63,7 @@ export class ImageClassifierPreprocessor implements Preprocessor {
 		this.logger = config.logger
 		this.fs = config.fs
 		this.skipVision = config.skipVision ?? false
+		this.gate = config.gate
 	}
 
 	async process(
@@ -124,7 +134,7 @@ export class ImageClassifierPreprocessor implements Preprocessor {
 	): Promise<string | null> {
 		try {
 			// Use file:// URL - resolved to base64 lazily in LLM provider
-			const result = await this.llmProvider.inference({
+			const inferenceCall = () => this.llmProvider.inference({
 				model: this.visionModel,
 				systemPrompt: 'You are an image description assistant. Describe images concisely in 1-2 sentences.',
 				messages: [
@@ -146,6 +156,8 @@ export class ImageClassifierPreprocessor implements Preprocessor {
 				temperature: 0.3,
 			})
 
+			const result = await (this.gate ? this.gate.run(inferenceCall) : inferenceCall())
+
 			if (result.ok && result.value.content) {
 				return result.value.content.trim()
 			}

package/src/plugins/uploads/preprocessors/markitdown-preprocessor.ts

@@ -13,6 +13,7 @@
  */
 
 import { dirname } from 'node:path'
+import { mapWithConcurrency } from '~/lib/utils/concurrency.js'
 import type { Result } from '~/lib/utils/result.js'
 import { Err, Ok } from '~/lib/utils/result.js'
 import type { FileSystem } from '~/platform/fs.js'
@@ -22,6 +23,7 @@ import type { Logger } from '../../../lib/logger/logger.js'
 import type { Preprocessor, PreprocessorContext, PreprocessorRegistry, PreprocessorResult } from '../preprocessor.js'
 
 const MAX_IMAGES = 50
+const IMAGE_CLASSIFY_CONCURRENCY = 10
 
 function makeExec(processRunner: ProcessRunner) {
 	return (cmd: string, args: string[]) => processRunner.execFile(cmd, args, { timeout: 60_000, maxBuffer: 50 * 1024 * 1024 })
@@ -228,19 +230,17 @@ export async function classifyExtractedImages(
 	registry: PreprocessorRegistry,
 	logger: Logger,
 ): Promise<Array<{ relativePath: string; description: string }>> {
-	const results: Array<{ relativePath: string; description: string }> = []
-
 	const listResult = await imageStore.list('', { maxDepth: 3 })
-	if (!listResult.ok) return results
+	if (!listResult.ok) return []
 
 	const imageFiles = listResult.value
 		.filter(e => e.type === 'file' && IMAGE_EXT_RE.test(e.name))
 		.sort((a, b) => a.name.localeCompare(b.name))
 		.slice(0, MAX_IMAGES)
 
-	for (const imgFile of imageFiles) {
+	const settled = await mapWithConcurrency(imageFiles, IMAGE_CLASSIFY_CONCURRENCY, async (imgFile) => {
 		const imgPathResult = imageStore.realPath(imgFile.name)
-		if (!imgPathResult.ok) continue
+		if (!imgPathResult.ok) return null
 
 		const imgMime = guessImageMime(imgFile.name)
 		let description = imgMime
@@ -255,8 +255,8 @@ export async function classifyExtractedImages(
 			}
 		}
 
-		results.push({ relativePath: `${relativePrefix}/${imgFile.name}`, description })
-	}
+		return { relativePath: `${relativePrefix}/${imgFile.name}`, description }
+	})
 
-	return results
+	return settled.filter((r): r is { relativePath: string; description: string } => r !== null)
 }

package/src/plugins/uploads/preprocessors/zip-preprocessor.ts

@@ -8,6 +8,7 @@
  */
 
 import { extname } from 'node:path'
+import { mapWithConcurrency } from '~/lib/utils/concurrency.js'
 import type { Result } from '~/lib/utils/result.js'
 import { Err, Ok } from '~/lib/utils/result.js'
 import type { ProcessRunner } from '~/platform/process.js'
@@ -17,6 +18,7 @@ import type { Preprocessor, PreprocessorContext, PreprocessorRegistry, Preproces
 const MAX_DEPTH = 3
 const MAX_FILES = 500
 const MAX_TOTAL_SIZE = 100 * 1024 * 1024 // 100MB
+const ZIP_FILE_CONCURRENCY = 10
 
 const MIME_MAP: Record<string, string> = {
 	'.pdf': 'application/pdf',
@@ -116,38 +118,45 @@ export class ZipPreprocessor implements Preprocessor {
 			return Err(new Error('Failed to list extracted files'))
 		}
 
-		const derivedPaths: string[] = []
-		const manifest: string[] = []
-		let fileCount = 0
-		let totalSize = 0
-
 		const files = listResult.value
 			.filter(e => e.type === 'file')
 			.sort((a, b) => a.name.localeCompare(b.name))
 
+		// Pick eligible files first (limits depend on cumulative iteration order, so this stays sequential)
+		const eligible: typeof files = []
+		let totalSize = 0
+		let truncationNotice: string | null = null
+
 		for (const file of files) {
-			if (fileCount >= MAX_FILES) {
-				manifest.push(`... (truncated, ${files.length - fileCount} more files)`)
+			if (eligible.length >= MAX_FILES) {
+				truncationNotice = `... (truncated, ${files.length - eligible.length} more files)`
 				break
 			}
-
 			const fileSize = file.size ?? 0
-			totalSize += fileSize
-			if (totalSize > MAX_TOTAL_SIZE) {
-				manifest.push('... (total size limit reached)')
+			if (totalSize + fileSize > MAX_TOTAL_SIZE) {
+				truncationNotice = '... (total size limit reached)'
 				break
 			}
+			totalSize += fileSize
+			eligible.push(file)
+		}
+
+		const fileCount = eligible.length
 
-			fileCount++
+		// Process eligible files in parallel with bounded concurrency
+		const processed = await mapWithConcurrency(eligible, ZIP_FILE_CONCURRENCY, async (file) => {
+			const collectedPaths: string[] = []
 
 			const fileRealPath = extractStore.realPath(file.name)
 			if (!fileRealPath.ok) {
-				manifest.push(`- ${file.name} (path resolution failed)`)
-				continue
+				return {
+					manifestEntry: `- ${file.name} (path resolution failed)`,
+					derivedPaths: collectedPaths,
+				}
 			}
 
 			const relativePath = `extracted/${file.name}`
-			derivedPaths.push(relativePath)
+			collectedPaths.push(relativePath)
 
 			const mime = getMimeType(file.name)
 			let contentSummary = ''
@@ -171,7 +180,7 @@ export class ZipPreprocessor implements Preprocessor {
 					if (subResult.ok) {
 						if (subResult.value.derivedPaths) {
 							for (const dp of subResult.value.derivedPaths) {
-								derivedPaths.push(`extracted/${file.name}-content/${dp}`)
+								collectedPaths.push(`extracted/${file.name}-content/${dp}`)
 							}
 						}
 						if (subResult.value.extractedContent) {
@@ -186,8 +195,19 @@ export class ZipPreprocessor implements Preprocessor {
 				}
 			}
 
-			manifest.push(`- ${file.name} (${formatSize(fileSize)})${contentSummary}`)
+			return {
+				manifestEntry: `- ${file.name} (${formatSize(file.size ?? 0)})${contentSummary}`,
+				derivedPaths: collectedPaths,
+			}
+		})
+
+		const derivedPaths: string[] = []
+		const manifest: string[] = []
+		for (const item of processed) {
+			derivedPaths.push(...item.derivedPaths)
+			manifest.push(item.manifestEntry)
 		}
+		if (truncationNotice) manifest.push(truncationNotice)
 
 		const fullManifest = `## ZIP Contents (${fileCount} files)\n\n${manifest.join('\n')}`
 

package/src/plugins/uploads/state.ts

@@ -9,7 +9,7 @@ export const uploadEvents = createEventsFactory({
 			filename: z4.string(),
 			mimeType: z4.string(),
 			size: z4.number(),
-			status: z4.enum(['ready', 'failed']),
+			status: z4.enum(['processing', 'ready', 'failed']),
 			extractedContent: z4.string().optional(),
 			derivedPaths: z4.array(z4.string()).optional(),
 			error: z4.string().optional(),

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