@roj-ai/sdk 0.1.36 → 0.2.1

package/src/testing/node-platform.ts

@@ -10,6 +10,8 @@ import { type ChildProcess, execFile as execFileCb, spawn as nodeSpawn } from 'n
 import * as fsp from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { promisify } from 'node:util'
+import { createBunShellRunner } from '~/bun-platform/shell.js'
+import { createTimerScheduler } from '~/platform/index.js'
 import type { FileSystem, Platform, ProcessRunner } from '~/platform/index.js'
 
 const execFileP = promisify(execFileCb)
@@ -32,6 +34,7 @@ export function createNodeFileSystem(): 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),
@@ -75,6 +78,8 @@ export function createNodePlatform(): Platform {
 	return {
 		fs: createNodeFileSystem(),
 		process: createNodeProcessRunner(),
+		scheduler: createTimerScheduler(),
+		shell: createBunShellRunner(),
 		tmpDir: tmpdir(),
 	}
 }

package/src/testing/test-harness.ts

@@ -1,3 +1,5 @@
+import { rm } from 'node:fs/promises'
+import { fullPlugins } from '~/bootstrap.js'
 import type { AgentId } from '~/core/agents/schema.js'
 import type { DomainError } from '~/core/errors.js'
 import { MemoryEventStore } from '~/core/events/memory.js'
@@ -18,44 +20,9 @@ import { ToolExecutor } from '~/core/tools/executor.js'
 import { silentLogger } from '~/lib/logger/logger.js'
 import { createNodePlatform } from './node-platform.js'
 import type { Result } from '~/lib/utils/result.js'
-import { agentStatusPlugin } from '~/plugins/agent-status/plugin.js'
-import { agentsPlugin } from '~/plugins/agents/plugin.js'
-import { filesystemPlugin } from '~/plugins/filesystem/index.js'
-import { gitStatusPlugin } from '~/plugins/git-status/index.js'
-import { llmDebugPlugin } from '~/plugins/llm-debug/plugin.js'
-import { logsPlugin } from '~/plugins/logs/index.js'
-import { mailboxPlugin } from '~/plugins/mailbox/plugin.js'
-import { resourcesPlugin } from '~/plugins/resources/plugin.js'
-import { servicePlugin } from '~/plugins/services/plugin.js'
-import { presetsPlugin, sessionLifecyclePlugin } from '~/plugins/session-lifecycle/index.js'
-import { sessionStatsPlugin } from '~/plugins/session-stats/index.js'
-import { sessionStatePlugin } from '~/plugins/session-state/plugin.js'
-import { uploadsPlugin } from '~/plugins/uploads/plugin.js'
-import { userChatPlugin } from '~/plugins/user-chat/plugin.js'
 import { NotificationCollector } from './notification-collector.js'
 import { waitForAllAgentsIdle } from './wait-helpers.js'
 
