@roj-ai/sdk 0.1.13 → 0.1.14

package/src/lib/utils/concurrency.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it } from 'bun:test'
+import { mapWithConcurrency, Semaphore } from './concurrency.js'
+
+function defer<T = void>(): { promise: Promise<T>; resolve: (v: T) => void; reject: (e: unknown) => void } {
+	let resolve!: (v: T) => void
+	let reject!: (e: unknown) => void
+	const promise = new Promise<T>((res, rej) => {
+		resolve = res
+		reject = rej
+	})
+	return { promise, resolve, reject }
+}
+
+describe('mapWithConcurrency', () => {
+	it('preserves input order regardless of completion order', async () => {
+		const delays = [50, 10, 30, 5, 20]
+		const results = await mapWithConcurrency(delays, 3, async (ms, i) => {
+			await new Promise(r => setTimeout(r, ms))
+			return `${i}:${ms}`
+		})
+		expect(results).toEqual(['0:50', '1:10', '2:30', '3:5', '4:20'])
+	})
+
+	it('does not exceed the concurrency limit', async () => {
+		let active = 0
+		let peak = 0
+		const items = Array.from({ length: 20 }, (_, i) => i)
+
+		await mapWithConcurrency(items, 4, async () => {
+			active++
+			peak = Math.max(peak, active)
+			await new Promise(r => setTimeout(r, 5))
+			active--
+		})
+
+		expect(peak).toBeLessThanOrEqual(4)
+		expect(peak).toBe(4)
+	})
+
+	it('handles empty input without spawning workers', async () => {
+		let calls = 0
+		const results = await mapWithConcurrency([], 5, async () => {
+			calls++
+			return 1
+		})
+		expect(results).toEqual([])
+		expect(calls).toBe(0)
+	})
+
+	it('caps worker count at item count when concurrency > items', async () => {
+		let active = 0
+		let peak = 0
+		const items = [1, 2]
+
+		await mapWithConcurrency(items, 10, async () => {
+			active++
+			peak = Math.max(peak, active)
+			await new Promise(r => setTimeout(r, 5))
+			active--
+		})
+
+		expect(peak).toBe(2)
+	})
+
+	it('propagates errors thrown by the worker fn', async () => {
+		await expect(
+			mapWithConcurrency([1, 2, 3], 2, async (n) => {
+				if (n === 2) throw new Error('boom')
+				return n
+			}),
+		).rejects.toThrow('boom')
+	})
+})
+
+describe('Semaphore', () => {
+	it('rejects invalid limits', () => {
+		expect(() => new Semaphore(0)).toThrow()
+		expect(() => new Semaphore(-1)).toThrow()
+		expect(() => new Semaphore(1.5)).toThrow()
+	})
+
+	it('caps concurrent executions at limit', async () => {
+		const gate = new Semaphore(3)
+		let active = 0
+		let peak = 0
+
+		const tasks = Array.from({ length: 12 }, () =>
+			gate.run(async () => {
+				active++
+				peak = Math.max(peak, active)
+				await new Promise(r => setTimeout(r, 10))
+				active--
+			}),
+		)
+
+		await Promise.all(tasks)
+		expect(peak).toBe(3)
+		expect(active).toBe(0)
+	})
+
+	it('admits waiters in FIFO order', async () => {
+		const gate = new Semaphore(1)
+		const order: number[] = []
+		const blocker = defer()
+
+		// Hold the only slot
+		const held = gate.run(async () => {
+			await blocker.promise
+		})
+
+		// Queue three waiters in known order, with their own blockers so the test
+		// can observe entry order without relying on real timers.
+		const gates = [defer(), defer(), defer()]
+		const queued = gates.map((g, i) =>
+			gate.run(async () => {
+				order.push(i)
+				await g.promise
+			}),
+		)
+
+		// Yield so all three are queued.
+		await new Promise(r => setTimeout(r, 0))
+		expect(order).toEqual([])
+
+		// Release the holder; waiter 0 should run first.
+		blocker.resolve()
+		await new Promise(r => setTimeout(r, 0))
+		expect(order).toEqual([0])
+
+		gates[0]!.resolve()
+		await new Promise(r => setTimeout(r, 0))
+		expect(order).toEqual([0, 1])
+
+		gates[1]!.resolve()
+		await new Promise(r => setTimeout(r, 0))
+		expect(order).toEqual([0, 1, 2])
+
+		gates[2]!.resolve()
+		await Promise.all([held, ...queued])
+	})
+
+	it('releases the slot when the body throws', async () => {
+		const gate = new Semaphore(1)
+
+		await expect(gate.run(async () => {
+			throw new Error('boom')
+		})).rejects.toThrow('boom')
+
+		// Slot must be free again — this would deadlock otherwise.
+		const result = await gate.run(async () => 42)
+		expect(result).toBe(42)
+	})
+
+	it('serializes work under limit=1', async () => {
+		const gate = new Semaphore(1)
+		const events: string[] = []
+
+		const tasks = [0, 1, 2].map(i =>
+			gate.run(async () => {
+				events.push(`start:${i}`)
+				await new Promise(r => setTimeout(r, 5))
+				events.push(`end:${i}`)
+			}),
+		)
+
+		await Promise.all(tasks)
+		expect(events).toEqual(['start:0', 'end:0', 'start:1', 'end:1', 'start:2', 'end:2'])
+	})
+})

