@roj-ai/sdk 0.1.26 → 0.1.28

package/src/plugins/resources/plugin.ts

@@ -1,4 +1,4 @@
-import { join, relative } from 'node:path'
+import { join, relative, resolve } from 'node:path'
 import z from 'zod/v4'
 import { definePlugin } from '~/core/plugins/plugin-builder.js'
 import { Ok } from '~/lib/utils/result.js'
@@ -15,8 +15,16 @@ import { type InjectedResource, resourceEvents, type ResourcesState } from './st
 
 const MAX_LISTED_PATHS = 100
 
+export interface ResourcesTargetDirArgs {
+	sessionId: string
+	sessionDir: string
+	workspaceDir?: string
+}
+
+export type ResourcesTargetDir = string | ((args: ResourcesTargetDirArgs) => string | Promise<string>)
+
 export interface ResourcesPluginConfig {
-	targetDir?: string
+	targetDir?: ResourcesTargetDir
 	/**
 	 * Called after a resource is written/extracted into `targetDir`, before the
 	 * `resource_injected` event is emitted. Use `postInjectRules` for a declarative
@@ -61,6 +69,16 @@ async function listFiles(fs: FileSystem, dir: string, maxEntries: number): Promi
 	return results
 }
 
+async function resolveTargetDir(targetDir: ResourcesTargetDir | undefined, args: ResourcesTargetDirArgs): Promise<string> {
+	const baseDir = args.workspaceDir ?? args.sessionDir
+	if (targetDir === undefined) return baseDir
+
+	const raw = typeof targetDir === 'function'
+		? await targetDir(args)
+		: targetDir
+	return resolve(baseDir, raw)
+}
+
 export const resourcesPlugin = definePlugin('resources')
 	.pluginConfig<ResourcesPluginConfig>()
 	.events([resourceEvents])
@@ -76,6 +94,7 @@ export const resourcesPlugin = definePlugin('resources')
 					filename: event.filename,
 					mimeType: event.mimeType,
 					paths: event.paths,
+					targetDir: event.targetDir,
 					injectedAt: event.injectedAt,
 				}
 				return { resources: [...state.resources, resource] }
@@ -102,7 +121,12 @@ export const resourcesPlugin = definePlugin('resources')
 		handler: async (ctx, input) => {
 			const fs = ctx.platform.fs
 			const exec = makeExec(ctx.platform.process)
-			const targetDir = ctx.pluginConfig?.targetDir ?? ctx.environment.workspaceDir ?? ctx.environment.sessionDir
+			const targetDir = await resolveTargetDir(ctx.pluginConfig?.targetDir, {
+				sessionId: String(ctx.sessionId),
+				sessionDir: ctx.environment.sessionDir,
+				workspaceDir: ctx.environment.workspaceDir,
+			})
+			await fs.mkdir(targetDir, { recursive: true })
 			const resourceId = crypto.randomUUID()
 			let paths: string[]
 
@@ -183,6 +207,7 @@ export const resourcesPlugin = definePlugin('resources')
 				filename: input.filename,
 				mimeType: input.mimeType,
 				paths,
+				targetDir,
 				injectedAt: Date.now(),
 			}))
 
@@ -193,12 +218,16 @@ export const resourcesPlugin = definePlugin('resources')
 		const { resources } = ctx.pluginState
 		if (resources.length === 0) return null
 
-		const targetDir = ctx.pluginConfig?.targetDir ?? ctx.environment.workspaceDir ?? ctx.environment.sessionDir
 		const lines = resources.map(r => {
 			const label = r.name ?? r.slug ?? r.filename
-			return `- **${label}** (${r.filename}): ${r.paths.length} files`
+			const target = r.targetDir ? ` in \`${r.targetDir}\`` : ''
+			return `- **${label}** (${r.filename}): ${r.paths.length} files${target}`
 		})
+		const targetDirs = [...new Set(resources.flatMap((r) => r.targetDir ? [r.targetDir] : []))]
+		const targetSummary = targetDirs.length === 1
+			? `\`${targetDirs[0]}\``
+			: targetDirs.length > 1 ? 'multiple target directories' : 'the configured target directory'
 
-		return `## Injected Resources\n\nThe following resources have been extracted into your workspace (\`${targetDir}\`):\n${lines.join('\n')}\n\nThese files are ready to use. Explore them with the filesystem tools.`
+		return `## Injected Resources\n\nThe following resources have been extracted into your workspace (${targetSummary}):\n${lines.join('\n')}\n\nThese files are ready to use. Explore them with the filesystem tools.`
 	})
 	.build()

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

@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, it } from 'bun:test'
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { MockLLMProvider } from '~/core/llm/mock.js'
+import { createTestPreset, TestHarness } from '~/testing/index.js'
+import { resourcesPlugin } from './plugin.js'
+import { resourceEvents, type ResourcesState } from './state.js'
+
+let currentHarness: TestHarness | undefined
+
+afterEach(async () => {
+	if (currentHarness) {
+		await currentHarness.shutdown()
+		currentHarness = undefined
+	}
+})
+
+describe('resources plugin', () => {
+	it('resolves targetDir callback relative to workspace and records it in state', async () => {
+		const workspaceDir = await mkdtemp(join(tmpdir(), 'roj-resources-'))
+		const targetDir = join(workspaceDir, 'packages', 'web')
+
+		try {
+			const harness = new TestHarness({
+				presets: [
+					createTestPreset({
+						workspaceDir,
+						plugins: [
+							resourcesPlugin.configure({
+								targetDir: ({ sessionId, workspaceDir: resolvedWorkspaceDir }) => {
+									expect(sessionId.length).toBeGreaterThan(0)
+									expect(resolvedWorkspaceDir).toBe(workspaceDir)
+									return 'packages/web'
+								},
+							}),
+						],
+					}),
+				],
+				llmProvider: MockLLMProvider.withFixedResponse({ content: 'Ok', toolCalls: [] }),
+			})
+			currentHarness = harness
+
+			const session = await harness.createSession('test')
+			const result = await session.callPluginMethod('resources.inject', {
+				sessionId: String(session.sessionId),
+				filename: 'hello.txt',
+				mimeType: 'text/plain',
+				size: 5,
+				fileBuffer: Buffer.from('hello'),
+			})
+
+			expect(result).toMatchObject({
+				ok: true,
+				value: { paths: ['hello.txt'] },
+			})
+			await expect(readFile(join(targetDir, 'hello.txt'), 'utf-8')).resolves.toBe('hello')
+
+			const resources = session.getPluginState<ResourcesState>('resources')
+			expect(resources?.resources[0]?.targetDir).toBe(targetDir)
+
+			const events = await session.getEventsByType(resourceEvents, 'resource_injected')
+			expect(events[0]?.targetDir).toBe(targetDir)
+		} finally {
+			await rm(workspaceDir, { recursive: true, force: true })
+		}
+	})
+})

package/src/plugins/resources/state.ts

@@ -10,6 +10,7 @@ export const resourceEvents = createEventsFactory({
 			filename: z4.string(),
 			mimeType: z4.string(),
 			paths: z4.array(z4.string()),
+			targetDir: z4.string().optional(),
 			injectedAt: z4.number(),
 		}),
 	},
@@ -22,6 +23,7 @@ export interface InjectedResource {
 	filename: string
 	mimeType: string
 	paths: string[]
+	targetDir?: string
 	injectedAt: number
 }
 

package/src/plugins/services/plugin.ts

@@ -17,6 +17,8 @@ export const serviceEvents = createEventsFactory({
 			toStatus: z.enum(['stopped', 'starting', 'ready', 'stopping', 'failed', 'paused']),
 			port: z.number().optional(),
 			error: z.string().optional(),
+			cwd: z.string().optional(),
+			command: z.string().optional(),
 			pid: z.number().optional(),
 			pidStartTime: z.number().optional(),
 		}),
@@ -58,6 +60,8 @@ export const servicePlugin = definePlugin('services')
 							serviceType: event.serviceType,
 							status: event.toStatus,
 							port: event.port,
+							cwd: event.cwd,
+							command: event.command,
 							startedAt: event.timestamp,
 							pid: event.pid,
 							pidStartTime: event.pidStartTime,
@@ -71,6 +75,8 @@ export const servicePlugin = definePlugin('services')
 							updated.startedAt = event.timestamp
 							updated.error = undefined
 							updated.port = event.port
+							updated.cwd = event.cwd
+							updated.command = event.command
 							updated.pid = event.pid
 							updated.pidStartTime = event.pidStartTime
 						}
@@ -79,6 +85,12 @@ export const servicePlugin = definePlugin('services')
 							if (event.port !== undefined) {
 								updated.port = event.port
 							}
+							if (event.cwd !== undefined) {
+								updated.cwd = event.cwd
+							}
+							if (event.command !== undefined) {
+								updated.command = event.command
+							}
 						}
 						if (event.toStatus === 'failed' && event.error) {
 							updated.error = event.error
@@ -122,17 +134,19 @@ export const servicePlugin = definePlugin('services')
 	})
 	.context(async (ctx, pluginConfig) => {
 		const executor = new ServiceExecutor(ctx.logger, pluginConfig.portPool, { fs: ctx.platform.fs, process: ctx.platform.process })
-		executor.onStatusChanged = (sessionId, serviceType, status, port, error, pid, pidStartTime) => {
+		executor.onStatusChanged = (sessionId, serviceType, status, details) => {
 			void ctx.emitEvent(serviceEvents.create('service_status_changed', {
 				serviceType,
 				toStatus: status,
-				port,
-				error,
-				pid,
-				pidStartTime,
+				port: details.port,
+				error: details.error,
+				cwd: details.cwd,
+				command: details.command,
+				pid: details.pid,
+				pidStartTime: details.pidStartTime,
 			}))
 			// Broadcast service status to connected clients (DO → SPA) via WS
-			ctx.notify('serviceStatus', { sessionId: String(sessionId), serviceType, status, port })
+			ctx.notify('serviceStatus', { sessionId: String(sessionId), serviceType, status, port: details.port })
 		}
 		return { executor }
 	})
@@ -160,7 +174,8 @@ export const servicePlugin = definePlugin('services')
 				}
 
 				const preferredPort = ctx.pluginState.get(input.serviceType)?.port
-				await ctx.pluginContext.executor.start(svcConfig, ctx.sessionId, ctx.sessionState.workspaceDir, preferredPort)
+				const startResult = await ctx.pluginContext.executor.start(svcConfig, ctx.sessionId, ctx.sessionState.workspaceDir, preferredPort)
+				if (!startResult.ok) return Err(ValidationErrors.invalid(startResult.error.message))
 				started.push(input.serviceType)
 			} else {
 				for (const svcConfig of ctx.pluginConfig.services) {
@@ -174,7 +189,8 @@ export const servicePlugin = definePlugin('services')
 							}
 						} else {
 							const preferredPort = ctx.pluginState.get(svcConfig.type)?.port
-							await ctx.pluginContext.executor.start(svcConfig, ctx.sessionId, ctx.sessionState.workspaceDir, preferredPort)
+							const startResult = await ctx.pluginContext.executor.start(svcConfig, ctx.sessionId, ctx.sessionState.workspaceDir, preferredPort)
+							if (!startResult.ok) return Err(ValidationErrors.invalid(startResult.error.message))
 							started.push(svcConfig.type)
 						}
 					}
@@ -250,6 +266,8 @@ export const servicePlugin = definePlugin('services')
 			serviceType: z.string(),
 			status: z.string(),
 			port: z.number().optional(),
+			cwd: z.string().optional(),
+			command: z.string().optional(),
 			error: z.string().optional(),
 			recentLogs: z.array(z.string()),
 		}),
@@ -262,6 +280,8 @@ export const servicePlugin = definePlugin('services')
 				serviceType: input.serviceType,
 				status: status ?? 'stopped',
 				port: stateEntry?.port,
+				cwd: stateEntry?.cwd,
+				command: stateEntry?.command,
 				error: stateEntry?.error,
 				recentLogs: logsResult.ok ? logsResult.value : [],
 			})
@@ -340,7 +360,10 @@ export const servicePlugin = definePlugin('services')
 				const status = ctx.pluginContext.executor.getStatus(svcConfig.type)
 				if (status !== 'ready' && status !== 'starting') {
 					const preferredPort = ctx.pluginState.get(svcConfig.type)?.port
-					await ctx.pluginContext.executor.start(svcConfig, ctx.sessionId, ctx.sessionState.workspaceDir, preferredPort)
+					const startResult = await ctx.pluginContext.executor.start(svcConfig, ctx.sessionId, ctx.sessionState.workspaceDir, preferredPort)
+					if (!startResult.ok) {
+						ctx.logger.debug('Auto-start service skipped', { serviceType: svcConfig.type, error: startResult.error.message })
+					}
 				}
 			}
 		}

package/src/plugins/services/prompt.ts

@@ -42,6 +42,9 @@ export function buildServiceStatusMessage(
 		if (entry?.error) {
 			line += ` (error: ${entry.error})`
 		}
+		if (entry?.cwd) {
+			line += ` (cwd: ${entry.cwd})`
+		}
 
 		lines.push(line)
 	}

package/src/plugins/services/schema.ts

@@ -24,6 +24,12 @@ export type ServiceStatus = 'stopped' | 'starting' | 'ready' | 'stopping' | 'fai
  */
 export interface ServiceCommandArgs {
 	port: number
+	/** Session id of the service owner. */
+	sessionId: string
+	/** Absolute path of the session workspace directory, when configured. */
+	workspaceDir?: string
+	/** Resolved working directory that will be passed to the child process. */
+	cwd?: string
 }
 
 /**
@@ -32,10 +38,30 @@ export interface ServiceCommandArgs {
  * to locate the web app inside a monorepo before launching the dev server.
  */
 export interface ServiceCwdArgs {
+	/** Session id of the service owner. */
+	sessionId: string
 	/** Absolute path of the session workspace directory. */
 	workspaceDir: string
 }
 
+/**
+ * Arguments passed to service environment and readiness callbacks.
+ */
+export interface ServiceStartArgs extends ServiceCommandArgs {
+	/** Recently captured service output lines. Empty before the process writes. */
+	logs: readonly string[]
+}
+
+/**
+ * Arguments passed to `availableWhen` before a service is started.
+ */
+export interface ServiceAvailabilityArgs {
+	/** Session id of the service owner. */
+	sessionId: string
+	/** Absolute path of the session workspace directory, when configured. */
+	workspaceDir?: string
+}
+
 /**
  * Service configuration declared inline in presets.
  * Defines how to spawn and monitor a background process.
@@ -45,8 +71,8 @@ export interface ServiceConfig {
 	type: string
 	/** Human-readable description */
 	description: string
-	/** Shell command to run, or a callback receiving allocated port */
-	command: string | ((args: ServiceCommandArgs) => string)
+	/** Shell command to run, or a callback receiving runtime start context */
+	command: string | ((args: ServiceCommandArgs) => string | Promise<string>)
 	/**
 	 * Working directory (defaults to the workspace dir).
 	 *
@@ -57,12 +83,18 @@ export interface ServiceConfig {
 	 * resolved the same way.
 	 */
 	cwd?: string | ((args: ServiceCwdArgs) => string | Promise<string>)
-	/** Additional environment variables */
-	env?: Record<string, string>
+	/** Additional environment variables, resolved after cwd and before spawn */
+	env?: Record<string, string> | ((args: ServiceCommandArgs) => Record<string, string> | Promise<Record<string, string>>)
+	/** Return false to make start/autoStart skip this service for the current workspace. */
+	availableWhen?: (args: ServiceAvailabilityArgs) => boolean | Promise<boolean>
 	/** Start automatically with session (default: false) */
 	autoStart?: boolean
 	/** Regex pattern to detect "ready" in stdout */
 	readyPattern?: string
+	/** Callback polled until it reports that the service is ready. */
+	readyWhen?: (args: ServiceStartArgs) => boolean | Promise<boolean>
+	/** Poll interval for readyWhen in ms (default: 250) */
+	readyCheckIntervalMs?: number
 	/** SIGTERM→SIGKILL timeout in ms (default: 5000) */
 	gracefulStopMs?: number
 	/** Ring buffer size for log lines (default: 200) */
@@ -86,6 +118,10 @@ export interface ServiceEntry {
 	status: ServiceStatus
 	port?: number
 	error?: string
+	/** Resolved working directory used for the current/last start. */
+	cwd?: string
+	/** Resolved command used for the current/last start. */
+	command?: string
 	startedAt?: number
 	readyAt?: number
 	stoppedAt?: number