-/**
- * Default system plugins for testing — same as builtinPlugins in bootstrap.ts.
- */
-const defaultSystemPlugins: readonly PluginDefinition<string, any, any, any, any>[] = [
-	sessionLifecyclePlugin,
-	presetsPlugin,
-	mailboxPlugin,
-	agentsPlugin,
-	agentStatusPlugin,
-	userChatPlugin,
-	uploadsPlugin,
-	resourcesPlugin,
-	llmDebugPlugin,
-	servicePlugin,
-	filesystemPlugin,
-	logsPlugin,
-	sessionStatsPlugin,
-	sessionStatePlugin,
-	gitStatusPlugin,
-]
-
 const mergeSystemPlugins = <TPlugin extends { name: string }>(plugins: readonly TPlugin[]): TPlugin[] => {
 	const seen = new Set<string>()
 	return plugins.filter(plugin => {
@@ -76,6 +43,8 @@ export class TestHarness {
 	readonly llmProvider: MockLLMProvider
 	readonly notifications: NotificationCollector
 	readonly sessionManager: SessionManager
+	/** Per-instance scratch dir under /tmp, removed by shutdown(). */
+	private readonly basePath: string
 
 	constructor(options: {
 		presets: Preset[]
@@ -87,6 +56,10 @@ export class TestHarness {
 		llmLogger?: LLMLogger
 		/** Optional pre-existing event store — lets multiple harnesses share persisted state (simulates server restart) */
 		eventStore?: MemoryEventStore
+		/** Resident session idle timeout. Zero or absent disables eviction. */
+		sessionIdleTimeoutMs?: number
+		/** Extra notification sink, run after the recorder. Throwing here simulates a hostile embedder. */
+		onUserOutput?: (notification: PluginNotification) => void
 	}) {
 		this.eventStore = options.eventStore ?? new MemoryEventStore()
 
@@ -118,6 +91,7 @@ export class TestHarness {
 		}
 
 		const basePath = `/tmp/roj-test-${Math.random().toString(36).slice(2)}`
+		this.basePath = basePath
 		const toolExecutor = new ToolExecutor(silentLogger)
 		const platform = createNodePlatform()
 		const dataFileStore = new SessionFileStore(basePath, undefined, false, platform.fs, 'session')
@@ -135,10 +109,14 @@ export class TestHarness {
 			logger: silentLogger,
 			basePath,
 			dataFileStore,
-			onUserOutput: (n: PluginNotification) => this.notifications.push(n),
+			onUserOutput: (n: PluginNotification) => {
+				this.notifications.push(n)
+				options.onUserOutput?.(n)
+			},
 			llmLogger: options.llmLogger,
 			platform,
-			systemPlugins: mergeSystemPlugins([...defaultSystemPlugins, ...(options.systemPlugins ?? [])]),
+			sessionIdleTimeoutMs: options.sessionIdleTimeoutMs,
+			systemPlugins: mergeSystemPlugins([...fullPlugins, ...(options.systemPlugins ?? [])]),
 		})
 	}
 
@@ -177,10 +155,15 @@ export class TestHarness {
 	}
 
 	/**
-	 * Shutdown all sessions.
+	 * Shutdown all sessions and remove the harness's own scratch directory.
+	 *
+	 * The directory is exclusively ours (a per-instance random path under /tmp),
+	 * so nothing else can be relying on it. Idempotent — safe from an afterEach
+	 * that also runs after a failed test.
 	 */
 	async shutdown(): Promise<void> {
 		await this.sessionManager.shutdown()
+		await rm(this.basePath, { recursive: true, force: true })
 	}
 }
 

package/src/testing/wait-helpers.ts

@@ -1,3 +1,4 @@
+import { sleep } from '~/lib/utils/sleep.js'
 import type { AgentId } from '~/core/agents/schema.js'
 import type { Session } from '~/core/sessions/session.js'
 
@@ -78,7 +79,3 @@ function areAllAgentsIdle(session: Session): boolean {
 	}
 	return true
 }
-
-function sleep(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms))
-}

package/src/transport/adapter/client-adapter.ts

@@ -12,13 +12,21 @@
 import type { IWebSocketFactory, ProtocolDef, ReconnectOptions } from '@roj-ai/transport'
 import { ClientConnection } from '@roj-ai/transport/client'
 import type { Logger } from '../../lib/logger/logger.js'
