@roj-ai/sdk 0.2.8 → 0.2.9

package/src/platform/shell.ts

@@ -37,6 +37,7 @@ export interface ShellRunOptions {
 	cwd: string
 	env?: Record<string, string>
 	stdin?: string
+	/** Wall-clock deadline; ignored when `supportsTimeout` is false. */
 	timeoutMs: number
 	/**
 	 * What the command may reach. Meaningful only under `paths` confinement, and
@@ -78,6 +79,8 @@ export interface ShellRunResult {
 export interface ShellRunner {
 	/** Declared, not assumed: a caller that needs confinement checks it before running. */
 	readonly confinement: ShellConfinement
+	/** Whether `timeoutMs` terminates the run before it resolves with `timedOut: true`. Omitted means true for legacy runners. */
+	readonly supportsTimeout?: boolean
 
 	/**
 	 * Run one command line to completion and buffer its output.

package/src/plugins/services/plugin.ts

@@ -201,11 +201,13 @@ export const servicePlugin = definePlugin('services')
 		const statusEffects = new Set<Promise<void>>()
 		let statusEffectTail = Promise.resolve()
 		let publicationEnabled = true
-		const executor = new ServiceExecutor(logger, pluginConfig.portPool, {
-			fs: ctx.platform.fs,
-			process: ctx.platform.process,
-			pidRegistry: pluginConfig.pidRegistry,
-		})
+		const executor =
+			ctx.platform.createServiceExecutor?.(logger, pluginConfig.portPool) ??
+			new ServiceExecutor(logger, pluginConfig.portPool, {
+				fs: ctx.platform.fs,
+				process: ctx.platform.process,
+				pidRegistry: pluginConfig.pidRegistry,
+			})
 		const beginLifecycle = (serviceType: string): ServiceLease | undefined => {
 			const existing = serviceLeases.get(serviceType)
 			if (existing && !existing.terminalPending) return existing

package/src/plugins/services/service.ts

@@ -149,6 +149,22 @@ export interface ServiceExecutorDeps {
 	hookTimeoutMs?: number
 }
 
+/** Lifecycle used by the services plugin, independently of how a host runs it. */
+export type ServiceExecutorPort = Pick<
+	ServiceExecutor,
+	| 'onStatusChanged'
+	| 'onStartSettled'
+	| 'start'
+	| 'stop'
+	| 'restart'
+	| 'close'
+	| 'getStatus'
+	| 'getLogs'
+	| 'waitForReady'
+	| 'hasScheduledRestart'
+	| 'reapProcessGroup'
+>
+
 type ProcessGroupProbe = { state: 'alive' | 'gone' } | { state: 'error'; error: Error }
 
 let serviceExecutorObserverForTesting: ((executor: ServiceExecutor) => void) | undefined

package/src/plugins/shell/executor.ts

@@ -92,9 +92,7 @@ async function resolveAgentPath(
 			}
 			return Ok(absolutePath)
 		}
-		const validPrefixes = workspaceDir
-			? `${VIRTUAL_SESSION}/ or ${VIRTUAL_WORKSPACE}/`
-			: `${VIRTUAL_SESSION}/`
+		const validPrefixes = workspaceDir ? `${VIRTUAL_SESSION}/ or ${VIRTUAL_WORKSPACE}/` : `${VIRTUAL_SESSION}/`
 		return Err({ message: `Path must start with ${validPrefixes}. Got: '${agentPath}'`, recoverable: false })
 	}
 	// Non-sandboxed: validate within allowed dirs
