@roj-ai/sdk 0.1.12 → 0.1.14

package/dist/user-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"user-config.js","sourceRoot":"","sources":["../src/user-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwCH;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC7C,OAAO,MAAM,CAAA;AACd,CAAC"}
+{"version":3,"file":"user-config.js","sourceRoot":"","sources":["../src/user-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuDH;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC7C,OAAO,MAAM,CAAA;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@roj-ai/sdk",
-	"version": "0.1.12",
+	"version": "0.1.14",
 	"type": "module",
 	"main": "./dist/index.js",
 	"exports": {
@@ -135,7 +135,7 @@
 		"type-check": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@roj-ai/transport": "^0.1.12",
+		"@roj-ai/transport": "^0.1.14",
 		"@hono/zod-validator": "0.7.6",
 		"hono": "4.12.5",
 		"ignore": "7.0.5",

package/src/bootstrap.ts

@@ -28,6 +28,7 @@ import type { ToolExecutor } from './core/tools/executor.js'
 import { ToolExecutor as ToolExecutorImpl } from './core/tools/executor.js'
 import { ConsoleLogger, JsonLogger } from './lib/logger/index.js'
 import type { Logger } from './lib/logger/logger.js'
+import { Semaphore } from './lib/utils/concurrency.js'
 import { agentStatusPlugin } from './plugins/agent-status/plugin.js'
 import { agentsPlugin } from './plugins/agents/plugin.js'
 import { filesystemPlugin } from './plugins/filesystem/index.js'
@@ -119,7 +120,8 @@ export function bootstrap(config: Config, userConfig: RojConfig, platform: Platf
 	const portPool = new PortPool()
 
 	const preprocessorRegistry = new PreprocessorRegistry()
-	preprocessorRegistry.register(new ImageClassifierPreprocessor({ llmProvider, logger, fs: platform.fs }))
+	const imageClassifierGate = new Semaphore(config.imageClassifierConcurrency ?? 10)
+	preprocessorRegistry.register(new ImageClassifierPreprocessor({ llmProvider, logger, fs: platform.fs, gate: imageClassifierGate }))
 	preprocessorRegistry.register(new MarkitdownPreprocessor({ registry: preprocessorRegistry, logger, fs: platform.fs, process: platform.process }))
 	preprocessorRegistry.register(new ZipPreprocessor({ registry: preprocessorRegistry, logger, process: platform.process }))
 

package/src/config.ts

@@ -30,6 +30,9 @@ export interface Config {
 	// LLM Logging
 	llmLoggingEnabled?: boolean
 
+	/** Max concurrent vision LLM calls when classifying uploaded images. Default 10. */
+	imageClassifierConcurrency?: number
+
 	// Logging
 	logLevel: LogLevel
 	logFormat: 'console' | 'json'
@@ -59,6 +62,9 @@ export const loadConfig = (): Config => {
 		defaultModel: process.env.DEFAULT_MODEL ?? 'anthropic/claude-haiku-4.5',
 		thinkingBudget: process.env.THINKING_BUDGET ? parseInt(process.env.THINKING_BUDGET, 10) : undefined,
 		llmLoggingEnabled: process.env.LLM_LOGGING_ENABLED !== 'false',
+		imageClassifierConcurrency: process.env.IMAGE_CLASSIFIER_CONCURRENCY
+			? parseInt(process.env.IMAGE_CLASSIFIER_CONCURRENCY, 10)
+			: undefined,
 		logLevel: (process.env.LOG_LEVEL ?? 'info') as LogLevel,
 		logFormat: (process.env.LOG_FORMAT ?? 'console') as 'console' | 'json',
 		workerUrl: process.env.WORKER_URL,

package/src/core/sessions/session-manager.ts

@@ -677,15 +677,24 @@ export class SessionManager {
 		const plugins: ConfiguredPlugin[] = []
 
 		for (const pluginDef of this.systemPlugins) {
-			// Determine config: preset explicit > infra auto-derived > no config (void)
+			// Determine config: merge infra (auto-derived) + preset explicit (overrides),
+			// fall back to whichever exists, else no config (void).
 			let config: unknown
 			let hasConfig = false
 
-			if (presetConfigs.has(pluginDef.name)) {
-				config = presetConfigs.get(pluginDef.name)
+			const presetConfig = presetConfigs.get(pluginDef.name)
+			const infraConfig = infraConfigs.get(pluginDef.name)
+			const isMergeable = (v: unknown): v is Record<string, unknown> =>
+				typeof v === 'object' && v !== null && !Array.isArray(v)
+
+			if (presetConfig !== undefined && infraConfig !== undefined && isMergeable(presetConfig) && isMergeable(infraConfig)) {
+				config = { ...infraConfig, ...presetConfig }
+				hasConfig = true
+			} else if (presetConfig !== undefined) {
+				config = presetConfig
 				hasConfig = true
-			} else if (infraConfigs.has(pluginDef.name)) {
-				config = infraConfigs.get(pluginDef.name)
+			} else if (infraConfig !== undefined) {
+				config = infraConfig
 				hasConfig = true
 			}
 

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/agents/plugin.ts

@@ -12,11 +12,12 @@
 
 import z from 'zod/v4'
 import { AgentId, agentIdSchema, generateAgentId } from '~/core/agents/schema.js'
-import { agentEvents } from '~/core/agents/state.js'
+import { type AgentState, agentEvents } from '~/core/agents/state.js'
 import { AgentErrors, ValidationErrors } from '~/core/errors.js'
 import { definePlugin } from '~/core/plugins/index.js'
 import { getNextAgentSeq } from '~/core/sessions/state.js'
 import { createTool } from '~/core/tools/definition.js'
+import type { Logger } from '~/lib/logger/logger.js'
 import { Err, Ok } from '~/lib/utils/result.js'
 import { mailboxPlugin } from '~/plugins/mailbox/plugin.js'
 
@@ -36,6 +37,132 @@ export interface SpawnableAgentInfo {
 export interface AgentsPluginConfig {
 	/** Map of agent name → spawn info for generating typed tools */
 	agentDefinitions: Map<string, SpawnableAgentInfo>
+	/**
+	 * Supervision tick interval (ms) for parent agents. When set, parent agents
+	 * with active children receive a periodic <children-status> snapshot via
+	 * mailbox so they stay aware of long-running sub-agents and prompt cache
+	 * stays warm.
+	 *
+	 * Default: undefined (disabled). Recommended: 240000 (4 min, just under
+	 * the 5 min prompt cache TTL — see SUPERVISION_INTERVAL_CACHE_FRIENDLY).
+	 */
+	superviseChildrenIntervalMs?: number
+}
+
+/**
+ * Recommended supervision interval — 4 min, just under prompt cache TTL.
+ * Each tick triggers a parent inference, keeping the prompt cache warm.
+ */
+export const SUPERVISION_INTERVAL_CACHE_FRIENDLY = 240_000
+
+/** Per-session runtime state held in plugin context — timers + trigger callback. */
+interface AgentsPluginContext {
+	timers: Map<AgentId, ReturnType<typeof setTimeout>>
+	/** Set in onSessionReady — calls agents._supervisionTick via callPluginMethod (fresh ctx). */
+	triggerTick: ((agentId: AgentId) => Promise<unknown>) | null
+	/** null = supervision disabled for this session. */
+	intervalMs: number | null
+	logger: Logger | null
+}
+
+/**
+ * Get all direct children of an agent.
+ */
+function getDirectChildren(sessionAgents: Map<AgentId, AgentState>, parentId: AgentId): AgentState[] {
+	const out: AgentState[] = []
+	for (const agent of sessionAgents.values()) {
+		if (agent.parentId === parentId) out.push(agent)
+	}
+	return out
+}
+
+/**
+ * Count assistant tool calls across conversation history + currently pending.
+ */
+function countToolCalls(state: AgentState): number {
+	let total = state.pendingToolCalls.length
+	for (const m of state.conversationHistory) {
+		if (m.role === 'assistant' && m.toolCalls) total += m.toolCalls.length
+	}
+	return total
+}
+
+/**
+ * Count completed LLM inferences (= assistant turns in history).
+ */
+function countLLMCalls(state: AgentState): number {
+	let total = 0
+	for (const m of state.conversationHistory) {
+		if (m.role === 'assistant') total++
+	}
+	return total
+}
+
+/**
+ * Build a compact "first N words..last M words" preview of the agent's most
+ * recent assistant message (skipping empty turns). Returns null if none.
+ */
+function previewLastAssistant(state: AgentState, headWords = 5, tailWords = 5): string | null {
+	for (let i = state.conversationHistory.length - 1; i >= 0; i--) {
+		const m = state.conversationHistory[i]
+		if (m.role !== 'assistant') continue
+		const text = m.content?.trim()
+		if (!text) continue
+		const words = text.split(/\s+/)
+		if (words.length <= headWords + tailWords + 1) return text
+		return `${words.slice(0, headWords).join(' ')}..${words.slice(-tailWords).join(' ')}`
+	}
+	return null
+}
+
+/**
+ * Build a compact children-status snapshot for the given parent agent.
+ */
+function buildChildrenStatus(sessionAgents: Map<AgentId, AgentState>, parentId: AgentId): string {
+	const children = getDirectChildren(sessionAgents, parentId)
+	const lines = children.map((c) => {
+		const tools = countToolCalls(c)
+		const llm = countLLMCalls(c)
+		const subs = getDirectChildren(sessionAgents, c.id).length
+		const last = previewLastAssistant(c)
+
+		const parts: string[] = [c.id, c.status]
+		parts.push(`${tools} tools`)
+		parts.push(`${llm} llm`)
+		if (subs > 0) parts.push(`${subs} sub${subs === 1 ? '' : 's'}`)
+		if (last) parts.push(`last "${last.replaceAll('"', "'")}"`)
+
+		return parts.join(', ')
+	})
+
+	return `<children-status>\n${lines.join('\n')}\n</children-status>`
+}
+
+/**
+ * (Re)schedule a supervision tick for an agent. Any existing timer is cleared first.
+ */
+function scheduleSupervisionTick(
+	pluginContext: AgentsPluginContext,
+	agentId: AgentId,
+	delayMs: number,
+): void {
+	const existing = pluginContext.timers.get(agentId)
+	if (existing) clearTimeout(existing)
+
+	const timer = setTimeout(() => {
+		pluginContext.timers.delete(agentId)
+		const trigger = pluginContext.triggerTick
+		if (!trigger) return
+		trigger(agentId).catch((err) => {
+			pluginContext.logger?.error(
+				'Supervision tick failed',
+				err instanceof Error ? err : undefined,
+				{ agentId },
+			)
+		})
+	}, delayMs)
+
+	pluginContext.timers.set(agentId, timer)
 }
 
 /**
@@ -57,6 +184,12 @@ function createStartAgentSchema(agent: SpawnableAgentInfo) {
 export const agentsPlugin = definePlugin('agents')
 	.pluginConfig<AgentsPluginConfig>()
 	.dependencies([mailboxPlugin])
+	.context(async (): Promise<AgentsPluginContext> => ({
+		timers: new Map(),
+		triggerTick: null,
+		intervalMs: null,
+		logger: null,
+	}))
 	.isEnabled((ctx) => {
 		return ctx.agentConfig.spawnableAgents.length > 0
 	})
@@ -108,6 +241,11 @@ export const agentsPlugin = definePlugin('agents')
 				parentId: input.parentId,
 			})
 
+			// Ensure parent has a supervision tick running now that it has a child.
+			if (ctx.pluginContext.intervalMs !== null) {
+				scheduleSupervisionTick(ctx.pluginContext, parentId, ctx.pluginContext.intervalMs)
+			}
+
 			return Ok({ agentId })
 		},
 	})
@@ -196,12 +334,99 @@ export const agentsPlugin = definePlugin('agents')
 			return Ok({})
 		},
 	})
-	.systemPrompt(() => {
-		return `## Working with Child Agents
+	.method('_supervisionTick', {
+		input: z.object({ agentId: agentIdSchema }),
+		output: z.object({}),
+		handler: async (ctx, input) => {
+			const agentId = AgentId(input.agentId)
+
+			// Self may already be gone (terminated mid-tick); just stop.
+			if (!ctx.sessionState.agents.has(agentId)) return Ok({})
+
+			const children = getDirectChildren(ctx.sessionState.agents, agentId)
+			if (children.length === 0) {
+				// No active children → don't reschedule. spawn() will re-arm if/when needed.
+				return Ok({})
+			}
+
+			const snapshot = buildChildrenStatus(ctx.sessionState.agents, agentId)
+			const sendResult = await ctx.deps.mailbox.send({
+				toAgentId: agentId,
+				content: snapshot,
+				fromSupervisor: true,
+			})
+			if (!sendResult.ok) {
+				ctx.logger.warn('Supervision snapshot send failed', {
+					agentId,
+					error: sendResult.error.message,
+				})
+			}
+
+			// Reschedule the next tick from now (rolling).
+			if (ctx.pluginContext.intervalMs !== null) {
+				scheduleSupervisionTick(ctx.pluginContext, agentId, ctx.pluginContext.intervalMs)
+			}
+
+			return Ok({})
+		},
+	})
+	.sessionHook('onSessionReady', async (ctx) => {
+		const intervalMs = ctx.pluginConfig.superviseChildrenIntervalMs
+		if (intervalMs === undefined) {
+			// Supervision disabled (default). No timer wiring; spawn() and
+			// afterInference() check intervalMs === null and skip too.
+			ctx.pluginContext.intervalMs = null
+			return
+		}
+		ctx.pluginContext.intervalMs = intervalMs
+		ctx.pluginContext.logger = ctx.logger
+
+		// Wire the trigger callback — calls back via self.* so each tick gets a
+		// fresh ctx (live sessionState/pluginState/deps).
+		ctx.pluginContext.triggerTick = (agentId) => ctx.self._supervisionTick({ agentId })
+
+		// (Re-)schedule timers for every agent that currently has direct children.
+		// Covers initial session creation AND server-restart reload (onSessionReady
+		// fires in both paths). Worst-case drift after restart = intervalMs.
+		for (const agent of ctx.sessionState.agents.values()) {
+			if (getDirectChildren(ctx.sessionState.agents, agent.id).length > 0) {
+				scheduleSupervisionTick(ctx.pluginContext, agent.id, intervalMs)
+			}
+		}
+	})
+	.sessionHook('onSessionClose', async (ctx) => {
+		for (const t of ctx.pluginContext.timers.values()) clearTimeout(t)
+		ctx.pluginContext.timers.clear()
+		ctx.pluginContext.triggerTick = null
+	})
+	.hook('afterInference', async (ctx) => {
+		// Natural inference warmed the cache — push the next tick out by intervalMs
+		// so we don't double-charge for parents who are already actively interacting.
+		if (ctx.pluginContext.intervalMs !== null) {
+			if (getDirectChildren(ctx.sessionState.agents, ctx.agentId).length > 0) {
+				scheduleSupervisionTick(ctx.pluginContext, ctx.agentId, ctx.pluginContext.intervalMs)
+			}
+		}
+		return null
+	})
+	.systemPrompt((ctx) => {
+		const base = `## Working with Child Agents
 
 - **New task** → spawn a new agent using \`start_<agent_name>\`. You will receive the agent's ID in the result — use it with \`send_message\` for follow-up communication.
 - **Follow-up on an existing task** → send a message to the existing agent via \`send_message\` with the agent's ID. Do NOT spawn a new agent for feedback, corrections, or additional instructions on a task already assigned.
 - Spawned agents communicate back to you via \`send_message\`. Check your incoming messages for their results and progress updates.`
+
+		// Only include supervision instructions if supervision is actually enabled
+		// for this session — otherwise the section is misleading bloat.
+		if (ctx.pluginContext.intervalMs === null) return base
+
+		return `${base}
+
+### Supervision messages
+
+You will periodically receive a \`<children-status>\` message from \`from="supervisor"\`. It is a status snapshot of your direct children — purely informational. Per child you'll see status, cumulative tool/llm call counts, sub-agent count, and a "first words..last words" preview of their last assistant turn.
+
+Do NOT act on a supervision tick unless something is genuinely wrong (a child has been errored or stuck for a long time, you have a deadline, etc.). Most of the time you should just wait. Never reply to the supervisor.`
 	})
 	.tools((ctx) => {
 		const spawnableAgents = ctx.agentConfig.spawnableAgents