@roj-ai/sdk 0.1.36 → 0.2.2

package/dist/user-config.js

@@ -4,6 +4,7 @@
  * The runtime loader (`loadUserConfig`) lives in the Bun runtime package
  * since it performs dynamic imports that require a runtime context.
  */
+import { isAbsolute, resolve } from 'node:path';
 /**
  * Type sugar for defining configuration (like Vite, Vitest, etc.).
  * Provides better DX with type inference.
@@ -11,4 +12,74 @@
 export function defineConfig(config) {
     return config;
 }
+const SHELL_PLUGIN_NAME = 'shell';
+/**
+ * Fold the top-level sandbox settings into every preset, so a config that
+ * declares them takes effect. A preset that sets its own value keeps it.
+ *
+ * `bootstrap` calls this, and every host goes through `bootstrap` — an entry
+ * point should forward its `SessionDefaults` rather than fold them itself.
+ */
+export function applySandboxSettings(settings) {
+    return settings.presets.map(preset => ({
+        ...preset,
+        sandboxed: preset.sandboxed ?? settings.sandboxed ?? false,
+        plugins: settings.extraBinds !== undefined ? withExtraBinds(preset.plugins, settings.extraBinds) : preset.plugins,
+    }));
+}
+/** One-line summary of the resolved sandbox posture, for startup logging. */
+export function describeSandboxPosture(presets) {
+    const on = presets.filter(p => p.sandboxed).map(p => p.id);
+    const off = presets.filter(p => !p.sandboxed).map(p => p.id);
+    if (on.length === 0)
+        return 'off';
+    if (off.length === 0)
+        return 'on';
+    return `on for ${on.join(', ')}; off for ${off.join(', ')}`;
+}
+/**
+ * Validate the `extraBinds` of a config file. A relative host `path` resolves
+ * against the config directory, the way `localResources` does. `destPath` names
+ * a location inside the sandbox, so it has nothing to resolve against and must
+ * already be absolute.
+ */
+export function parseExtraBinds(raw, configDir, configPath) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw)) {
+        throw new Error(`'extraBinds' must be an array: ${configPath}`);
+    }
+    const entries = raw;
+    return entries.map((entry, i) => {
+        if (typeof entry !== 'object' || entry === null) {
+            throw new Error(`extraBinds[${i}] must be an object: ${configPath}`);
+        }
+        const path = 'path' in entry ? entry.path : undefined;
+        const mode = 'mode' in entry ? entry.mode : undefined;
+        const destPath = 'destPath' in entry ? entry.destPath : undefined;
+        if (typeof path !== 'string' || !path) {
+            throw new Error(`extraBinds[${i}] missing required 'path': ${configPath}`);
+        }
+        if (mode !== 'rw' && mode !== 'ro') {
+            throw new Error(`extraBinds[${i}] 'mode' must be 'rw' or 'ro': ${configPath}`);
+        }
+        if (destPath !== undefined && (typeof destPath !== 'string' || !isAbsolute(destPath))) {
+            throw new Error(`extraBinds[${i}] 'destPath' must be an absolute path inside the sandbox: ${configPath}`);
+        }
+        return { path: isAbsolute(path) ? path : resolve(configDir, path), mode, destPath };
+    });
+}
+// The shell plugin is the only consumer of extraBinds — a preset without it has nothing to bind into.
+function withExtraBinds(plugins, extraBinds) {
+    return plugins?.map(entry => {
+        if (entry.pluginName !== SHELL_PLUGIN_NAME)
+            return entry;
+        const current = entry.config;
+        if (typeof current !== 'object' || current === null)
+            return entry;
+        if ('extraBinds' in current && current.extraBinds !== undefined)
+            return entry;
+        return { ...entry, config: { ...current, extraBinds } };
+    });
+}
 //# sourceMappingURL=user-config.js.map

