@roj-ai/sdk 0.1.36 → 0.2.1

package/src/plugins/agents/plugin.ts

@@ -15,11 +15,17 @@ import { AgentId, agentIdSchema, generateAgentId } from '~/core/agents/schema.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 type { SessionContext } from '~/core/sessions/context.js'
+import { pluginWakeKey } from '~/core/wake-key.js'
+import type { SessionState } from '~/core/sessions/state.js'
+import { agentSequenceKey, 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'
+import { getAgentUnconsumedMailbox, selectMailboxState } from '~/plugins/mailbox/query.js'
+
+const PLUGIN_NAME = 'agents'
+const SUPERVISION_TICK_METHOD = '_supervisionTick'
 
 /**
  * Information about a spawnable agent, used to generate typed start_<name> tools.
@@ -55,16 +61,6 @@ export interface AgentsPluginConfig {
  */
 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.
  */
@@ -76,6 +72,55 @@ function getDirectChildren(sessionAgents: Map<AgentId, AgentState>, parentId: Ag
 	return out
 }
 
+/**
+ * Input waiting in the agent's queue that the loop will dequeue on its next turn.
+ *
+ * Incomplete on purpose, for want of a seam: `Agent.decide()` asks every plugin with
+ * a `dequeue` hook (mailbox, user-chat, uploads) and nothing exposes that predicate
+ * at session level, so a child fed only through user-chat or uploads reads as idle
+ * here. See PR #18.
+ */
+function hasQueuedInput(sessionState: SessionState, agentId: AgentId): boolean {
+	return getAgentUnconsumedMailbox(selectMailboxState(sessionState), agentId).length > 0
+}
+
+/**
+ * Is this agent running, or holding input it will run?
+ *
+ * `paused` is the only status that never resumes on its own — everything else is
+ * decided by the queue, exactly as `Agent.decide()` decides it. In particular an
+ * `errored` agent is NOT idle: with its input still queued (a retryable failure
+ * preserves the dequeue token) `decide()` returns `resume_from_error` and the
+ * agent retries itself at the capped backoff.
+ */
+function isAgentWorking(sessionState: SessionState, agent: AgentState): boolean {
+	if (agent.status === 'paused') return false
+	if (agent.status === 'inferring' || agent.status === 'tool_exec') return true
+	// decide() resumes an errored agent only for queued input — stale
+	// pendingToolResults were already there when the inference failed.
+	if (agent.status === 'errored') return hasQueuedInput(sessionState, agent.id)
+	if (agent.pendingToolCalls.length > 0 || agent.pendingToolResults.length > 0) return true
+	return hasQueuedInput(sessionState, agent.id)
+}
+
+/**
+ * Is anything below this agent still working? Agents are never removed from
+ * session state, so "has children" stays true forever and cannot gate the tick.
+ * Walks the whole subtree — a child idling on its own children is still work.
+ */
+function hasWorkingDescendant(sessionState: SessionState, parentId: AgentId): boolean {
+	const queue = getDirectChildren(sessionState.agents, parentId)
+	const seen = new Set<AgentId>()
+	for (let i = 0; i < queue.length; i++) {
+		const agent = queue[i]
+		if (seen.has(agent.id)) continue
+		seen.add(agent.id)
+		if (isAgentWorking(sessionState, agent)) return true
+		queue.push(...getDirectChildren(sessionState.agents, agent.id))
+	}
+	return false
+}
+
 /**
  * Count assistant tool calls across conversation history + currently pending.
  */
@@ -143,31 +188,34 @@ function buildChildrenStatus(sessionAgents: Map<AgentId, AgentState>, parentId:
 	return `<children-status>\n${lines.join('\n')}\n</children-status>`
 }
 
+/** What arming a supervision wake needs, in every context that arms one. */
+type SupervisionScheduling = Pick<SessionContext, 'platform' | 'sessionId' | 'logger'>
+
+function supervisionWakeKey(ctx: SupervisionScheduling, agentId: AgentId): string {
+	return pluginWakeKey(ctx.sessionId, PLUGIN_NAME, SUPERVISION_TICK_METHOD, agentId)
+}
+
 /**
- * (Re)schedule a supervision tick for an agent. Any existing timer is cleared first.
+ * (Re)arm the supervision tick for an agent.
+ *
+ * The wake carries no closure — it comes back as `agents._supervisionTick` on a
+ * session loaded by id. `wake()` replaces any pending wake for the same key,
+ * which is also how a natural inference pushes the next tick out.
  */
-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)
+async function scheduleSupervisionTick(ctx: SupervisionScheduling, agentId: AgentId, delayMs: number): Promise<void> {
+	try {
+		await ctx.platform.scheduler.wake(supervisionWakeKey(ctx, agentId), delayMs)
+	} catch (err) {
+		ctx.logger.error('Failed to arm supervision wake', err instanceof Error ? err : undefined, { agentId })
+	}
+}
 