@@ -102,8 +100,7 @@ async function resolveAgentPath(
 	const normalizedSession = resolve(sessionDir)
 	const normalizedWorkspace = workspaceDir ? resolve(workspaceDir) : null
 	const isInSession = absolutePath === normalizedSession || absolutePath.startsWith(normalizedSession + '/')
-	const isInWorkspace = normalizedWorkspace
-		&& (absolutePath === normalizedWorkspace || absolutePath.startsWith(normalizedWorkspace + '/'))
+	const isInWorkspace = normalizedWorkspace && (absolutePath === normalizedWorkspace || absolutePath.startsWith(normalizedWorkspace + '/'))
 	if (!isInSession && !isInWorkspace) {
 		return Err({ message: `Path '${agentPath}' is outside allowed directories`, recoverable: false })
 	}
@@ -174,6 +171,7 @@ export interface ShellResult {
 	exitCode: number
 	signal?: string
 	timedOut: boolean
+	truncated?: boolean
 	durationMs: number
 }
 
@@ -187,19 +185,17 @@ export class ShellExecutor {
 	private readonly fs: FileSystem
 	private readonly shell?: ShellRunner
 
-	constructor(private config: ShellConfig, deps: ShellExecutorDeps) {
+	constructor(
+		private config: ShellConfig,
+		deps: ShellExecutorDeps,
+	) {
 		this.fs = deps.fs
 		this.shell = deps.shell
 	}
 
-	async execute(
-		input: RunCommandInput,
-		environment: SessionEnvironment,
-	): Promise<Result<ShellResult, ToolError>> {
+	async execute(input: RunCommandInput, environment: SessionEnvironment): Promise<Result<ShellResult, ToolError>> {
 		const args = typeof input.args === 'string' ? [input.args] : input.args
-		const fullCommand = args
-			? `${shellEscape(input.command)} ${args.map(shellEscape).join(' ')}`
-			: input.command
+		const fullCommand = args ? `${shellEscape(input.command)} ${args.map(shellEscape).join(' ')}` : input.command
 
 		const timeout = input.timeout ?? this.config.timeout ?? 30000
 		const startTime = Date.now()
@@ -279,6 +275,7 @@ export class ShellExecutor {
 				exitCode: result.exitCode,
 				signal: result.signal,
 				timedOut: result.timedOut,
+				...(result.truncated === undefined ? {} : { truncated: result.truncated }),
 				durationMs: Date.now() - startTime,
 			})
 		} catch (error) {
@@ -297,11 +294,7 @@ export class ShellExecutor {
 	 * Paths under the hidden home roots exist only where a grant mounts them back; the rest of
 	 * the tree the sandbox binds read-only, so a directory there grants nothing.
 	 */
-	private async resolveSandboxCwd(
-		agentCwd: string,
-		sessionDir: string,
-		workspaceDir: string | undefined,
-	): Promise<Result<string, ToolError>> {
+	private async resolveSandboxCwd(agentCwd: string, sessionDir: string, workspaceDir: string | undefined): Promise<Result<string, ToolError>> {
 		if (!isAbsolute(agentCwd)) {
 			return Err({ message: `Working directory '${agentCwd}' must be an absolute path`, recoverable: false })
 		}
@@ -323,11 +316,7 @@ export class ShellExecutor {
 		}
 
 		if (HIDDEN_ROOTS.some((root) => isWithin(normalized, root))) {
-			const mounted = [
-				VIRTUAL_SESSION,
-				...(workspaceDir ? [VIRTUAL_WORKSPACE] : []),
-				...this.boundRoots().map((root) => root.seen),
-			]
+			const mounted = [VIRTUAL_SESSION, ...(workspaceDir ? [VIRTUAL_WORKSPACE] : []), ...this.boundRoots().map((root) => root.seen)]
 			return Err({
 				message: `Path '${agentCwd}' is not mounted in this sandbox. Mounted roots: ${mounted.join(', ')}`,
 				recoverable: false,
@@ -338,7 +327,7 @@ export class ShellExecutor {
 	}
 
 	private async requireExists(hostPath: string, agentCwd: string, seen: string): Promise<Result<string, ToolError>> {
-		if (await this.fs.exists(hostPath)) return Ok(seen)
+		if (await this.fs.exists(hostPath)) return Ok(this.shell?.confinement === 'paths' ? seen : hostPath)
 		return Err({ message: `Working directory '${agentCwd}' does not exist`, recoverable: false })
 	}
 

package/src/testing/conformance.ts

@@ -93,7 +93,8 @@ export const GIT_FIXTURE: {
 /**
  * What the suite reports on. Most are ports; the dotted ones are facets a port
  * either has or does not — a scheduler that delivers its own wakes, a shell that
- * confines by paths — and they are named so that not exercising one is visible.
+ * terminates on timeout or confines by paths — and they are named so that not
+ * exercising one is visible.
  */
 export type ConformancePort =
 	| 'fs'
@@ -106,6 +107,7 @@ export type ConformancePort =
 	| 'scheduler'
 	| 'scheduler.live'
 	| 'shell'
+	| 'shell.timeout'
 	| 'shell.paths'
 	| 'shell.host'
 	| 'git'
@@ -126,6 +128,7 @@ export const CONFORMANCE_PORTS: readonly ConformancePort[] = [
 	'scheduler',
 	'scheduler.live',
 	'shell',
+	'shell.timeout',
 	'shell.paths',
 	'shell.host',
 	'git',
@@ -230,9 +233,7 @@ interface WalkShape {
 }
 
 function walkShapes(base: string, entries: readonly WalkEntry[]): WalkShape[] {
-	return entries
-		.map((entry) => ({ path: relativeTo(base, entry.path), type: entry.type, size: entry.size }))
-		.sort((a, b) => a.path.localeCompare(b.path))
+	return entries.map((entry) => ({ path: relativeTo(base, entry.path), type: entry.type, size: entry.size })).sort((a, b) => a.path.localeCompare(b.path))
 }
 
 /**
@@ -251,16 +252,13 @@ async function walkWithReaddir(fs: FileSystem, dir: string, options?: WalkOption
 			if (options?.excludeHidden && dirent.name.startsWith('.')) continue
 
 			const path = joinPath(current, [dirent.name])
-			const type: WalkEntry['type'] = dirent.isSymbolicLink()
-				? 'symlink'
-				: dirent.isDirectory()
-					? 'directory'
-					: dirent.isFile()
-						? 'file'
-						: 'other'
-
-			const stats = await fs.stat(path).then((value) => value, () => undefined)
-			const size = type === 'directory' ? 0 : stats?.size ?? 0
+			const type: WalkEntry['type'] = dirent.isSymbolicLink() ? 'symlink' : dirent.isDirectory() ? 'directory' : dirent.isFile() ? 'file' : 'other'
+
+			const stats = await fs.stat(path).then(
+				(value) => value,
+				() => undefined,
+			)
+			const size = type === 'directory' ? 0 : (stats?.size ?? 0)
 			const mtime = stats?.mtimeMs ?? 0
 
 			out.push({ path, type, size, mtime })
@@ -274,13 +272,15 @@ async function walkWithReaddir(fs: FileSystem, dir: string, options?: WalkOption
 
 /** The per-path `readFile` loop `FileSystem.readFiles` replaces. */
 async function readFilesWithLoop(fs: FileSystem, paths: readonly string[]): Promise<ReadFilesEntry[]> {
-	return Promise.all(paths.map(async (path): Promise<ReadFilesEntry> => {
-		try {
-			return { path, content: await fs.readFile(path) }
-		} catch (error) {
-			return { path, error: errorCode(error) ?? String(error) }
-		}
-	}))
+	return Promise.all(
+		paths.map(async (path): Promise<ReadFilesEntry> => {
+			try {
+				return { path, content: await fs.readFile(path) }
+			} catch (error) {
+				return { path, error: errorCode(error) ?? String(error) }
+			}
+		}),
+	)
 }
 
 /**
@@ -335,12 +335,15 @@ function contextFor(target: ConformanceTarget, instance: PlatformInstance): Conf
 			if (!repo) {
 				const dir = joinPath(instance.root, ['fixture-repo'])
 				const build = target.buildGitRepo ?? defaultBuildGitRepo
-				repo = build(instance, dir).then(() => dir, (error) => {
-					throw new Error(
-						`could not build the fixture repository: ${error instanceof Error ? error.message : String(error)}. `
-							+ 'A host that cannot run `git` supplies ConformanceTarget.buildGitRepo.',
-					)
-				})
+				repo = build(instance, dir).then(
+					() => dir,
+					(error) => {
+						throw new Error(
+							`could not build the fixture repository: ${error instanceof Error ? error.message : String(error)}. ` +
+								'A host that cannot run `git` supplies ConformanceTarget.buildGitRepo.',
+						)
+					},
+				)
 			}
 			return repo
 		},
@@ -416,9 +419,7 @@ const fsChecks: ConformanceCheck[] = [
 			expect((await fs.readdir(path())).sort()).toEqual(['a.txt', 'b.txt', 'dir'])
 
 			const dirents = await fs.readdir(path(), { withFileTypes: true })
-			const classified = dirents
-				.map((dirent) => [dirent.name, dirent.isDirectory(), dirent.isFile()])
-				.sort()
+			const classified = dirents.map((dirent) => [dirent.name, dirent.isDirectory(), dirent.isFile()]).sort()
 			expect(classified).toEqual([
 				['a.txt', false, true],
 				['b.txt', false, true],
@@ -763,8 +764,9 @@ const readFilesChecks: ConformanceCheck[] = [
 			const looped = await readFilesWithLoop(fs, paths)
 
 			expect(batched.map((entry) => entry.path)).toEqual(paths)
-			expect(batched.map((entry) => (entry.content ? textOf(entry.content) : undefined)))
-				.toEqual(looped.map((entry) => (entry.content ? textOf(entry.content) : undefined)))
+			expect(batched.map((entry) => (entry.content ? textOf(entry.content) : undefined))).toEqual(
+				looped.map((entry) => (entry.content ? textOf(entry.content) : undefined)),
+			)
 			expect(batched.map((entry) => entry.error)).toEqual([undefined, undefined, undefined])
 		},
 	},
@@ -869,10 +871,7 @@ const rmFilesChecks: ConformanceCheck[] = [
 			const fs = platform.fs
 			await fs.writeFile(path('a.txt'), 'a')
 
-			await rejection(
-				Promise.resolve(fs.rmFiles?.([path('missing.txt')])),
-				'rmFiles of a missing path without force',
-			)
+			await rejection(Promise.resolve(fs.rmFiles?.([path('missing.txt')])), 'rmFiles of a missing path without force')
 			await fs.rmFiles?.([path('missing.txt'), path('a.txt')], { force: true })
 			expect(await fs.exists(path('a.txt'))).toBe(false)
 		},
@@ -885,10 +884,7 @@ const rmFilesChecks: ConformanceCheck[] = [
 			await fs.mkdir(path('tree', 'nested'), { recursive: true })
 			await fs.writeFile(path('tree', 'nested', 'leaf.txt'), 'leaf')
 
-			await rejection(
-				Promise.resolve(fs.rmFiles?.([path('tree')])),
-				'rmFiles of a populated directory without recursive',
-			)
+			await rejection(Promise.resolve(fs.rmFiles?.([path('tree')])), 'rmFiles of a populated directory without recursive')
 			expect(await fs.exists(path('tree', 'nested', 'leaf.txt'))).toBe(true)
 
 			await fs.rmFiles?.([path('tree')], { recursive: true })
@@ -908,10 +904,7 @@ const scopeReadsChecks: ConformanceCheck[] = [
 			await fs.writeFile(path('sub', 'b.txt'), 'bb')
 
 			const outside = [await fs.readFile(path('a.txt'), 'utf-8'), (await fs.readdir(path())).sort().join(',')]
-			const inside = await fs.scopeReads?.(async () => [
-				await fs.readFile(path('a.txt'), 'utf-8'),
-				(await fs.readdir(path())).sort().join(','),
-			])
+			const inside = await fs.scopeReads?.(async () => [await fs.readFile(path('a.txt'), 'utf-8'), (await fs.readdir(path())).sort().join(',')])
 
 			expect(inside).toEqual(outside)
 		},
@@ -922,9 +915,11 @@ const scopeReadsChecks: ConformanceCheck[] = [
 		async run({ platform }) {
 			const marker = new Error('block failed')
 			const caught = await rejection(
-				Promise.resolve(platform.fs.scopeReads?.(async () => {
-					throw marker
-				})),
+				Promise.resolve(
+					platform.fs.scopeReads?.(async () => {
+						throw marker
+					}),
+				),
 				'scopeReads over a block that throws',
 			)
 			expect(caught).toBe(marker)
@@ -1069,6 +1064,14 @@ const shellChecks: ConformanceCheck[] = [
 			expect(declared).toContain(platform.shell?.confinement)
 		},
 	},
+	{
+		port: 'shell',
+		name: 'declares a boolean timeout capability or omits it for legacy support',
+		async run({ platform }) {
+			const capability = platform.shell?.supportsTimeout
+			expect(capability === undefined || typeof capability === 'boolean').toBe(true)
+		},
+	},
 	{
 		port: 'shell',
 		name: 'a non-zero exit resolves rather than rejects',
@@ -1129,7 +1132,7 @@ const shellChecks: ConformanceCheck[] = [
 		},
 	},
 	{
-		port: 'shell',
+		port: 'shell.timeout',
 		name: 'a timeout terminates the command and reports timedOut',
 		async run({ platform, root }) {
 			const started = Date.now()
@@ -1139,6 +1142,21 @@ const shellChecks: ConformanceCheck[] = [
 			expect(result.exitCode).not.toBe(0)
 		},
 	},
+	{
+		port: 'shell.timeout',
+		name: 'a timed-out run cannot keep mutating after it resolves',
+		async run({ platform, path, root }) {
+			const marker = path('late-after-timeout.txt')
+			const result = await shellRun(platform, {
+				command: 'sleep 1; printf late > late-after-timeout.txt',
+				cwd: root,
+				timeoutMs: 100,
+			})
+			expect(result.timedOut).toBe(true)
+			await sleep(1_200)
+			expect(await platform.fs.exists(marker)).toBe(false)
+		},
+	},
 	{
 		port: 'shell.paths',
 		name: 'a granted path is reachable and one outside the grants is not',
@@ -1281,10 +1299,7 @@ const gitChecks: ConformanceCheck[] = [
 
 			await rejection(Promise.resolve(platform.git?.status({ dir })), 'status outside a repository')
 			await rejection(Promise.resolve(platform.git?.log({ dir })), 'log outside a repository')
-			await rejection(
-				Promise.resolve(platform.git?.countAhead({ dir, base: GIT_FIXTURE.base })),
-				'countAhead outside a repository',
-			)
+			await rejection(Promise.resolve(platform.git?.countAhead({ dir, base: GIT_FIXTURE.base })), 'countAhead outside a repository')
 
 			// `defaultBranch` says undefined means unknown, so outside a repo it may answer either way.
 			const branch = await platform.git?.defaultBranch({ dir }).catch(() => undefined)
@@ -1605,11 +1620,16 @@ async function probeInstance(target: ConformanceTarget, instance: PlatformInstan
 
 	const confinement = platform.shell?.confinement
 	add('shell', platform.shell !== undefined)
+	add(
+		'shell.timeout',
+		platform.shell !== undefined && platform.shell.supportsTimeout !== false,
+		platform.shell === undefined ? 'port absent' : 'the runner declares no wall-clock timeout support',
+	)
 	const confines = await probeConfinement(instance)
 	add('shell.paths', confines.ok, confines.note)
 	add('shell.host', confinement === 'host', `confinement is ${confinement ?? 'absent'}`)
 
-	const buildable = platform.git !== undefined && await canBuildGitRepo(target, platform)
+	const buildable = platform.git !== undefined && (await canBuildGitRepo(target, platform))
 	add('git', buildable, platform.git === undefined ? undefined : 'no way to build a fixture repository — declare ConformanceTarget.buildGitRepo')
 
 	add('fsRevision', platform.fsRevision !== undefined)
@@ -1698,9 +1718,7 @@ export async function runConformanceCheck(target: ConformanceTarget, check: Conf
 /** The checks a host answering `answered` should be held to. */
 export function checksFor(answered: Iterable<ConformancePort>): ConformanceCheck[] {
 	const ports = new Set(answered)
-	return platformConformanceChecks.filter((check) =>
-		ports.has(check.port) && (check.needs ?? []).every((port) => ports.has(port))
-	)
+	return platformConformanceChecks.filter((check) => ports.has(check.port) && (check.needs ?? []).every((port) => ports.has(port)))
 }
 
 function describeSkip(support: PortSupport): string {
@@ -1722,9 +1740,7 @@ export function runPlatformConformance(target: ConformanceTarget): void {
 		const skipped = support.filter((entry) => !entry.answered)
 
 		console.log(
-			`[conformance] ${target.name}\n`
-				+ `  exercised: ${exercised.join(', ') || 'none'}\n`
-				+ `  skipped:   ${skipped.map(describeSkip).join(', ') || 'none'}`,
+			`[conformance] ${target.name}\n` + `  exercised: ${exercised.join(', ') || 'none'}\n` + `  skipped:   ${skipped.map(describeSkip).join(', ') || 'none'}`,
 		)
 
 		for (const port of CONFORMANCE_PORTS) {

package/src/transport/http/context.ts

@@ -9,13 +9,13 @@
  */
 
 import type { PreprocessorRegistry } from '~/plugins/uploads/preprocessor.js'
-import type { Services } from '../../bootstrap.js'
+import type { PluginProfile, Services } from '../../bootstrap.js'
 import type { SessionManager } from '../../core/sessions/session-manager.js'
 
 /**
  * Extended services with SessionManager for HTTP routes.
  */
-export type AppServices = Services & {
+export type AppServices = Services<PluginProfile> & {
 	sessionRuntime: SessionManager
 	/** Bearer token for authenticating HTTP requests. Optional - only used in worker mode. */
 	agentToken?: string