+import { encodeProbe, isAckFrame } from './heartbeat.js'
 import type { IAgentTransport, PluginNotification } from './types.js'
 
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 10_000
+
+/** Unanswered probes tolerated before the link counts as dead. */
+const MAX_MISSED_BEATS = 3
+
 export interface ClientAdapterConfig {
 	url: string
 	wsFactory: IWebSocketFactory
 	reconnect?: Partial<ReconnectOptions>
 	logger?: Logger
+	/** Liveness probe cadence. Defaults to 10s. */
+	heartbeatIntervalMs?: number
 }
 
 export class ClientAdapter implements IAgentTransport {
@@ -26,6 +34,8 @@ export class ClientAdapter implements IAgentTransport {
 	private readonly connection: ClientConnection<ProtocolDef, ProtocolDef>
 	private readonly logger?: Logger
 	private heartbeatTimer: ReturnType<typeof setInterval> | null = null
+	private missedBeats = 0
+	private ackObserved = false
 
 	constructor(config: ClientAdapterConfig) {
 		this.config = config
@@ -40,6 +50,18 @@ export class ClientAdapter implements IAgentTransport {
 				jitterFactor: 0.3,
 			},
 		})
+		this.connection.setRawMessageListener((type, payload) => {
+			if (!isAckFrame(type, payload)) return
+			this.ackObserved = true
+			this.missedBeats = 0
+		})
+		// Answering is a property of the peer, not of this adapter: a reconnect can land
+		// on a host that does not, so every connection has to earn the arming again.
+		this.connection.on((event) => {
+			if (event !== 'connected') return
+			this.ackObserved = false
+			this.missedBeats = 0
+		})
 	}
 
 	async start(): Promise<void> {
@@ -58,9 +80,11 @@ export class ClientAdapter implements IAgentTransport {
 
 	private startHeartbeat(): void {
 		this.stopHeartbeat()
-		this.heartbeatTimer = setInterval(() => {
-			this.connection.send(JSON.stringify({ type: 'heartbeat', ts: Date.now() }))
-		}, 10_000)
+		this.missedBeats = 0
+		this.heartbeatTimer = setInterval(
+			() => this.beat(),
+			this.config.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS,
+		)
 	}
 
 	private stopHeartbeat(): void {
@@ -70,6 +94,39 @@ export class ClientAdapter implements IAgentTransport {
 		}
 	}
 
+	private beat(): void {
+		if (!this.connection.isConnected()) {
+			this.missedBeats = 0
+			return
+		}
+
+		// Armed only once this peer has answered, so a host that never acks reads as
+		// "does not implement the probe" rather than as a dead link.
+		if (this.ackObserved && this.missedBeats >= MAX_MISSED_BEATS) {
+			this.logger?.warn('Heartbeat unanswered, reconnecting', { missedBeats: this.missedBeats })
+			void this.reconnect()
+			return
+		}
+
+		this.missedBeats++
+		this.connection.send(encodeProbe())
+	}
+
+	private async reconnect(): Promise<void> {
+		this.missedBeats = 0
+		try {
+			await this.connection.disconnect()
+			// stop() may have run while the socket was tearing down — do not revive it.
+			if (this.heartbeatTimer === null) return
+			await this.connection.connect()
+		} catch (error) {
+			this.logger?.error(
+				'Reconnect after missed heartbeats failed',
+				error instanceof Error ? error : new Error(String(error)),
+			)
+		}
+	}
+
 	broadcast(notification: PluginNotification): void {
 		// Send as wire message — protocol validation happens at the DO side
 		this.connection.send(JSON.stringify({

package/src/transport/adapter/heartbeat.ts

@@ -0,0 +1,50 @@
+/**
+ * Framing for the liveness probe an agent sends and its host answers.
+ *
+ * Both directions carry a complete `WireMessage`, and each side reads the other's
+ * frame before acting on it: an envelope missing its payload is indistinguishable
+ * from silence, which is exactly what the sender's missed-beat count notices.
+ */
+
+import type { WireMessage } from '@roj-ai/transport'
+
+export const HEARTBEAT_TYPE = 'heartbeat'
+export const HEARTBEAT_ACK_TYPE = 'heartbeat_ack'
+
+/** Send time, so a reader can tell one beat from the next. */
+interface HeartbeatPayload {
+	ts: number
+}
+
+function encode(type: string): string {
+	const ts = Date.now()
+	const message: WireMessage<HeartbeatPayload> = { type, payload: { ts }, ts }
+	return JSON.stringify(message)
+}
+
+export const encodeProbe = (): string => encode(HEARTBEAT_TYPE)
+
+export const encodeAck = (): string => encode(HEARTBEAT_ACK_TYPE)
+
+function hasSendTime(payload: unknown): boolean {
+	return typeof payload === 'object' && payload !== null && 'ts' in payload && typeof payload.ts === 'number'
+}
+
+/** Reads a probe off the wire. An incomplete frame is not one, so it goes unanswered. */
+export function isProbeFrame(raw: string): boolean {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(raw)
+	} catch {
+		return false
+	}
+	if (typeof parsed !== 'object' || parsed === null) return false
+	if (!('type' in parsed) || parsed.type !== HEARTBEAT_TYPE) return false
+	if (!('ts' in parsed) || typeof parsed.ts !== 'number') return false
+	return 'payload' in parsed && hasSendTime(parsed.payload)
+}
+
+/** Reads an ack the router has already unwrapped into `(type, payload)`. */
+export function isAckFrame(type: string, payload: unknown): boolean {
+	return type === HEARTBEAT_ACK_TYPE && hasSendTime(payload)
+}

package/src/transport/adapter/server-adapter.ts

@@ -9,6 +9,7 @@
 import type { IServerWebSocket, ProtocolDef } from '@roj-ai/transport'
 import { ConnectionManager, ServerConnection } from '@roj-ai/transport/server'
 import type { Logger } from '../../lib/logger/logger.js'
+import { encodeAck, isProbeFrame } from './heartbeat.js'
 import type { IAgentTransport, PluginNotification } from './types.js'
 
 export interface ServerAdapterConfig {
@@ -79,6 +80,11 @@ export class ServerAdapter implements IAgentTransport {
 	}
 
 	handleMessage(ws: IServerWebSocket, message: string): void {
+		// Answered here, not in the router: the probe carries no session and has no handler.
+		if (isProbeFrame(message)) {
+			ws.send(encodeAck())
+			return
+		}
 		// Forward message to the connection's onmessage handler
 		ws.onmessage?.(message)
 	}

package/src/transport/http/app.ts

@@ -7,9 +7,8 @@
 import { Hono } from 'hono'
 import { cors } from 'hono/cors'
 import { SDK_VERSION } from '~/info.js'
-import type { PreprocessorRegistry } from '~/plugins/uploads/preprocessor.js'
-import type { Services } from '../../bootstrap.js'
-import type { SessionManager } from '../../core/sessions/session-manager.js'
+import type { AppEnv, AppServices } from './context.js'
+import { getServices } from './context.js'
 import { createBearerAuth } from './middleware/bearer-auth.js'
 import { errorHandler } from './middleware/error-handler.js'
 import { createFileRoutes } from './routes/files.js'
@@ -17,38 +16,10 @@ import { createResourceRoutes } from './routes/resources.js'
 import { createRpcRoutes } from './routes/rpc.js'
 import { createUploadRoutes } from './routes/upload.js'
 
-/**
- * Extended services with SessionManager for HTTP routes.
- */
-export type AppServices = Services & {
-	sessionRuntime: SessionManager
-	/** Bearer token for authenticating HTTP requests. Optional - only used in worker mode. */
-	agentToken?: string
-	/** File preprocessor registry for upload routes. Optional - only available when uploads plugin is configured. */
-	preprocessorRegistry?: PreprocessorRegistry
-}
-
-/**
- * Environment type for Hono app with injected services.
- */
-export type AppEnv = {
-	Variables: {
-		services: AppServices
-	}
-}
-
-/**
- * Hono context type for routes.
- */
-export type AppContext = import('hono').Context<AppEnv>
-
-/**
- * Type-safe accessor for services from Hono context.
- * Guarantees services are present (set by middleware).
- */
-export function getServices(c: AppContext): AppServices {
-	return c.get('services')
-}
+// Re-exported so `from './app.js'` keeps working for consumers; the
+// declarations live in context.js, which routes import directly.
+export type { AppContext, AppEnv, AppServices } from './context.js'
+export { getServices } from './context.js'
 
 /**
  * Creates the Hono application with all middleware and routes.
@@ -91,6 +62,7 @@ export function createApp(services: AppServices): Hono<AppEnv> {
 			},
 			stats: {
 				sessionCount: stats.sessionCount,
+				loadedSessionCount: stats.loadedSessionCount,
 				pendingAgents: stats.pendingAgents,
 				processingAgents: stats.processingAgents,
 			},

package/src/transport/http/context.ts

@@ -0,0 +1,46 @@
+/**
+ * Hono context types and the services accessor.
+ *
+ * Kept out of app.ts on purpose. The route factories need `getServices` — a
+ * runtime value, not just a type — while app.ts imports every route factory to
+ * mount them. With both in app.ts the ESM module graph really does contain a
+ * cycle (app -> routes/* -> app), not merely a type-shape artifact. This module
+ * imports nothing from app.ts, so the graph stays acyclic.
+ */
+
+import type { PreprocessorRegistry } from '~/plugins/uploads/preprocessor.js'
+import type { Services } from '../../bootstrap.js'
+import type { SessionManager } from '../../core/sessions/session-manager.js'
+
+/**
+ * Extended services with SessionManager for HTTP routes.
+ */
+export type AppServices = Services & {
+	sessionRuntime: SessionManager
+	/** Bearer token for authenticating HTTP requests. Optional - only used in worker mode. */
+	agentToken?: string
+	/** File preprocessor registry for upload routes. Optional - only available when uploads plugin is configured. */
+	preprocessorRegistry?: PreprocessorRegistry
+}
+
+/**
+ * Environment type for Hono app with injected services.
+ */
+export type AppEnv = {
+	Variables: {
+		services: AppServices
+	}
+}
+
+/**
+ * Hono context type for routes.
+ */
+export type AppContext = import('hono').Context<AppEnv>
+
+/**
+ * Type-safe accessor for services from Hono context.
+ * Guarantees services are present (set by middleware).
+ */
+export function getServices(c: AppContext): AppServices {
+	return c.get('services')
+}