@roj-ai/isolate-runtime 0.0.0 → 0.2.14

package/src/host-contract.ts

@@ -0,0 +1,25 @@
+/**
+ * The contract between the runtime and the Durable Object hosting it. Kept free of imports,
+ * so a host type-checked against Workers types can use it without the SDK.
+ */
+
+/** A user-output notification in the shape the sandbox runtime sends over its agent WebSocket. */
+export interface RuntimeBroadcast {
+	type: string
+	payload: unknown
+	ts: number
+}
+
+/** What the host gives the runtime. Bound to one instance by the host; the runtime cannot name another. */
+export interface RuntimeHost {
+	/** The single alarm slot of the host's Durable Object, lent to the runtime. */
+	setAlarm(scheduledTime: number): Promise<void>
+	deleteAlarm(): Promise<void>
+	broadcast(message: RuntimeBroadcast): Promise<void>
+}
+
+/** What the host calls on the facet's stub. */
+export interface RuntimeFacetRpc {
+	fetch(request: Request): Promise<Response>
+	deliverWakes(): Promise<string[]>
+}

package/src/host.ts

@@ -0,0 +1,9 @@
+/**
+ * What a host needs at run time: the contract with the facet, the module map helpers and the
+ * runtime version. Imports nothing from the runtime itself, so it adds nothing to a host's bundle.
+ */
+
+export type { RuntimeBroadcast, RuntimeFacetRpc, RuntimeHost } from './host-contract.js'
+export { ISOLATE_RUNTIME_NAME, ISOLATE_RUNTIME_VERSION } from './info.js'
+export type { LoaderModule, RuntimeModules } from './modules.js'
+export { APP_BUNDLE_MODULE, unresolvedImports, withAppBundle } from './modules.js'

package/src/index.ts

@@ -0,0 +1,12 @@
+export type {
+	AlarmScheduler,
+	AlarmSchedulerHost,
+	AlarmSchedulerStats,
+	AlarmStorageLike,
+	SyncKvLike,
+} from './alarm-scheduler.js'
+export { createAlarmScheduler } from './alarm-scheduler.js'
+export { ISOLATE_RUNTIME_NAME, ISOLATE_RUNTIME_VERSION } from './info.js'
+export type { RuntimeBroadcast, RuntimeFacetRpc, RuntimeHost } from './host-contract.js'
+export type { IsolateRuntime, IsolateRuntimeOptions, IsolateRuntimeState } from './runtime.js'
+export { createIsolateRuntime, EGRESS_PROVIDED_KEY } from './runtime.js'

package/src/info.ts

@@ -0,0 +1,6 @@
+/** Read from this package's own package.json, so the value tracks releases. */
+
+import pkg from '../package.json' with { type: 'json' }
+
+export const ISOLATE_RUNTIME_VERSION = pkg.version
+export const ISOLATE_RUNTIME_NAME = pkg.name

package/src/modules.ts