-	pluginContext.timers.set(agentId, timer)
+async function cancelSupervisionTick(ctx: SupervisionScheduling, agentId: AgentId): Promise<void> {
+	try {
+		await ctx.platform.scheduler.cancel(supervisionWakeKey(ctx, agentId))
+	} catch (err) {
+		ctx.logger.error('Failed to cancel supervision wake', err instanceof Error ? err : undefined, { agentId })
+	}
 }
 
 /**
@@ -186,15 +234,10 @@ function createStartAgentSchema(agent: SpawnableAgentInfo) {
 	})
 }
 
-export const agentsPlugin = definePlugin('agents')
+export const agentsPlugin = definePlugin(PLUGIN_NAME)
+	.order(40)
 	.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
 	})
@@ -222,7 +265,11 @@ export const agentsPlugin = definePlugin('agents')
 			}
 
 			// Generate agent ID and emit spawn event
-			const agentId = generateAgentId(input.definitionName, getNextAgentSeq(ctx.sessionState, input.definitionName))
+			const seq = ctx.reserveSequence(
+				agentSequenceKey(input.definitionName),
+				() => getNextAgentSeq(ctx.getSessionState(), input.definitionName),
+			)
+			const agentId = generateAgentId(input.definitionName, seq)
 			await ctx.emitEvent(agentEvents.create('agent_spawned', {
 				agentId,
 				definitionName: input.definitionName,
@@ -247,8 +294,9 @@ export const agentsPlugin = definePlugin('agents')
 			})
 
 			// 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)
+			const intervalMs = ctx.pluginConfig.superviseChildrenIntervalMs
+			if (intervalMs !== undefined) {
+				await scheduleSupervisionTick(ctx, parentId, intervalMs)
 			}
 
 			return Ok({ agentId })
@@ -339,14 +387,15 @@ export const agentsPlugin = definePlugin('agents')
 			return Ok({})
 		},
 	})
-	.method('_supervisionTick', {
+	.method(SUPERVISION_TICK_METHOD, {
 		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 agent = ctx.sessionState.agents.get(agentId)
+			if (!agent) return Ok({})
 
 			const children = getDirectChildren(ctx.sessionState.agents, agentId)
 			if (children.length === 0) {
@@ -354,63 +403,67 @@ export const agentsPlugin = definePlugin('agents')
 				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,
+			// A paused parent cannot consume a snapshot — sending anyway piles one
+			// un-consumable message per interval into its mailbox until it resumes.
+			if (agent.status !== 'paused') {
+				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)
+			// Reschedule the next tick from now (rolling), but only while something
+			// below is still working — otherwise the tick would re-arm forever.
+			// Read live state: the send above appended an event and dispatched
+			// listeners, so ctx.sessionState is already behind by the time we decide.
+			const intervalMs = ctx.pluginConfig.superviseChildrenIntervalMs
+			if (intervalMs !== undefined && hasWorkingDescendant(ctx.getSessionState(), agentId)) {
+				await scheduleSupervisionTick(ctx, agentId, intervalMs)
 			}
 
 			return Ok({})
 		},
 	})
 	.sessionHook('onSessionReady', async (ctx) => {
+		// Supervision is disabled by default; spawn() and afterInference() read the
+		// same config and skip too.
 		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 })
+		if (intervalMs === undefined) return
 
-		// (Re-)schedule timers for every agent that currently has direct children.
+		// (Re-)arm a wake 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.
+		// Not gated on live status: a reload resets 'inferring' back to 'pending',
+		// so the first tick — not this hook — decides whether to keep going.
 		for (const agent of ctx.sessionState.agents.values()) {
 			if (getDirectChildren(ctx.sessionState.agents, agent.id).length > 0) {
-				scheduleSupervisionTick(ctx.pluginContext, agent.id, intervalMs)
+				await scheduleSupervisionTick(ctx, 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
+		if (ctx.pluginConfig.superviseChildrenIntervalMs === undefined) return
+
+		// Eviction runs this too, and onSessionReady re-arms on the next load —
+		// so a parked session ticks no more often than a resident one.
+		for (const agent of ctx.sessionState.agents.values()) {
+			await cancelSupervisionTick(ctx, agent.id)
+		}
 	})
 	.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)
-			}
+		const intervalMs = ctx.pluginConfig.superviseChildrenIntervalMs
+		if (intervalMs !== undefined && hasWorkingDescendant(ctx.sessionState, ctx.agentId)) {
+			await scheduleSupervisionTick(ctx, ctx.agentId, intervalMs)
 		}
 		return null
 	})
@@ -424,7 +477,7 @@ export const agentsPlugin = definePlugin('agents')
 
 		// 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
+		if (ctx.pluginConfig.superviseChildrenIntervalMs === undefined) return base
 
 		return `${base}
 

package/src/plugins/filesystem/listing.ts

@@ -5,7 +5,8 @@
  */
 
 import { extname, join, resolve } from 'node:path'