package/dist/user-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"user-config.js","sourceRoot":"","sources":["../src/user-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuDH;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC7C,OAAO,MAAM,CAAA;AACd,CAAC"}
+{"version":3,"file":"user-config.js","sourceRoot":"","sources":["../src/user-config.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,8 +1,13 @@
 {
 	"name": "@roj-ai/sdk",
-	"version": "0.1.36",
+	"version": "0.2.2",
 	"type": "module",
 	"main": "./dist/index.js",
+	"roj": {
+		"bunOnlyExports": [
+			"./testing/conformance"
+		]
+	},
 	"exports": {
 		".": {
 			"types": "./dist/index.d.ts",
@@ -74,6 +79,11 @@
 			"import": "./dist/testing/index.js",
 			"default": "./dist/testing/index.js"
 		},
+		"./testing/conformance": {
+			"types": "./dist/testing/conformance.d.ts",
+			"import": "./dist/testing/conformance.js",
+			"default": "./dist/testing/conformance.js"
+		},
 		"./tools/filesystem": {
 			"types": "./dist/plugins/filesystem/index.d.ts",
 			"import": "./dist/plugins/filesystem/index.js",
@@ -113,11 +123,14 @@
 			"types": "./dist/transport/rpc/index.d.ts",
 			"import": "./dist/transport/rpc/index.js",
 			"default": "./dist/transport/rpc/index.js"
-		}
+		},
+		"./package.json": "./package.json"
 	},
 	"files": [
 		"src",
-		"dist"
+		"dist",
+		"!src/**/*.test.ts",
+		"!src/__tests__"
 	],
 	"publishConfig": {
 		"access": "public"
@@ -135,18 +148,15 @@
 		"type-check": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@roj-ai/transport": "^0.1.36",
-		"@hono/zod-validator": "0.7.6",
+		"@roj-ai/transport": "^0.2.2",
 		"hono": "4.13.1",
 		"ignore": "7.0.5",
 		"tokenx": "^1.3.0",
 		"uuidv7": "^1.1.0",
-		"ws": "^8.18.0",
 		"zod": "4.3.6"
 	},
 	"devDependencies": {
 		"@types/bun": "latest",
-		"@types/ws": "^8.5.10",
 		"typescript": "^5.7.2"
 	},
 	"types": "./dist/index.d.ts"

package/src/bootstrap.ts

@@ -45,13 +45,17 @@ import { sessionStatePlugin } from './plugins/session-state/plugin.js'
 import { resourcesPlugin } from './plugins/resources/plugin.js'
 import { uploadsPlugin } from './plugins/uploads/plugin.js'
 import { userChatPlugin } from './plugins/user-chat/plugin.js'
-import type { RojConfig } from './user-config.js'
+import { applySandboxSettings, describeSandboxPosture, type RojConfig } from './user-config.js'
 
 /**
  * All built-in plugin definitions passed to createSystem for type inference.
- * These are always registered in every session (see SessionManager.createSessionInstance).
+ * Registered in every session under the default `full` profile (see
+ * SessionManager.createSessionInstance).
+ *
+ * This set is also the RPC contract: `BuiltinMethodSchemas` — and through it
+ * every client's method types — derives from it whichever profile a host registers.
  */
-const builtinPlugins = [
+export const fullPlugins = [
 	sessionLifecyclePlugin,
 	presetsPlugin,
 	mailboxPlugin,
@@ -69,13 +73,55 @@ const builtinPlugins = [
 	gitStatusPlugin,
 ] as const
 
+/**
+ * Built-in plugins that run without an OS process table, for hosts like a Worker
+ * isolate. Drops `uploads`, `resources` and `services` — each of them shells out
+ * (pdftotext/markitdown, unzip, dev servers).
+ *
+ * `satisfies` keeps this a strict subset of `fullPlugins`, so it cannot name a
+ * plugin the RPC contract does not know about.
+ */
+export const isolatePlugins = [
+	sessionLifecyclePlugin,
+	presetsPlugin,
+	mailboxPlugin,
+	agentsPlugin,
+	agentStatusPlugin,
+	userChatPlugin,
+	llmDebugPlugin,
+	filesystemPlugin,
+	logsPlugin,
+	sessionStatsPlugin,
+	sessionStatePlugin,
+	gitStatusPlugin,
+] as const satisfies readonly (typeof fullPlugins)[number][]
+
+/** Which built-in plugin set a host registers. */
+export type PluginProfile = 'full' | 'isolate'
+
 /** Method schemas inferred from all built-in plugins */
-export type BuiltinMethodSchemas = AllMethodSchemas<typeof builtinPlugins>
+export type BuiltinMethodSchemas = AllMethodSchemas<typeof fullPlugins>
+
+/** Method schemas the `isolate` profile actually registers */
+export type IsolateMethodSchemas = AllMethodSchemas<typeof isolatePlugins>
+
+/** Options for {@link bootstrap}. */
+export interface BootstrapOptions<TProfile extends PluginProfile = PluginProfile> {
+	/** Built-in plugin set to register. Defaults to `full`. */
+	pluginProfile?: TProfile
+	/**
+	 * Event store to use instead of the one `config.persistence` names.
+	 *
+	 * A host whose durable storage is neither a file tree nor memory passes its own
+	 * here, rather than having the store it wants patched in after the fact.
+	 */
+	eventStore?: EventStore
+}
 
 /**
  * Container for all bootstrapped services
  */
-export interface Services {
+export interface Services<TProfile extends PluginProfile = 'full'> {
 	eventStore: EventStore
 	llmProvider: LLMProvider
 	/** Named provider instances for middleware routing (e.g. useProvider('anthropic')) */
@@ -94,29 +140,44 @@ export interface Services {
 	pidRegistry: ServicePidRegistry
 	/** Preprocessor registry for upload content extraction */
 	preprocessorRegistry: PreprocessorRegistry
-	/** Host-environment adapters (filesystem, process). */
+	/** Host-environment adapters (filesystem, process, scheduler). */
 	platform: Platform
+	/** Built-in plugin set chosen at bootstrap — selects what createSystemFromServices registers. */
+	pluginProfile: TProfile
 }
 
 /**
  * Bootstrap all services based on configuration.
  *
- * `platform` provides runtime adapters (fs, process). Callers pass concrete
- * impls from their runtime package (e.g. `createBunPlatform()` from
+ * `platform` provides runtime adapters (fs, process, scheduler). Callers pass
+ * concrete impls from their runtime package (e.g. `createBunPlatform()` from
  * `@roj-ai/sdk/bun-platform`).
+ *
+ * `options.pluginProfile` picks the built-in plugin set; it defaults to `full`.
  */
-export function bootstrap(config: Config, userConfig: RojConfig, platform: Platform): Services {
+export function bootstrap<TProfile extends PluginProfile>(
+	config: Config,
+	userConfig: RojConfig,
+	platform: Platform,
+	options: BootstrapOptions<TProfile> & { pluginProfile: TProfile },
+): Services<TProfile>
+export function bootstrap(config: Config, userConfig: RojConfig, platform: Platform, options?: BootstrapOptions): Services
+export function bootstrap(config: Config, userConfig: RojConfig, platform: Platform, options?: BootstrapOptions): Services<PluginProfile> {
+	const pluginProfile = options?.pluginProfile ?? 'full'
 	const logger = createLogger(config)
-	logger.info('Bootstrapping agent server', { persistence: config.persistence, logLevel: config.logLevel })
+	logger.info('Bootstrapping agent server', { persistence: config.persistence, logLevel: config.logLevel, pluginProfile })
 
-	const eventStore = config.persistence === 'memory'
-		? new MemoryEventStore()
-		: new FileEventStore(config.dataPath, platform.fs)
+	const eventStore = options?.eventStore
+		?? (config.persistence === 'memory'
+			? new MemoryEventStore()
+			: new FileEventStore(config.dataPath, platform.fs, logger))
 
 	const { llmProvider, llmProviders, llmLogger } = createLLMProvider(config, logger, platform)
 
-	const presets = new Map(userConfig.presets.map(p => [p.id, p]))
-	logger.info('Loaded presets', { count: presets.size })
+	// The one place the declared sandbox settings are folded in — every host lands here.
+	const resolvedPresets = applySandboxSettings(userConfig)
+	const presets = new Map(resolvedPresets.map(p => [p.id, p]))
+	logger.info('Loaded presets', { count: presets.size, sandbox: describeSandboxPosture(resolvedPresets) })
 
 	const toolExecutor = new ToolExecutorImpl(logger)
 	const dataFileStore = new SessionFileStore(config.dataPath, undefined, false, platform.fs, 'session')
@@ -156,6 +217,7 @@ export function bootstrap(config: Config, userConfig: RojConfig, platform: Platf
 		pidRegistry,
 		preprocessorRegistry,
 		platform,
+		pluginProfile,
 	}
 }
 
@@ -225,8 +287,9 @@ function createLLMProvider(config: Config, logger: Logger, platform: Platform):
 		return { llmProvider: baseProvider, llmProviders: namedProviders }
 	}
 
-	const llmLogger = new LLMLogger({ basePath: config.dataPath, enabled: true, fs: platform.fs })
-	logger.info('LLM request logging enabled', { path: config.dataPath })
+	// Rows where the host has a table for them, `sessions/<id>/calls/*.json` otherwise.
+	const llmLogger = new LLMLogger({ basePath: config.dataPath, enabled: true, fs: platform.fs, store: platform.llmCallLog })
+	logger.info('LLM request logging enabled', { sink: platform.llmCallLog ? 'store' : config.dataPath })
 
 	return {
 		llmProvider: new LoggingLLMProvider(baseProvider, llmLogger, logger),
@@ -235,18 +298,13 @@ function createLLMProvider(config: Config, logger: Logger, platform: Platform):
 	}
 }
 
-/**
- * Create a System wired to bootstrapped services.
- * Returns the full System object with SessionManager, typed method schemas, and lifecycle methods.
- */
-export function createSystemFromServices(
-	services: Services,
-	options?: {
-		onUserOutput?: UserOutputCallback
-	},
-): System<BuiltinMethodSchemas, typeof builtinPlugins> {
-	return createSystem({
-		plugins: builtinPlugins,
+interface CreateSystemFromServicesOptions {
+	onUserOutput?: UserOutputCallback
+}
+
+/** Everything a System needs except the plugin set, which the profile picks. */
+function buildSystem(services: Services<PluginProfile>, options?: CreateSystemFromServicesOptions) {
+	const wiring = {
 		eventStore: services.eventStore,
 		llmProvider: services.llmProvider,
 		llmProviders: services.llmProviders,
@@ -257,11 +315,39 @@ export function createSystemFromServices(
 		dataFileStore: services.dataFileStore,
 		onUserOutput: options?.onUserOutput,
 		preprocessorRegistry: services.preprocessorRegistry,
+		uploadArchiveLimits: services.config.uploadArchiveLimits,
+		resourceArchiveLimits: services.config.resourceArchiveLimits,
 		llmLogger: services.llmLogger,
 		portPool: services.portPool,
 		pidRegistry: services.pidRegistry,
 		platform: services.platform,
-	})
+		sessionIdleTimeoutMs: services.config.sessionIdleTimeoutMs,
+	}
+
+	return services.pluginProfile === 'isolate'
+		? createSystem({ ...wiring, plugins: isolatePlugins })
+		: createSystem({ ...wiring, plugins: fullPlugins })
+}
+
+/**
+ * Create a System wired to bootstrapped services.
+ * Returns the full System object with SessionManager, typed method schemas, and lifecycle methods.
+ *
+ * Which plugins get registered follows the profile `services` was bootstrapped
+ * with. `BuiltinMethodSchemas` still covers every built-in plugin, so a client
+ * may name a method the running profile does not register — that call comes back
+ * as a method-not-found error, the same as any unknown method.
+ */
+export function createSystemFromServices(
+	services: Services<'isolate'>,
+	options?: CreateSystemFromServicesOptions,
+): System<IsolateMethodSchemas, typeof isolatePlugins>
+export function createSystemFromServices(
+	services: Services,
+	options?: CreateSystemFromServicesOptions,
+): System<BuiltinMethodSchemas, typeof fullPlugins>
+export function createSystemFromServices(services: Services<PluginProfile>, options?: CreateSystemFromServicesOptions) {
+	return buildSystem(services, options)
 }
 
 /**
@@ -269,12 +355,10 @@ export function createSystemFromServices(
  * @deprecated Use createSystemFromServices() instead for typed method registry.
  */
 export function createSessionManager(
-	services: Services,
-	options?: {
-		onUserOutput?: UserOutputCallback
-	},
+	services: Services<PluginProfile>,
+	options?: CreateSystemFromServicesOptions,
 ): SessionManager {
-	return createSystemFromServices(services, options).sessionManager
+	return buildSystem(services, options).sessionManager
 }
 
 /**

package/src/bun-platform/fs.ts

@@ -26,6 +26,7 @@ export function createBunFileSystem(): FileSystem {
 				: fsp.readdir(path)) as FileSystem['readdir'],
 
 		stat: (path) => fsp.stat(path),
+		lstat: (path) => fsp.lstat(path),
 		access: (path, mode) => fsp.access(path, mode),
 
 		unlink: (path) => fsp.unlink(path),

package/src/bun-platform/index.ts

@@ -6,16 +6,33 @@
  */
 
 import { tmpdir } from 'node:os'
+import { createTimerScheduler } from '../platform/index.js'
 import type { Platform } from '../platform/index.js'
 import { createBunFileSystem } from './fs.js'
 import { createBunProcessRunner } from './process.js'
+import { createBunShellRunner } from './shell.js'
 
 export function createBunPlatform(): Platform {
 	return {
 		fs: createBunFileSystem(),
 		process: createBunProcessRunner(),
+		scheduler: createTimerScheduler(),
+		shell: createBunShellRunner(),
 		tmpDir: tmpdir(),
 	}
 }
 
-export { createBunFileSystem, createBunProcessRunner }
+export { createBunFileSystem, createBunProcessRunner, createBunShellRunner }
+export { buildBwrapArgs, type BwrapOptions } from './shell.js'
+export {
+	createServerLifecycle,
+	runServerStartup,
+	ServerCleanupError,
+	shutdownFromSignal,
+	StartupInterruptedError,
+	type ServerLifecycle,
+	type ServerLifecycleOptions,
+	type ServerSignal,
+	type SignalListenerRegistry,
+	type StartupStage,
+} from './server-lifecycle.js'

package/src/bun-platform/server-lifecycle.ts

@@ -0,0 +1,218 @@
+export type ServerSignal = 'SIGINT' | 'SIGTERM'
+
+export interface SignalListenerRegistry {
+	add(signal: ServerSignal, listener: () => void): void
+	remove(signal: ServerSignal, listener: () => void): void
+}
+
+export interface ServerLifecycle {
+	shutdown(): Promise<void>
+	isShuttingDown(): boolean
+	runStartupStage(stage: StartupStage): Promise<void>
+}
+
+export interface StartupStage {
+	run: () => Promise<void>
+	cancel?: () => Promise<void> | void
+}
+
+export interface ServerLifecycleOptions {
+	stopIngress: () => Promise<void> | void
+	cleanupSteps: ReadonlyArray<() => Promise<void> | void>
+	runSignalShutdown: (shutdown: () => Promise<void>) => void
+}
+
+export class ServerCleanupError extends AggregateError {
+	readonly orderedErrors: readonly unknown[]
+
+	constructor(errors: readonly unknown[]) {
+		super(errors, 'Server shutdown failed')
+		this.name = 'ServerCleanupError'
+		this.orderedErrors = errors
+	}
+}
+
+export class StartupInterruptedError extends Error {
+	constructor() {
+		super('Server startup was interrupted by shutdown')
+		this.name = 'StartupInterruptedError'
+	}
+}
+
+const processSignalListeners: SignalListenerRegistry = {
+	add(signal, listener) {
+		process.on(signal, listener)
+	},
+	remove(signal, listener) {
+		process.off(signal, listener)
+	},
+}
+
+export function createServerLifecycle(
+	options: ServerLifecycleOptions,
+	signalListeners: SignalListenerRegistry = processSignalListeners,
+): ServerLifecycle {
+	let shutdownPromise: Promise<void> | undefined
+	let shuttingDown = false
+	let activeStartupStage: { promise: Promise<void>; cancel?: () => Promise<void> | void } | undefined
+	let listenersInstalled = true
+	let signalHandled = false
+
+	const removeSignalListeners = () => {
+		if (!listenersInstalled) return
+		listenersInstalled = false
+		signalListeners.remove('SIGINT', handleSigint)
+		signalListeners.remove('SIGTERM', handleSigterm)
+	}
+
+	const finishCleanup = async (
+		ingressResult: Promise<void> | void,
+		startupStage: { promise: Promise<void>; cancel?: () => Promise<void> | void } | undefined,
+	) => {
+		const errors: unknown[] = []
+		let cancellationError: unknown
+		let cancellationFailed = false
+		let cancellationSettled: Promise<void> | undefined
+		if (startupStage?.cancel) {
+			try {
+				cancellationSettled = Promise.resolve(startupStage.cancel()).catch((error) => {
+					cancellationFailed = true
+					cancellationError = error
+				})
+			} catch (error) {
+				cancellationFailed = true
+				cancellationError = error
+			}
+		}
+
+		try {
+			await ingressResult
+		} catch (error) {
+			errors.push(error)
+		}
+
+		await cancellationSettled
+		if (cancellationFailed) errors.push(cancellationError)
+
+		if (startupStage) {
+			try {
+				await startupStage.promise
+			} catch {
+				// Startup reports its own failure after joining shutdown.
+			}
+		}
+
+		for (const step of options.cleanupSteps) {
+			try {
+				await step()
+			} catch (error) {
+				errors.push(error)
+			}
+		}
+
+		if (errors.length === 1) throw errors[0]
+		if (errors.length > 1) throw new ServerCleanupError(errors)
+	}
+
+	const shutdown = (): Promise<void> => {
+		if (shutdownPromise) return shutdownPromise
+
+		shuttingDown = true
+		const startupStage = activeStartupStage
+		let resolveShutdown = () => {}
+		let rejectShutdown = (_error: unknown) => {}
+		shutdownPromise = new Promise<void>((resolve, reject) => {
+			resolveShutdown = resolve
+			rejectShutdown = reject
+		})
+
+		let ingressResult: Promise<void> | void
+		try {
+			ingressResult = options.stopIngress()
+		} catch (error) {
+			ingressResult = Promise.reject(error)
+		}
+
+		void (async () => {
+			try {
+				await finishCleanup(ingressResult, startupStage)
+				removeSignalListeners()
+				resolveShutdown()
+			} catch (error) {
+				removeSignalListeners()
+				rejectShutdown(error)
+			}
+		})()
+		return shutdownPromise
+	}
+
+	const beginSignalShutdown = () => {
+		if (signalHandled) return
+		signalHandled = true
+		options.runSignalShutdown(shutdown)
+	}
+
+	function handleSigint() {
+		beginSignalShutdown()
+	}
+
+	function handleSigterm() {
+		beginSignalShutdown()
+	}
+
+	signalListeners.add('SIGINT', handleSigint)
+	signalListeners.add('SIGTERM', handleSigterm)
+
+	return {
+		shutdown,
+		isShuttingDown: () => shuttingDown,
+		async runStartupStage(stage) {
+			if (shuttingDown) throw new StartupInterruptedError()
+			const runningStage = Promise.resolve().then(stage.run)
+			const activeStage = { promise: runningStage, cancel: stage.cancel }
+			activeStartupStage = activeStage
+			try {
+				await runningStage
+			} finally {
+				if (activeStartupStage === activeStage) activeStartupStage = undefined
+			}
+		},
+	}
+}
+
+export async function runServerStartup(lifecycle: ServerLifecycle, steps: ReadonlyArray<StartupStage>): Promise<void> {
+	try {
+		for (const step of steps) {
+			await lifecycle.runStartupStage(step)
+			if (lifecycle.isShuttingDown()) throw new StartupInterruptedError()
+		}
+	} catch (startupError) {
+		const reportedStartupError =
+			lifecycle.isShuttingDown() && !(startupError instanceof StartupInterruptedError) ? new StartupInterruptedError() : startupError
+		try {
+			await lifecycle.shutdown()
+		} catch (cleanupError) {
+			const cleanupErrors = cleanupError instanceof ServerCleanupError ? cleanupError.orderedErrors : [cleanupError]
+			throw new AggregateError([reportedStartupError, ...cleanupErrors], 'Server startup failed and cleanup failed', {
+				cause: reportedStartupError,
+			})
+		}
+		throw reportedStartupError
+	}
+}
+
+export async function shutdownFromSignal(
+	shutdown: () => Promise<void>,
+	reportError: (message: string, error: unknown) => void = (message, error) => console.error(message, error),
+	exit: (code: number) => void = (code) => process.exit(code),
+): Promise<void> {
+	let exitCode = 0
+	try {
+		await shutdown()
+	} catch (error) {
+		exitCode = 1
+		reportError('Shutdown failed', error)
+	} finally {
+		exit(exitCode)
+	}
+}