package/src/lib/utils/concurrency.ts

@@ -0,0 +1,72 @@
+/**
+ * Run an async mapping with bounded concurrency.
+ *
+ * Spawns up to `concurrency` workers that pull from a shared cursor.
+ * Results preserve input order.
+ */
+export async function mapWithConcurrency<T, R>(
+	items: readonly T[],
+	concurrency: number,
+	fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+	const results: R[] = new Array(items.length)
+	let next = 0
+	const workerCount = Math.max(1, Math.min(concurrency, items.length))
+	const workers = Array.from({ length: workerCount }, async () => {
+		while (true) {
+			const i = next++
+			if (i >= items.length) return
+			results[i] = await fn(items[i] as T, i)
+		}
+	})
+	await Promise.all(workers)
+	return results
+}
+
+/**
+ * Counting semaphore with FIFO waiter queue.
+ *
+ * Use `run(fn)` to execute work under the gate — acquires before invoking,
+ * releases on resolve/reject. Suitable for bounding contention on a shared
+ * resource (e.g. concurrent LLM calls) regardless of how many call sites
+ * compete for it.
+ */
+export class Semaphore {
+	private active = 0
+	private readonly waiters: Array<() => void> = []
+
+	constructor(private readonly limit: number) {
+		if (!Number.isInteger(limit) || limit < 1) {
+			throw new Error(`Semaphore limit must be a positive integer, got ${limit}`)
+		}
+	}
+
+	async run<T>(fn: () => Promise<T>): Promise<T> {
+		await this.acquire()
+		try {
+			return await fn()
+		} finally {
+			this.release()
+		}
+	}
+
+	private acquire(): Promise<void> {
+		if (this.active < this.limit) {
+			this.active++
+			return Promise.resolve()
+		}
+		return new Promise<void>(resolve => {
+			this.waiters.push(resolve)
+		})
+	}
+
+	private release(): void {
+		const next = this.waiters.shift()
+		if (next) {
+			// Slot transfers directly to the next waiter; active stays unchanged.
+			next()
+		} else {
+			this.active--
+		}
+	}
+}

package/src/plugins/uploads/plugin.ts

@@ -2,11 +2,24 @@ import z from 'zod/v4'
 import { ValidationErrors } from '~/core/errors.js'
 import type { FileStore } from '~/core/file-store/types.js'
 import { definePlugin } from '~/core/plugins/plugin-builder.js'
+import { SessionId } from '~/core/sessions/schema.js'
 import { Err, Ok } from '~/lib/utils/result.js'
 import type { PreprocessorRegistry } from './preprocessor.js'
 import { generateUploadId, type MessageAttachment, UploadId, type UploadMetadata } from './schema.js'
 import { type PendingUpload, uploadEvents, type UploadsState } from './state.js'
 
+// ============================================================================
+// Notification schemas
+// ============================================================================
+
+const statusChangedSchema = z.object({
+	sessionId: z.string(),
+	uploadId: z.string(),
+	status: z.enum(['processing', 'ready', 'failed']),
+	extractedContent: z.string().optional(),
+	error: z.string().optional(),
+})
+
 // ============================================================================
 // Constants
 // ============================================================================
@@ -66,6 +79,69 @@ function formatUploadsForLLM(uploads: PendingUpload[], sessionRoot: string): str
 	return blocks.join('\n')
 }
 