@@ -0,0 +1,58 @@
+/**
+ * The Worker Loader module map a host builds once per runtime version (`./build`) and completes with
+ * one app bundle per instance. Free of Bun and Node APIs, so a host can use it inside a Worker.
+ */
+
+/** A Worker Loader module: a `.js` name maps to ES module source, any other name needs its type. */
+export type LoaderModule = string | { js: string }
+
+export interface RuntimeModules {
+	mainModule: string
+	modules: Record<string, LoaderModule>
+}
+
+/** The module name the main module imports the app's config from. */
+export const APP_BUNDLE_MODULE = 'roj-app-bundle'
+
+/** The runtime's modules plus one app bundle: what a host passes to `LOADER.get()`. */
+export function withAppBundle(runtime: RuntimeModules, appBundle: string): RuntimeModules {
+	return { mainModule: runtime.mainModule, modules: { ...runtime.modules, [APP_BUNDLE_MODULE]: { js: appBundle } } }
+}
+
+/** The loader resolves a specifier against the importing module's directory, a bare one included. */
+function resolveModuleName(importer: string, specifier: string): string {
+	if (specifier.startsWith('/')) return specifier.slice(1)
+	const parts = importer.split('/').slice(0, -1)
+	for (const part of specifier.split('/')) {
+		if (part === '..') parts.pop()
+		else if (part !== '.') parts.push(part)
+	}
+	return parts.join('/')
+}
+
+const STATIC_IMPORT = /^(?:import|export)\b[^;'"]*?\bfrom\s*["']([^"']+)["']|^import\s*["']([^"']+)["']/gm
+const DYNAMIC_IMPORT = /\bimport\(\s*["']([^"']+)["']\s*\)/g
+/** Bun's `target: 'bun'` output loads CommonJS dependencies through it; workerd has no such API. */
+const BUN_REQUIRE = 'import.meta.require'
+
+/**
+ * Imports that would not resolve under the loader's rules, plus any use of `import.meta.require`,
+ * reported with that as the specifier. Bun's unminified ESM output keeps every static import at the
+ * start of a line, which is what the scan relies on. Platform builtins (`node:`, `cloudflare:`) are not checked.
+ */
+export function unresolvedImports(modules: Record<string, LoaderModule>): { module: string; specifier: string }[] {
+	const missing: { module: string; specifier: string }[] = []
+	for (const [name, module] of Object.entries(modules)) {
+		const source = typeof module === 'string' ? module : module.js
+		const specifiers = [
+			...[...source.matchAll(STATIC_IMPORT)].map(match => match[1] ?? match[2]),
+			...[...source.matchAll(DYNAMIC_IMPORT)].map(match => match[1]),
+		]
+		for (const specifier of specifiers) {
+			if (specifier === undefined || /^(?:node|cloudflare):/.test(specifier)) continue
+			if (!(resolveModuleName(name, specifier) in modules)) missing.push({ module: name, specifier })
+		}
+		if (source.includes(BUN_REQUIRE)) missing.push({ module: name, specifier: BUN_REQUIRE })
+	}
+	return missing
+}

package/src/runtime.ts

@@ -0,0 +1,115 @@
+/**
+ * The Roj runtime for a Durable Object that runs untrusted app code.
+ *
+ * Everything persistent lives in the object's own SQLite: the kompjutr filesystem,
+ * the event log, the LLM call log and the wake rows. Everything else comes from
+ * {@link RuntimeHost}, the only capability the object holds. Outbound `fetch`
+ * goes wherever the host routed the isolate's global outbound, which is where
+ * provider keys and tool credentials are added — the runtime never holds them.
+ *
+ * It answers the same HTTP surface as the sandbox runtime (`/rpc`, `/status`,
+ * `/sessions/*`), so a host can reuse its sandbox client. Requests reach it only
+ * through the host, which authenticates the caller and stamps `_caller`.
+ */
+
+import { type DurableObjectStorageLike, Workspace } from '@kompjutr/do'
+import { createKompjutrPlatform, KompjutrEventStore } from '@roj-ai/kompjutr-platform'
+import { bootstrap, createSystemFromServices } from '@roj-ai/sdk'
+import type { Config, RojConfig } from '@roj-ai/sdk'
+import { createApp } from '@roj-ai/sdk/transport/http/app'
+import { createAlarmScheduler, type AlarmSchedulerStats, type SyncKvLike } from './alarm-scheduler.js'
+import type { RuntimeHost } from './host-contract.js'
+import { ISOLATE_RUNTIME_NAME, ISOLATE_RUNTIME_VERSION } from './info.js'
+
+/** The parts of `DurableObjectState` the runtime uses. */
+export interface IsolateRuntimeState {
+	storage: DurableObjectStorageLike & { kv: SyncKvLike }
+	waitUntil(promise: Promise<unknown>): void
+}
+
+export interface IsolateRuntimeOptions {
+	userConfig: RojConfig
+	host: RuntimeHost
+	state: IsolateRuntimeState
+	/** Overrides of the built-in config, e.g. `llmMock` in tests. */
+	config?: Partial<Config>
+	/** See `AlarmSchedulerHost.inFlightRetryMs`. */
+	inFlightRetryMs?: number
+}
+
+export interface IsolateRuntime {
+	/** Loads open sessions, which recovers agents an eviction left mid-turn. Await before serving. */
+	start(): Promise<void>
+	fetch(request: Request): Promise<Response>
+	/** Call from the host's `alarm()`. Returns the wake keys delivered. */
+	deliverWakes(): Promise<string[]>
+	schedulerStats(): AlarmSchedulerStats
+}
+
+const DATA_ROOT = '/data'
+
+/**
+ * Stands in for the provider key, so the SDK's key check passes. The host's
+ * egress replaces the authorization header on provider requests.
+ */
+export const EGRESS_PROVIDED_KEY = 'provided-by-host-egress'
+
+export function createIsolateRuntime(options: IsolateRuntimeOptions): IsolateRuntime {
+	const { state, host } = options
+	// `loadConfig()` reads process.env and the cwd, which an isolate has neither of.
+	const config: Config = {
+		port: 0,
+		host: 'localhost',
+		dataPath: DATA_ROOT,
+		persistence: 'memory',
+		logLevel: 'warn',
+		logFormat: 'json',
+		llmLoggingEnabled: true,
+		openRouterApiKey: EGRESS_PROVIDED_KEY,
+		agentRuntime: { name: ISOLATE_RUNTIME_NAME, version: ISOLATE_RUNTIME_VERSION },
+		...options.config,
+	}
+
+	const workspace = new Workspace({ storage: state.storage })
+	workspace.filesystem.mkdir(DATA_ROOT, { recursive: true })
+	const scheduler = createAlarmScheduler({
+		storage: {
+			kv: state.storage.kv,
+			setAlarm: scheduledTime => host.setAlarm(scheduledTime),
+			deleteAlarm: () => host.deleteAlarm(),
+		},
+		waitUntil: promise => state.waitUntil(promise),
+		inFlightRetryMs: options.inFlightRetryMs,
+	})
+	const services = bootstrap(config, options.userConfig, createKompjutrPlatform(workspace, { scheduler }), {
+		pluginProfile: 'isolate',
+		eventStore: new KompjutrEventStore(workspace.db),
+	})
+	const system = createSystemFromServices(services, {
+		onUserOutput: notification => {
+			state.waitUntil(host.broadcast({ type: notification.type, payload: notification.payload, ts: Date.now() }))
+		},
+	})
+	const app = createApp({ ...services, sessionRuntime: system.sessionManager })
+
+	return {
+		async start() {
+			await system.sessionManager.loadAllSessions()
+			await scheduler.flush()
+		},
+
+		async fetch(request) {
+			const response = await app.fetch(request)
+			await scheduler.flush()
+			return response
+		},
+
+		async deliverWakes() {
+			const keys = await scheduler.deliverDue(key => system.sessionManager.dispatchWake(key))
+			await scheduler.flush()
+			return keys
+		},
+
+		schedulerStats: () => scheduler.stats(),
+	}
+}

package/src/testing.ts

@@ -0,0 +1,33 @@
+/** In-memory stand-ins for the Durable Object storage the scheduler uses. Tests only. */
+
+import type { AlarmStorageLike, SyncKvLike } from './alarm-scheduler.js'
+
+export class MemoryKv implements SyncKvLike {
+	readonly #rows = new Map<string, unknown>()
+
+	list(options?: { prefix?: string }): Iterable<[string, unknown]> {
+		const prefix = options?.prefix ?? ''
+		return [...this.#rows].filter(([key]) => key.startsWith(prefix)).sort(([a], [b]) => a.localeCompare(b))
+	}
+
+	put(key: string, value: unknown): void {
+		this.#rows.set(key, value)
+	}
+
+	delete(key: string): boolean {
+		return this.#rows.delete(key)
+	}
+}
+
+export class MemoryAlarmStorage implements AlarmStorageLike {
+	readonly kv = new MemoryKv()
+	alarm: number | null = null
+
+	async setAlarm(scheduledTime: number): Promise<void> {
+		this.alarm = scheduledTime
+	}
+
+	async deleteAlarm(): Promise<void> {
+		this.alarm = null
+	}
+}

package/src/worker/facet.ts

@@ -0,0 +1,29 @@
+import type { RojConfig } from '@roj-ai/sdk'
+import { DurableObject } from 'cloudflare:workers'
+import type { RuntimeFacetRpc, RuntimeHost } from '../host-contract.js'
+import { createIsolateRuntime, type IsolateRuntime } from '../runtime.js'
+
+export interface RuntimeFacetEnv {
+	HOST: RuntimeHost
+}
+
+/** The Durable Object class a host gets through `getDurableObjectClass('Runtime')` and runs as a facet. */
+export function createRuntimeFacet(userConfig: RojConfig) {
+	return class Runtime extends DurableObject<RuntimeFacetEnv> implements RuntimeFacetRpc {
+		readonly #runtime: IsolateRuntime
+
+		constructor(ctx: DurableObjectState, env: RuntimeFacetEnv) {
+			super(ctx, env)
+			this.#runtime = createIsolateRuntime({ userConfig, host: env.HOST, state: ctx })
+			void ctx.blockConcurrencyWhile(() => this.#runtime.start())
+		}
+
+		fetch(request: Request): Promise<Response> {
+			return this.#runtime.fetch(request)
+		}
+
+		deliverWakes(): Promise<string[]> {
+			return this.#runtime.deliverWakes()
+		}
+	}
+}

package/src/worker/main.ts

@@ -0,0 +1,6 @@
+/** Main module of the loaded worker. `roj-app-bundle` is the app's `roj build` output, added by the host. */
+
+import appConfig from 'roj-app-bundle'
+import { createRuntimeFacet } from './facet.js'
+
+export const Runtime = createRuntimeFacet(appConfig)

package/src/worker/roj-app-bundle.d.ts

@@ -0,0 +1,4 @@
+declare module 'roj-app-bundle' {
+	const config: import('@roj-ai/sdk').RojConfig
+	export default config
+}