@roj-ai/sdk 0.1.27 → 0.1.28

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

package/src/plugins/services/service.ts

@@ -13,7 +13,7 @@ import { Err, Ok } from '~/lib/utils/result.js'
 import type { FileSystem } from '~/platform/fs.js'
 import type { ChildProcess, ProcessRunner } from '~/platform/process.js'
 import type { PortPool } from '~/plugins/services/port-pool.js'
-import type { ServiceConfig, ServiceStatus } from '~/plugins/services/schema.js'
+import type { ServiceConfig, ServiceStartArgs, ServiceStatus } from '~/plugins/services/schema.js'
 import type { ToolError } from '../../core/tools/executor.js'
 import type { Logger } from '../../lib/logger/logger.js'
 import { RingBuffer } from '../../lib/logger/ring-buffer.js'
@@ -57,9 +57,20 @@ interface RunningService {
 	pid: number
 	status: ServiceStatus
 	port: number
+	cwd?: string
+	command: string
 	logs: RingBuffer
 }
 
+export interface ServiceStatusChangeDetails {
+	port?: number
+	error?: string
+	pid?: number
+	pidStartTime?: number
+	cwd?: string
+	command?: string
+}
+
 /** Matches a port bind-conflict across the Node and Bun runtimes. */
 const PORT_CONFLICT_PATTERN = /EADDRINUSE|address already in use/i
 
@@ -98,10 +109,7 @@ export class ServiceExecutor {
 		sessionId: string,
 		serviceType: string,
 		status: ServiceStatus,
-		port?: number,
-		error?: string,
-		pid?: number,
-		pidStartTime?: number,
+		details: ServiceStatusChangeDetails,
 	) => void
 
 	constructor(logger: Logger, portPool: PortPool, deps: ServiceExecutorDeps) {
@@ -115,14 +123,46 @@ export class ServiceExecutor {
 		sessionId: string,
 		serviceType: string,
 		status: ServiceStatus,
-		port?: number,
-		error?: string,
-		pid?: number,
-		pidStartTime?: number,
+		details: ServiceStatusChangeDetails = {},
 	): void {
-		this.onStatusChanged?.(sessionId, serviceType, status, port, error, pid, pidStartTime)
+		this.onStatusChanged?.(sessionId, serviceType, status, details)
 		if (status === 'ready' || status === 'failed' || status === 'stopped') {
-			this.resolveWaiters(serviceType, status, error)
+			this.resolveWaiters(serviceType, status, details.error)
+		}
+	}
+
+	private async isAvailable(config: ServiceConfig, sessionId: SessionId, workspaceDir?: string): Promise<Result<boolean, ToolError>> {
+		if (!config.availableWhen) return Ok(true)
+
+		try {
+			return Ok(await config.availableWhen({ sessionId: String(sessionId), workspaceDir }))
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error)
+			return Err({ message: `Service '${config.type}' availability check failed: ${message}`, recoverable: true })
+		}
+	}
+
+	private async resolveCwd(config: ServiceConfig, sessionId: SessionId, workspaceDir?: string): Promise<Result<string | undefined, ToolError>> {
+		try {
+			if (typeof config.cwd === 'function') {
+				if (!workspaceDir) {
+					return Err({
+						message: `Service '${config.type}' cwd resolver requires a workspaceDir`,
+						recoverable: true,
+					})
+				}
+				const raw = await config.cwd({ sessionId: String(sessionId), workspaceDir })
+				return Ok(resolve(workspaceDir, raw))
+			}
+
+			if (config.cwd !== undefined) {
+				return Ok(workspaceDir ? resolve(workspaceDir, config.cwd) : resolve(config.cwd))
+			}
+
+			return Ok(workspaceDir)
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error)
+			return Err({ message: `Service '${config.type}' cwd resolver failed: ${message}`, recoverable: true })
 		}
 	}
 
@@ -214,44 +254,74 @@ export class ServiceExecutor {
 			return Ok(undefined)
 		}
 