+/**
+ * Run preprocessor (with timeout) and persist final upload metadata to disk.
+ * Returns the resolved status + extracted/derived data for the caller to emit.
+ */
+async function runPreprocessAndPersist(args: {
+	uploadId: string
+	sessionId: SessionId
+	uploadStore: FileStore
+	filePath: string
+	filename: string
+	mimeType: string
+	size: number
+	createdAt: number
+	preprocessorRegistry?: PreprocessorRegistry
+}): Promise<{
+	status: 'ready' | 'failed'
+	extractedContent?: string
+	derivedPaths?: string[]
+	error?: string
+}> {
+	const preprocessor = args.preprocessorRegistry?.getForMimeType(args.mimeType)
+
+	let status: 'ready' | 'failed' = 'ready'
+	let extractedContent: string | undefined
+	let derivedPaths: string[] | undefined
+	let errorMessage: string | undefined
+
+	if (preprocessor) {
+		const processPromise = preprocessor.process(args.filePath, args.mimeType, {
+			files: args.uploadStore,
+		})
+		const timeoutPromise = sleep(PROCESSING_TIMEOUT_MS).then(() => ({
+			ok: false as const,
+			error: new Error('Processing timeout'),
+		}))
+		const result = await Promise.race([processPromise, timeoutPromise])
+		if (result.ok) {
+			extractedContent = result.value.extractedContent
+			derivedPaths = result.value.derivedPaths
+		} else {
+			status = 'failed'
+			errorMessage = result.error.message
+		}
+	}
+
+	const metadata: UploadMetadata = {
+		uploadId: UploadId(args.uploadId),
+		sessionId: args.sessionId,
+		filename: args.filename,
+		mimeType: args.mimeType,
+		size: args.size,
+		path: args.filePath,
+		status,
+		extractedContent,
+		derivedPaths,
+		createdAt: args.createdAt,
+		completedAt: Date.now(),
+	}
+	await args.uploadStore.write('meta.json', JSON.stringify(metadata, null, 2))
+
+	return { status, extractedContent, derivedPaths, error: errorMessage }
+}
+
 // ============================================================================
 // Plugin
 // ============================================================================
@@ -73,6 +149,7 @@ function formatUploadsForLLM(uploads: PendingUpload[], sessionRoot: string): str
 export const uploadsPlugin = definePlugin('uploads')
 	.pluginConfig<UploadsPluginConfig>()
 	.events([uploadEvents])
