@roj-ai/sdk 0.1.27 → 0.1.29

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 })
+					}
 				}
 			}
 		}
@@ -445,7 +468,10 @@ export const servicePlugin = definePlugin('services')
 					})
 					if (!result.ok) return Err({ message: result.error.message, recoverable: false })
 
-					return Ok(JSON.stringify(result.value))
+					// Strip cwd: a real host path, meaningless (and misleading) inside
+					// the agent's virtual-root namespace.
+					const { cwd: _cwd, ...agentSafe } = result.value
+					return Ok(JSON.stringify(agentSafe))
 				},
 			}),
 			createTool({

package/src/plugins/services/prompt.ts

@@ -42,6 +42,9 @@ export function buildServiceStatusMessage(
 		if (entry?.error) {
 			line += ` (error: ${entry.error})`
 		}
+		// Deliberately no cwd: it is a real host path, while sandboxed agents see the
+		// world through virtual roots — leaking it sends them chasing paths that
+		// don't exist in their namespace (see webmaster path-identity incident).
 
 		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) */
@@ -71,6 +103,14 @@ export interface ServiceConfig {
 	startupTimeoutMs?: number
 	/** Auto-pause configuration (interface prepared, not yet implemented) */
 	autoPause?: { inactivityMs: number }
+	/**
+	 * When false, the service is hidden from the owning agent: excluded from its
+	 * service_* tools and the session-context status block. It still runs at the
+	 * session level and stays fully controllable via the services.* methods —
+	 * for infrastructure services (e.g. a CMS sidecar) driven by the platform,
+	 * not by agents. Default: true.
+	 */
+	agentVisible?: boolean
 }
 
 // ============================================================================
@@ -86,6 +126,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