+		const availability = await this.isAvailable(config, sessionId, workspaceDir)
+		if (!availability.ok) return availability
+		if (!availability.value) {
+			return Err({ message: `Service '${config.type}' is not available in this workspace`, recoverable: true })
+		}
+
 		// Allocate port: reuse session-level allocation, then try preferred, then random
 		let port = this.allocatedPorts.get(config.type)
+		let allocatedNow = false
 		if (port === undefined) {
 			port = this.portPool.allocatePreferred(preferredPort) ?? undefined
 			if (port === undefined) {
-				this.notifyStatusChanged(sessionId, config.type, 'failed', undefined, 'No ports available in pool')
+				this.notifyStatusChanged(sessionId, config.type, 'failed', { error: 'No ports available in pool' })
 				return Err({ message: 'No ports available in pool', recoverable: true })
 			}
 			this.allocatedPorts.set(config.type, port)
+			allocatedNow = true
 		}
 
-		// Resolve cwd: a callback is invoked lazily at start (the workspace is
-		// populated by now), a string is used directly. Either result is resolved
-		// against the workspace dir so a relative path (e.g. 'packages/web' for a
-		// monorepo) lands inside this session's worktree; absolute paths pass through.
-		let cwd = workspaceDir
-		if (config.cwd !== undefined) {
-			const raw = typeof config.cwd === 'function'
-				? await config.cwd({ workspaceDir: workspaceDir ?? process.cwd() })
-				: config.cwd
-			cwd = workspaceDir ? resolve(workspaceDir, raw) : resolve(raw)
+		const cwdResult = await this.resolveCwd(config, sessionId, workspaceDir)
+		if (!cwdResult.ok) {
+			if (allocatedNow) {
+				this.allocatedPorts.delete(config.type)
+				this.portPool.release(port)
+			}
+			this.notifyStatusChanged(sessionId, config.type, 'failed', { port, error: cwdResult.error.message })
+			return cwdResult
 		}
+
+		const cwd = cwdResult.value
 		const logBufferSize = config.logBufferSize ?? 200
 		const startupTimeoutMs = config.startupTimeoutMs ?? 30_000
 
 		const readyRegex = config.readyPattern ? new RegExp(config.readyPattern) : undefined
 
-		// Resolve command: callback gets port, string used as-is
-		const command = typeof config.command === 'function'
-			? config.command({ port })
-			: config.command
+		const startArgs = {
+			port,
+			sessionId: String(sessionId),
+			workspaceDir,
+			cwd,
+		}
+
+		let command: string
+		let serviceEnv: Record<string, string> | undefined
+		try {
+			command = typeof config.command === 'function'
+				? await config.command(startArgs)
+				: config.command
+			serviceEnv = typeof config.env === 'function'
+				? await config.env(startArgs)
+				: config.env
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error)
+			const errorMessage = `Service '${config.type}' start resolver failed: ${message}`
+			if (allocatedNow) {
+				this.allocatedPorts.delete(config.type)
+				this.portPool.release(port)
+			}
+			this.notifyStatusChanged(sessionId, config.type, 'failed', { port, cwd, error: errorMessage })
+			return Err({ message: errorMessage, recoverable: true })
+		}
 
 		const shell = process.platform === 'win32' ? 'cmd.exe' : '/bin/sh'
 		const shellFlag = process.platform === 'win32' ? '/c' : '-c'
 
 		const child = this.processRunner.spawn(shell, [shellFlag, command], {
 			cwd,
-			env: { ...process.env, ...config.env, PORT: String(port) },
+			env: { ...process.env, ...serviceEnv, PORT: String(port) },
 			detached: true,
 			stdio: ['ignore', 'pipe', 'pipe'],
 		})