+	.notification('uploadStatusChanged', { schema: statusChangedSchema })
 	.state<UploadsState>({
 		key: 'uploads',
 		initial: (): UploadsState => ({ pending: [] }),
@@ -315,91 +392,179 @@ export const uploadsPlugin = definePlugin('uploads')
 		handler: async (ctx, input) => {
 			const { dataFileStore, preprocessorRegistry } = ctx.pluginConfig
 
-			// Validate
 			if (input.size > MAX_FILE_SIZE) {
 				return Err(ValidationErrors.invalid(`File too large: max ${MAX_FILE_SIZE / (1024 * 1024)}MB`))
 			}
-
 			if (!isAllowedMimeType(input.mimeType)) {
 				return Err(ValidationErrors.invalid(`Unsupported file type: ${input.mimeType}`))
 			}
 
-			// Generate upload ID and scoped store
 			const uploadId = generateUploadId()
 			const uploadStore = dataFileStore.scoped(`sessions/${input.sessionId}/uploads/${uploadId}`)
 
-			// Write file to disk
 			const writeResult = await uploadStore.write(input.filename, input.fileBuffer)
-
 			if (!writeResult.ok) {
 				return Err(ValidationErrors.invalid('Failed to write file'))
 			}
 
-			const filePath = writeResult.value.path
-
-			// Run preprocessor (with timeout)
-			let processingResult: 'success' | 'failed' | 'skipped' = 'skipped'
-			let extractedContent: string | undefined
-			let derivedPaths: string[] | undefined
+			const result = await runPreprocessAndPersist({
+				uploadId: String(uploadId),
+				sessionId: ctx.sessionId,
+				uploadStore,
+				filePath: writeResult.value.path,
+				filename: input.filename,
+				mimeType: input.mimeType,
+				size: input.size,
+				createdAt: Date.now(),
+				preprocessorRegistry,
+			})
 
-			const preprocessor = preprocessorRegistry?.getForMimeType(input.mimeType)
+			await ctx.emitEvent(uploadEvents.create('attachment_uploaded', {
+				uploadId,
+				filename: input.filename,
+				mimeType: input.mimeType,
+				size: input.size,
+				status: result.status,
+				extractedContent: result.extractedContent,
+				derivedPaths: result.derivedPaths,
+				error: result.error,
+			}))
 
-			if (preprocessor) {
-				const processPromise = preprocessor.process(filePath, input.mimeType, {
-					files: uploadStore,
-				})
+			return Ok({
+				uploadId: String(uploadId),
+				status: result.status,
+				extractedContent: result.extractedContent,
+			})
+		},
+	})
+	.method('uploadAsync', {
+		input: z.object({
+			sessionId: z.string(),
+			filename: z.string(),
+			mimeType: z.string(),
+			size: z.number(),
+			fileBuffer: z.custom<Buffer>(),
+		}),
+		output: z.object({
+			uploadId: z.string(),
+			status: z.enum(['processing']),
+		}),
+		handler: async (ctx, input) => {
+			const { dataFileStore, preprocessorRegistry } = ctx.pluginConfig
 
-				const timeoutPromise = sleep(PROCESSING_TIMEOUT_MS).then(() => ({
-					ok: false as const,
-					error: new Error('Processing timeout'),
-				}))
+			if (input.size > MAX_FILE_SIZE) {
+				return Err(ValidationErrors.invalid(`File too large: max ${MAX_FILE_SIZE / (1024 * 1024)}MB`))
+			}
+			if (!isAllowedMimeType(input.mimeType)) {
+				return Err(ValidationErrors.invalid(`Unsupported file type: ${input.mimeType}`))
+			}
 
-				const result = await Promise.race([processPromise, timeoutPromise])
+			const uploadId = generateUploadId()
+			const uploadIdStr = String(uploadId)
+			const uploadStore = dataFileStore.scoped(`sessions/${input.sessionId}/uploads/${uploadId}`)
 
-				if (result.ok) {
-					processingResult = 'success'
-					extractedContent = result.value.extractedContent
-					derivedPaths = result.value.derivedPaths
-				} else {
-					processingResult = 'failed'
-				}
+			const writeResult = await uploadStore.write(input.filename, input.fileBuffer)
+			if (!writeResult.ok) {
+				return Err(ValidationErrors.invalid('Failed to write file'))
 			}
 
-			// Create upload metadata
-			const now = Date.now()
-			const uploadStatus = processingResult === 'failed' ? 'failed' as const : 'ready' as const
-			const metadata: UploadMetadata = {
+			const filePath = writeResult.value.path
+			const createdAt = Date.now()
+
+			// Persist initial 'processing' metadata so listPending sees it before preprocessor finishes.
+			const processingMeta: UploadMetadata = {
 				uploadId,
 				sessionId: ctx.sessionId,
 				filename: input.filename,
 				mimeType: input.mimeType,
 				size: input.size,
 				path: filePath,
-				status: uploadStatus,
-				extractedContent,
-				derivedPaths,
-				createdAt: now,
-				completedAt: now,
+				status: 'processing',
+				createdAt,
+				completedAt: createdAt,
 			}
+			await uploadStore.write('meta.json', JSON.stringify(processingMeta, null, 2))
 
-			// Save metadata
-			await uploadStore.write('meta.json', JSON.stringify(metadata, null, 2))
-
-			// Emit event
 			await ctx.emitEvent(uploadEvents.create('attachment_uploaded', {
 				uploadId,
 				filename: input.filename,
 				mimeType: input.mimeType,
 				size: input.size,
-				status: uploadStatus,
-				extractedContent,
-				derivedPaths,
+				status: 'processing',
 			}))
+			ctx.notify('uploadStatusChanged', {
+				sessionId: input.sessionId,
+				uploadId: uploadIdStr,
+				status: 'processing',
+			})
+
+			// Capture refs from ctx before the handler returns — `notify`/`emitEvent`
+			// closures stay valid for the lifetime of the session, which in roj
+			// outlives any single handler call.
+			const { emitEvent, notify, logger } = ctx
+			const sessionId = ctx.sessionId
+
+			void (async () => {
+				try {
+					const result = await runPreprocessAndPersist({
+						uploadId: uploadIdStr,
+						sessionId,
+						uploadStore,
+						filePath,
+						filename: input.filename,
+						mimeType: input.mimeType,
+						size: input.size,
+						createdAt,
+						preprocessorRegistry,
+					})
+
+					await emitEvent(uploadEvents.create('attachment_uploaded', {
+						uploadId,
+						filename: input.filename,
+						mimeType: input.mimeType,
+						size: input.size,
+						status: result.status,
+						extractedContent: result.extractedContent,
+						derivedPaths: result.derivedPaths,
+						error: result.error,
+					}))
+					notify('uploadStatusChanged', {
+						sessionId: input.sessionId,
+						uploadId: uploadIdStr,
+						status: result.status,
+						extractedContent: result.extractedContent,
+						error: result.error,
+					})
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err)
+					logger.error('Async upload processing crashed', err instanceof Error ? err : undefined, {
+						uploadId: uploadIdStr,
+						filename: input.filename,
+					})
+					try {
+						await emitEvent(uploadEvents.create('attachment_uploaded', {
+							uploadId,
+							filename: input.filename,
+							mimeType: input.mimeType,
+							size: input.size,
+							status: 'failed',
+							error: message,
+						}))
+					} catch {
+						// Even event emission failed — best-effort; nothing useful left to do.
+					}
+					notify('uploadStatusChanged', {
+						sessionId: input.sessionId,
+						uploadId: uploadIdStr,
+						status: 'failed',
+						error: message,
+					})
+				}
+			})()
 
 			return Ok({
-				uploadId: String(uploadId),
-				status: uploadStatus,
-				extractedContent,
+				uploadId: uploadIdStr,
+				status: 'processing' as const,
 			})
 		},
 	})