-import type { FileSystem } from '~/platform/fs.js'
+import { containmentOf } from '~/core/file-store/containment.js'
+import type { FileSystem, WalkEntry } from '~/platform/fs.js'
 
 // ============================================================================
 // Constants
@@ -145,6 +146,9 @@ export function getMimeType(filePath: string): string {
 
 /**
  * Prevent path traversal — returns resolved path if safe, null otherwise.
+ *
+ * Lexical only. Callers that then touch the filesystem must also check the real
+ * target with `containmentOf`.
  */
 export function preventTraversal(baseDir: string, requestedPath: string): string | null {
 	const resolved = resolve(baseDir, requestedPath)
@@ -154,16 +158,61 @@ export function preventTraversal(baseDir: string, requestedPath: string): string
 	return resolved
 }
 
+/** Path under `baseDir`, with the separator dropped. */
+function relativeUnder(path: string, baseDir: string): string {
+	return path.slice(baseDir.endsWith('/') ? baseDir.length : baseDir.length + 1)
+}
+
+/** A walked entry as this plugin reports it; `relativeTo` adds the `path` the recursive listing carries. */
+function toDirectoryEntry(entry: WalkEntry, relativeTo?: string): DirectoryEntry {
+	const name = entry.path.slice(entry.path.lastIndexOf('/') + 1)
+	const isDir = entry.type === 'directory'
+	const out: DirectoryEntry = {
+		name,
+		...(relativeTo === undefined ? {} : { path: relativeUnder(entry.path, relativeTo) }),
+		type: isDir ? 'directory' : 'file',
+		size: isDir ? 0 : entry.size,
+	}
+	if (!isDir) out.mimeType = getMimeType(name)
+	return out
+}
+
+/** Directories first, then alphabetical — applied to whichever path produced the entries. */
+function sortEntries(entries: DirectoryEntry[]): DirectoryEntry[] {
+	entries.sort((a, b) => {
+		if (a.type !== b.type) return a.type === 'directory' ? -1 : 1
+		return a.name.localeCompare(b.name)
+	})
+	return entries
+}
+
 /**
  * List a single directory level, returning sorted DirectoryEntry[].
  * Directories first, then alphabetical within each group.
  */
 export async function listDirectory(fs: FileSystem, baseDir: string, subPath: string): Promise<DirectoryEntry[]> {
 	const targetDir = subPath ? preventTraversal(baseDir, subPath) : baseDir
-	if (!targetDir) {
+	if (!targetDir || (await containmentOf(fs, [baseDir], targetDir)) !== 'inside') {
 		throw new ListingError('forbidden', 'Path traversal not allowed')
 	}
 
+	if (fs.walk) {
+		let found: WalkEntry[]
+		try {
+			found = await fs.walk(targetDir, { depth: 1, excludeHidden: true })
+		} catch {
+			throw new ListingError('not_found', 'Directory not found')
+		}
+		return sortEntries(found.map((entry) => toDirectoryEntry(entry)))
+	}
+
+	// The readdir and a stat per entry are one question asked in pieces, so let a
+	// platform that can share those reads see them as one.
+	const read = (): Promise<DirectoryEntry[]> => readLevel(fs, targetDir)
+	return fs.scopeReads ? fs.scopeReads(read) : read()
+}
+
+async function readLevel(fs: FileSystem, targetDir: string): Promise<DirectoryEntry[]> {
 	let dirents: import('node:fs').Dirent[]
 	try {
 		dirents = await fs.readdir(targetDir, { withFileTypes: true })
@@ -199,13 +248,7 @@ export async function listDirectory(fs: FileSystem, baseDir: string, subPath: st
 		entries.push(entry)
 	}
 
-	// Sort: directories first, then alphabetical
-	entries.sort((a, b) => {
-		if (a.type !== b.type) return a.type === 'directory' ? -1 : 1
-		return a.name.localeCompare(b.name)
-	})
-
-	return entries
+	return sortEntries(entries)
 }
 
 /**
@@ -213,9 +256,19 @@ export async function listDirectory(fs: FileSystem, baseDir: string, subPath: st
  * Skips hidden files and IGNORED_DIRS.
  */
 export async function listDirectoryRecursive(fs: FileSystem, baseDir: string): Promise<DirectoryEntry[]> {
+	if (fs.walk) {
+		try {
+			const found = await fs.walk(baseDir, { exclude: [...IGNORED_DIRS], excludeHidden: true })
+			return found.map((entry) => toDirectoryEntry(entry, baseDir))
+		} catch {
+			// The loop below answers an unreadable directory with an empty listing, not a throw.
+			return []
+		}
+	}
+
 	const entries: DirectoryEntry[] = []
 
-	async function walk(dir: string, prefix: string) {
+	async function walk(dir: string, prefix: string): Promise<void> {
 		let dirents: import('node:fs').Dirent[]
 		try {
 			dirents = await fs.readdir(dir, { withFileTypes: true })
@@ -258,8 +311,13 @@ export async function listDirectoryRecursive(fs: FileSystem, baseDir: string): P
 		}
 	}
 
-	await walk(baseDir, '')
-	return entries
+	// Every stat here follows a readdir the level above already read past, so a
+	// platform that can share those reads should be given the chance to.
+	const run = async (): Promise<DirectoryEntry[]> => {
+		await walk(baseDir, '')
+		return entries
+	}
+	return fs.scopeReads ? fs.scopeReads(run) : run()
 }
 
 // ============================================================================

package/src/plugins/filesystem/plugin.ts

@@ -2,6 +2,7 @@ import { join, relative, resolve } from 'node:path'
 import z from 'zod/v4'
 import { agentEvents } from '~/core/agents/state.js'
 import { ValidationErrors } from '~/core/errors.js'
+import { containmentOf } from '~/core/file-store/containment.js'
 import type { FileEntry } from '~/core/file-store/types.js'
 import type { ToolResultContent } from '~/core/llm/llm-log-types.js'
 import { truncateByTokens } from '~/core/llm/tokens.js'
@@ -110,6 +111,7 @@ const replaceInFileInputSchema = z.object({
 // ============================================================================
 
 export const filesystemPlugin = definePlugin('filesystem')
+	.order(110)
 	.pluginConfig<FilesystemPresetConfig>()
 	.context(async () => {
 		return {} // No plugin-specific context needed
@@ -160,11 +162,11 @@ export const filesystemPlugin = definePlugin('filesystem')
 
 					// 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.
+					// the URL survives into conversationHistory and is re-resolved via
+					// fileStore.containedPath() on every later inference — which checks
+					// containment again, because what the path names can change in
+					// between. A resolved disk path would be rejected there when
+					// sandboxed, surfacing as "[Image unavailable: …]" on every turn.
 					const mimeType = getImageMimeType(input.path)
 					if (mimeType) {
 						return Ok([
@@ -439,7 +441,7 @@ export const filesystemPlugin = definePlugin('filesystem')
 			try {
 				if (input.recursive) {
 					const targetDir = subPath ? preventTraversal(resolvedWorkspace, subPath) : resolvedWorkspace
-					if (!targetDir) {
+					if (!targetDir || (await containmentOf(ctx.platform.fs, [resolvedWorkspace], targetDir)) !== 'inside') {
 						return Err(ValidationErrors.invalid('Path traversal not allowed'))
 					}
 					const entries = await listDirectoryRecursive(ctx.platform.fs, targetDir)