@@ -263,12 +333,20 @@ export class ServiceExecutor {
 			const current = this.services.get(config.type)
 			if (current && current.process === child && current.status !== 'stopped' && current.status !== 'failed') {
 				current.status = 'failed'
-				this.notifyStatusChanged(sessionId, config.type, 'failed', undefined, error.message)
+				this.notifyStatusChanged(sessionId, config.type, 'failed', {
+					error: error.message,
+					cwd,
+					command,
+				})
 			}
 		})
 
 		if (!child.pid) {
-			this.notifyStatusChanged(sessionId, config.type, 'failed', undefined, 'Failed to spawn process')
+			if (allocatedNow) {
+				this.allocatedPorts.delete(config.type)
+				this.portPool.release(port)
+			}
+			this.notifyStatusChanged(sessionId, config.type, 'failed', { port, cwd, command, error: 'Failed to spawn process' })
 			return Err({ message: 'Failed to spawn service process', recoverable: true })
 		}
 
@@ -276,8 +354,8 @@ export class ServiceExecutor {
 		// "our process" from "an unrelated process that grabbed this PID after ours died"
 		const pidStartTime = await getProcessStartTime(this.fs, child.pid)
 
-		// Emit starting event with PID, port (port is known at allocation time), and start time
-		this.notifyStatusChanged(sessionId, config.type, 'starting', port, undefined, child.pid, pidStartTime)
+		// Emit starting event with PID, port, resolved cwd/command, and start time.
+		this.notifyStatusChanged(sessionId, config.type, 'starting', { port, pid: child.pid, pidStartTime, cwd, command })
 
 		const logs = new RingBuffer(logBufferSize)
 		const startTime = Date.now()
@@ -291,10 +369,70 @@ export class ServiceExecutor {
 			pid: child.pid,
 			status: 'starting',
 			port,
+			cwd,
+			command,
 			logs,
 		}
 		this.services.set(config.type, entry)
 
+		let startupTimer: ReturnType<typeof setTimeout> | undefined
+		let readyCheckTimer: ReturnType<typeof setInterval> | undefined
+		let readyCheckInFlight = false
+
+		const clearReadinessTimers = () => {
+			if (startupTimer) {
+				clearTimeout(startupTimer)
+				startupTimer = undefined
+			}
+			if (readyCheckTimer) {
+				clearInterval(readyCheckTimer)
+				readyCheckTimer = undefined
+			}
+		}
+
+		const markReady = (matchedLine?: string) => {
+			const current = this.services.get(config.type)
+			if (!current || current.process !== child || current.status !== 'starting') return
+
+			current.status = 'ready'
+			clearReadinessTimers()
+			this.portConflictRetries.delete(config.type)
+			const startupDurationMs = Date.now() - startTime
+			this.notifyStatusChanged(sessionId, config.type, 'ready', {
+				port: current.port,
+				cwd: current.cwd,
+				command: current.command,
+			})
+			this.logger.info('Service ready', {
+				serviceType: config.type,
+				port: current.port,
+				startupDurationMs,
+				matchedLine,
+			})
+		}
+
+		const readyArgs = (): ServiceStartArgs => ({
+			...startArgs,
+			logs: logs.toArray(),
+		})
+
+		const checkReadyWhen = async () => {
+			if (!config.readyWhen || readyCheckInFlight) return
+			const current = this.services.get(config.type)
+			if (!current || current.process !== child || current.status !== 'starting') return
+
+			readyCheckInFlight = true
+			try {
+				if (await config.readyWhen(readyArgs())) {
+					markReady()
+				}
+			} catch {
+				// The service may not be reachable yet; keep polling until timeout.
+			} finally {
+				readyCheckInFlight = false
+			}
+		}
+
 		const processLine = (line: string) => {
 			logs.push(line)
 			if (PORT_CONFLICT_PATTERN.test(line)) {
@@ -307,27 +445,17 @@ export class ServiceExecutor {
 				this.logger.debug('Service output', { serviceType: config.type, line })
 			}
 
-			// Check for ready pattern
 			if (readyRegex && current.status === 'starting') {
 				if (readyRegex.test(line)) {
-					current.status = 'ready'
-					if (startupTimer) clearTimeout(startupTimer)
-					this.portConflictRetries.delete(config.type)
-					const startupDurationMs = Date.now() - startTime
-					this.notifyStatusChanged(sessionId, config.type, 'ready', current.port)
-					this.logger.info('Service ready', {
-						serviceType: config.type,
-						port: current.port,
-						startupDurationMs,
-						matchedLine: line,
-					})
+					markReady(line)
 				}
 			}
+
+			void checkReadyWhen()
 		}
 
 		// Startup timeout — mark as failed if not ready in time
-		let startupTimer: ReturnType<typeof setTimeout> | undefined
-		if (readyRegex) {
+		if (readyRegex || config.readyWhen) {
 			startupTimer = setTimeout(() => {
 				const current = this.services.get(config.type)
 				if (!current || current.process !== child || current.status !== 'starting') return
@@ -335,7 +463,13 @@ export class ServiceExecutor {
 				current.status = 'failed'
 				const errorMsg = `Service startup timed out after ${startupTimeoutMs}ms`
 				this.logger.error(errorMsg, undefined, { serviceType: config.type })
-				this.notifyStatusChanged(sessionId, config.type, 'failed', undefined, errorMsg)
+				clearReadinessTimers()
+				this.notifyStatusChanged(sessionId, config.type, 'failed', {
+					port: current.port,
+					cwd: current.cwd,
+					command: current.command,
+					error: errorMsg,
+				})
 
 				// Kill the timed-out process
 				try {
@@ -346,6 +480,14 @@ export class ServiceExecutor {
 			}, startupTimeoutMs)
 		}
 
+		if (config.readyWhen) {
+			const intervalMs = config.readyCheckIntervalMs ?? 250
+			readyCheckTimer = setInterval(() => {
+				void checkReadyWhen()
+			}, intervalMs)
+			void checkReadyWhen()
+		}
+
 		// Pipe stdout/stderr line by line
 		let stdoutPartial = ''
 		child.stdout?.on('data', (data: Buffer) => {
@@ -369,7 +511,7 @@ export class ServiceExecutor {
 
 		// Handle unexpected exit
 		child.on('close', (code) => {
-			if (startupTimer) clearTimeout(startupTimer)
+			clearReadinessTimers()
 			// Flush remaining partial lines
 			if (stdoutPartial) {
 				processLine(stdoutPartial)
@@ -413,7 +555,12 @@ export class ServiceExecutor {
 				// Unexpected exit
 				current.status = 'failed'
 				const errorMsg = `Process exited unexpectedly with code ${code}`
-				this.notifyStatusChanged(sessionId, config.type, 'failed', undefined, errorMsg)
+				this.notifyStatusChanged(sessionId, config.type, 'failed', {
+					port: current.port,
+					cwd: current.cwd,
+					command: current.command,
+					error: errorMsg,
+				})
 				this.logger.warn('Service process exited unexpectedly', {
 					serviceType: config.type,
 					code,
@@ -433,9 +580,8 @@ export class ServiceExecutor {
 		})
 
 		// If no ready pattern, immediately mark as ready
-		if (!readyRegex) {
-			entry.status = 'ready'
-			this.notifyStatusChanged(sessionId, config.type, 'ready', port)
+		if (!readyRegex && !config.readyWhen) {
+			markReady()
 		}
 
 		return Ok(undefined)
@@ -564,7 +710,11 @@ export class ServiceExecutor {
 		}
 
 		entry.status = 'ready'
-		this.notifyStatusChanged(sessionId, config.type, 'ready', entry.port)
+		this.notifyStatusChanged(sessionId, config.type, 'ready', {
+			port: entry.port,
+			cwd: entry.cwd,
+			command: entry.command,
+		})
 
 		this.logger.info('Service resumed', { serviceType: config.type })
 		return Ok(undefined)