@roj-ai/sdk 0.1.32 → 0.1.34

package/src/plugins/services/pid-registry.ts

@@ -0,0 +1,191 @@
+/**
+ * ServicePidRegistry — on-disk record of the service processes this host has spawned,
+ * so a later agent can find and kill the ones nobody owns any more.
+ *
+ * The session projection cannot do this job. It remembers one pid per service type, so
+ * every start overwrites the previous generation, and its reconcile runs from
+ * `onSessionReady` — which fires lazily, when a session is loaded. A session nobody
+ * reopens after a restart therefore never reconciles at all, and its dev server keeps
+ * running until the box runs out of memory. That is not theoretical: a production
+ * sandbox on 2026-08-05 held four dev servers at ~500 MB each across three sessions on
+ * 4 GB with no swap, and the kernel OOM-killer fired repeatedly.
+ *
+ * A file per (session, service type) survives both an agent restart and a VM
+ * pause/resume, and is enumerable without knowing which sessions exist — which is what
+ * makes a host-wide sweep at boot possible.
+ */
+
+import { join } from 'node:path'
+import type { FileSystem } from '~/platform/fs.js'
+import type { Logger } from '../../lib/logger/logger.js'
+import { getProcessStartTime } from './service.js'
+
+/**
+ * What we need in order to decide, later and from another process, whether a recorded
+ * pid may be killed.
+ *
+ * `pidStartTime` is /proc's start time in clock ticks: paired with the pid it identifies
+ * one process, so a mismatch means the kernel recycled the pid and killing would hit an
+ * unrelated process. `agentPid`/`agentStartTime` identify the agent that spawned it — a
+ * booting agent must not kill the services of another agent that is still running.
+ */
+export interface ServicePidRecord {
+	sessionId: string
+	serviceType: string
+	pid: number
+	pidStartTime?: number
+	command: string
+	agentPid: number
+	agentStartTime?: number
+}
+
+const REGISTRY_DIR = 'service-pids'
+
+export class ServicePidRegistry {
+	constructor(
+		private readonly fs: FileSystem,
+		private readonly logger: Logger,
+		/** Agent data directory. Never the session workspace — that is a git worktree. */
+		private readonly dataPath: string,
+	) {}
+
+	private get root(): string {
+		return join(this.dataPath, REGISTRY_DIR)
+	}
+
+	private recordPath(sessionId: string, serviceType: string): string {
+		// Service types are plugin-configured identifiers (`astro-dev`, `cms-sidecar`) and
+		// session ids are uuids, so neither needs escaping to be a safe file name.
+		return join(this.root, `${sessionId}__${serviceType}.json`)
+	}
+
+	/**
+	 * Record a freshly spawned service process. Best-effort: failing to record costs us a
+	 * later sweep, so it must never take down the start that just succeeded.
+	 */
+	async record(record: Omit<ServicePidRecord, 'agentPid' | 'agentStartTime'>): Promise<void> {
+		try {
+			await this.fs.mkdir(this.root, { recursive: true })
+			const full: ServicePidRecord = {
+				...record,
+				agentPid: process.pid,
+				agentStartTime: await getProcessStartTime(this.fs, process.pid),
+			}
+			await this.fs.writeFile(this.recordPath(record.sessionId, record.serviceType), JSON.stringify(full))
+		} catch (error) {
+			this.logger.debug('Could not record service pid', { sessionId: record.sessionId, serviceType: record.serviceType, error })
+		}
+	}
+
+	/** Drop the record for a service whose process is gone. */
+	async forget(sessionId: string, serviceType: string): Promise<void> {
+		try {
+			await this.fs.unlink(this.recordPath(sessionId, serviceType))
+		} catch {
+			// Already gone, or never recorded.
+		}
+	}
+
+	/**
+	 * Kill every recorded service process that no live agent owns, and clear its record.
+	 *
+	 * Meant to run once at agent boot, before any session loads: at that moment this agent
+	 * tracks nothing, so every survivor of a previous incarnation is by definition an
+	 * orphan. Records left by an agent that is still running are skipped — during an
+	 * overlapping restart the outgoing agent's services are still its own.
+	 */
+	async sweepOrphans(): Promise<void> {
+		let files: string[]
+		try {
+			files = await this.fs.readdir(this.root)
+		} catch {
+			return // No registry yet — nothing has ever been spawned here.
+		}
+
+		for (const file of files) {
+			if (!file.endsWith('.json')) continue
+			const path = join(this.root, file)
+			const record = await this.readRecord(path)
+			if (!record) {
+				await this.fs.unlink(path).catch(() => {})
+				continue
+			}
+
+			if (await this.isAgentAlive(record)) {
+				this.logger.debug('Leaving service to its still-running agent', {
+					sessionId: record.sessionId,
+					serviceType: record.serviceType,
+					agentPid: record.agentPid,
+				})
+				continue
+			}
+
+			await this.killIfStillOurs(record)
+			await this.fs.unlink(path).catch(() => {})
+		}
+	}
+
+	private async readRecord(path: string): Promise<ServicePidRecord | null> {
+		try {
+			const parsed: unknown = JSON.parse(await this.fs.readFile(path, 'utf-8'))
+			if (typeof parsed !== 'object' || parsed === null) return null
+			const record = parsed as Partial<ServicePidRecord>
+			if (typeof record.pid !== 'number' || typeof record.sessionId !== 'string' || typeof record.serviceType !== 'string') {
+				return null
+			}
+			return {
+				sessionId: record.sessionId,
+				serviceType: record.serviceType,
+				pid: record.pid,
+				pidStartTime: record.pidStartTime,
+				command: typeof record.command === 'string' ? record.command : '',
+				agentPid: typeof record.agentPid === 'number' ? record.agentPid : 0,
+				agentStartTime: record.agentStartTime,
+			}
+		} catch {
+			return null
+		}
+	}
+
+	/**
+	 * Whether a live agent still owns this record. Ourselves counts: a record carrying our own
+	 * pid describes a service this very process started, which the sweep must never touch —
+	 * that is what makes the sweep safe to run at any time, not only before the first start.
+	 */
+	private async isAgentAlive(record: ServicePidRecord): Promise<boolean> {
+		if (record.agentPid === process.pid) return true
+		if (record.agentPid === 0) return false
+		const currentStartTime = await getProcessStartTime(this.fs, record.agentPid)
+		if (currentStartTime === undefined) return false
+		return record.agentStartTime === undefined || currentStartTime === record.agentStartTime
+	}
+
+	private async killIfStillOurs(record: ServicePidRecord): Promise<void> {
+		const currentStartTime = await getProcessStartTime(this.fs, record.pid)
+		if (currentStartTime === undefined) return // Process is gone.
+		if (record.pidStartTime !== undefined && currentStartTime !== record.pidStartTime) {
+			this.logger.warn('PID reuse detected during orphan sweep — refusing to kill', {
+				sessionId: record.sessionId,
+				serviceType: record.serviceType,
+				pid: record.pid,
+				storedStartTime: record.pidStartTime,
+				currentStartTime,
+			})
+			return
+		}
+
+		try {
+			// Negative pid: services are spawned detached, so this takes the whole group —
+			// the `/bin/sh -c` wrapper and the runtime it exec'd underneath it.
+			process.kill(-record.pid, 'SIGKILL')
+			this.logger.info('Killed orphaned service process group', {
+				sessionId: record.sessionId,
+				serviceType: record.serviceType,
+				pid: record.pid,
+				command: record.command,
+			})
+		} catch (error) {
+			this.logger.debug('Orphaned service process already gone', { pid: record.pid, error })
+		}
+	}
+}

package/src/plugins/services/plugin.ts

@@ -8,6 +8,7 @@ import { Err, Ok } from '~/lib/utils/result.js'
 import type { PortPool } from './port-pool.js'
 import { buildServiceStatusMessage } from './prompt.js'
 import type { ServiceConfig, ServiceEntry } from './schema.js'
+import type { ServicePidRegistry } from './pid-registry.js'
 import { getProcessStartTime, ServiceExecutor } from './service.js'
 
 export const serviceEvents = createEventsFactory({
@@ -33,6 +34,8 @@ export type ServiceStatusChangedEvent = (typeof serviceEvents)['Events']['servic
 export interface ServicePluginConfig {
 	services: ServiceConfig[]
 	portPool: PortPool
+	/** Durable pid record swept at agent boot. Absent for embedders without a data dir. */
+	pidRegistry?: ServicePidRegistry
 }
 
 /**
@@ -133,7 +136,11 @@ 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 })
+		const executor = new ServiceExecutor(ctx.logger, pluginConfig.portPool, {
+			fs: ctx.platform.fs,
+			process: ctx.platform.process,
+			pidRegistry: pluginConfig.pidRegistry,
+		})
 		executor.onStatusChanged = (sessionId, serviceType, status, details) => {
 			void ctx.emitEvent(serviceEvents.create('service_status_changed', {
 				serviceType,

package/src/plugins/services/service.ts

@@ -13,6 +13,7 @@ import { Err, Ok } from '~/lib/utils/result.js'
 import type { FileSystem } from '~/platform/fs.js'
 import type { ChildProcess, ProcessRunner } from '~/platform/process.js'
 import type { PortPool } from '~/plugins/services/port-pool.js'
+import type { ServicePidRegistry } from '~/plugins/services/pid-registry.js'
 import type { ServiceConfig, ServiceStartArgs, ServiceStatus } from '~/plugins/services/schema.js'
 import type { ToolError } from '../../core/tools/executor.js'
 import type { Logger } from '../../lib/logger/logger.js'
@@ -89,6 +90,8 @@ const MAX_PORT_CONFLICT_RETRIES = 3
 export interface ServiceExecutorDeps {
 	fs: FileSystem
 	process: ProcessRunner
+	/** Durable pid record, swept at agent boot. Optional so embedders without a data dir still work. */
+	pidRegistry?: ServicePidRegistry
 }
 
 export class ServiceExecutor {
@@ -103,6 +106,7 @@ export class ServiceExecutor {
 	private readonly portPool: PortPool
 	private readonly fs: FileSystem
 	private readonly processRunner: ProcessRunner
+	private readonly pidRegistry?: ServicePidRegistry
 
 	/** Optional callback invoked on every service status change */
 	onStatusChanged?: (
@@ -117,6 +121,7 @@ export class ServiceExecutor {
 		this.portPool = portPool
 		this.fs = deps.fs
 		this.processRunner = deps.process
+		this.pidRegistry = deps.pidRegistry
 	}
 
 	private notifyStatusChanged(
@@ -354,6 +359,11 @@ export class ServiceExecutor {
 		// "our process" from "an unrelated process that grabbed this PID after ours died"
 		const pidStartTime = await getProcessStartTime(this.fs, child.pid)
 
+		// Durably record the process so a future agent can reap it if we die before the
+		// `close` handler gets to forget it. The session projection cannot serve that
+		// purpose — see ServicePidRegistry.
+		await this.pidRegistry?.record({ sessionId: String(sessionId), serviceType: config.type, pid: child.pid, pidStartTime, command })
+
 		// Emit starting event with PID, port, resolved cwd/command, and start time.
 		this.notifyStatusChanged(sessionId, config.type, 'starting', { port, pid: child.pid, pidStartTime, cwd, command })
 
@@ -512,6 +522,8 @@ export class ServiceExecutor {
 		// Handle unexpected exit
 		child.on('close', (code) => {
 			clearReadinessTimers()
+			// The process is gone, so its durable record has nothing left to reap.
+			void this.pidRegistry?.forget(String(sessionId), config.type)
 			// Flush remaining partial lines
 			if (stdoutPartial) {
 				processLine(stdoutPartial)

package/src/plugins/session-stats/index.ts

@@ -1,3 +1,3 @@
 export { sessionStatsPlugin } from './plugin.js'
-export type { SessionStatsState } from './plugin.js'
+export type { AgentStats, ProviderStats, SessionStatsState } from './plugin.js'
 export { selectSessionStats } from './plugin.js'

package/src/plugins/session-stats/plugin.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it } from 'bun:test'
+import { AgentId } from '~/core/agents/schema.js'
+import { agentEvents } from '~/core/agents/state.js'
+import { contextEvents } from '~/core/context/state.js'
+import { withSessionId } from '~/core/events/test-helpers.js'
+import type { DomainEvent } from '~/core/events/types.js'
+import type { LLMMetrics } from '~/core/llm/state.js'
+import { llmEvents } from '~/core/llm/state.js'
+import { createApplyEvent } from '~/core/sessions/apply-event.js'
+import { SessionId } from '~/core/sessions/schema.js'
+import { createSessionState } from '~/core/sessions/state.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import { toolEvents } from '~/core/tools/state.js'
+import { userChatEvents } from '~/plugins/user-chat/plugin.js'
+import { ChatMessageId } from '~/plugins/user-chat/schema.js'
+import { selectSessionStats, sessionStatsPlugin } from './plugin.js'
+
+const sessionId = SessionId('session-stats-test')
+const orchestrator = AgentId('orchestrator-1')
+const worker = AgentId('worker-1')
+
+const applyEvent = createApplyEvent([sessionStatsPlugin.create()])
+
+const metrics = (overrides: Partial<LLMMetrics> = {}): LLMMetrics => ({
+	promptTokens: 100,
+	completionTokens: 20,
+	totalTokens: 120,
+	latencyMs: 10,
+	model: 'test-model',
+	provider: 'anthropic',
+	cost: 0.5,
+	...overrides,
+})
+
+const spawn = (agentId: AgentId, definitionName: string) =>
+	withSessionId(sessionId, agentEvents.create('agent_spawned', { agentId, definitionName, parentId: null }))
+
+const inference = (agentId: AgentId, m: LLMMetrics) =>
+	withSessionId(sessionId, llmEvents.create('inference_completed', {
+		agentId,
+		consumedMessageIds: [],
+		response: { content: 'ok', toolCalls: [] },
+		metrics: m,
+	}))
+
+const reduce = (events: DomainEvent[]) => selectSessionStats(events.reduce(applyEvent, createSessionState(sessionId, 'test-preset', 0)))
+
+describe('session-stats plugin', () => {
+	it('starts from zeroed counters', () => {
+		const stats = reduce([])
+		expect(stats.userMessages).toBe(0)
+		expect(stats.compactions).toBe(0)
+		expect(stats.cacheReadTokens).toBe(0)
+		expect(stats.cacheWriteTokens).toBe(0)
+		expect(stats.byAgent).toEqual({})
+	})
+
+	it('counts user chat messages', () => {
+		const stats = reduce([
+			spawn(orchestrator, 'orchestrator'),
+			withSessionId(sessionId, userChatEvents.create('user_chat_message_received', {
+				agentId: orchestrator,
+				messageId: ChatMessageId('m1'),
+				content: 'hello',
+				timestamp: 1,
+			})),
+			withSessionId(sessionId, userChatEvents.create('user_chat_message_received', {
+				agentId: orchestrator,
+				messageId: ChatMessageId('m2'),
+				content: 'again',
+				timestamp: 2,
+			})),
+		])
+		expect(stats.userMessages).toBe(2)
+	})
+
+	it('counts context compactions', () => {
+		const stats = reduce([
+			spawn(orchestrator, 'orchestrator'),
+			withSessionId(sessionId, contextEvents.create('context_compacted', {
+				agentId: orchestrator,
+				compactedContent: 'summary',
+				newConversationHistory: [],
+				originalTokens: 1000,
+				compactedTokens: 100,
+				messagesRemoved: 8,
+			})),
+		])
+		expect(stats.compactions).toBe(1)
+	})
+
+	it('sums cache read and write tokens across main and auxiliary inferences', () => {
+		const stats = reduce([
+			spawn(orchestrator, 'orchestrator'),
+			inference(orchestrator, metrics({ cachedTokens: 800, cacheWriteTokens: 200 })),
+			withSessionId(sessionId, llmEvents.create('auxiliary_inference_completed', {
+				agentId: orchestrator,
+				metrics: metrics({ cachedTokens: 50, cacheWriteTokens: 10 }),
+			})),
+			// Providers that report no cache usage must not break the totals.
+			inference(orchestrator, metrics()),
+		])
+		expect(stats.cacheReadTokens).toBe(850)
+		expect(stats.cacheWriteTokens).toBe(210)
+		expect(stats.llmCalls).toBe(3)
+	})
+
+	it('breaks LLM usage down by agent definition name', () => {
+		const stats = reduce([
+			spawn(orchestrator, 'orchestrator'),
+			spawn(worker, 'coder'),
+			inference(orchestrator, metrics({ promptTokens: 100, completionTokens: 20, cost: 0.5 })),
+			inference(worker, metrics({ promptTokens: 300, completionTokens: 40, cost: 1.25 })),
+			inference(worker, metrics({ promptTokens: 200, completionTokens: 10, cost: 0.25 })),
+			withSessionId(sessionId, llmEvents.create('auxiliary_inference_completed', {
+				agentId: worker,
+				metrics: metrics({ promptTokens: 10, completionTokens: 1, cost: 0.05 }),
+			})),
+		])
+		expect(stats.byAgent).toEqual({
+			orchestrator: { llmCalls: 1, promptTokens: 100, completionTokens: 20, totalCost: 0.5 },
+			coder: { llmCalls: 3, promptTokens: 510, completionTokens: 51, totalCost: 1.55 },
+		})
+		expect(stats.totalCost).toBeCloseTo(2.05, 10)
+	})
+
+	it('keeps existing counters working', () => {
+		const stats = reduce([
+			spawn(orchestrator, 'orchestrator'),
+			inference(orchestrator, metrics()),
+			withSessionId(sessionId, llmEvents.create('inference_failed', { agentId: orchestrator, error: 'boom' })),
+			withSessionId(sessionId, toolEvents.create('tool_started', {
+				agentId: orchestrator,
+				toolCallId: ToolCallId('tc-1'),
+				toolName: 'read_file',
+				input: {},
+			})),
+			withSessionId(sessionId, toolEvents.create('tool_failed', {
+				agentId: orchestrator,
+				toolCallId: ToolCallId('tc-1'),
+				error: 'ENOENT',
+			})),
+		])
+		expect(stats.agentCount).toBe(1)
+		expect(stats.llmCalls).toBe(1)
+		expect(stats.llmErrors).toBe(1)
+		expect(stats.toolCalls).toBe(1)
+		expect(stats.toolErrors).toBe(1)
+		expect(stats.totalTokens).toBe(120)
+		expect(stats.promptTokens).toBe(100)
+		expect(stats.completionTokens).toBe(20)
+		expect(stats.byProvider.anthropic).toEqual({
+			llmCalls: 1,
+			totalTokens: 120,
+			promptTokens: 100,
+			completionTokens: 20,
+			totalCost: 0.5,
+		})
+	})
+})

package/src/plugins/session-stats/plugin.ts

@@ -1,9 +1,11 @@
 import { agentEvents } from '~/core/agents/state.js'
+import { contextEvents } from '~/core/context/state.js'
 import { llmEvents } from '~/core/llm/state.js'
 import { definePlugin } from '~/core/plugins/plugin-builder.js'
 import { selectPluginState } from '~/core/sessions/reducer.js'
 import type { SessionState } from '~/core/sessions/state.js'
 import { toolEvents } from '~/core/tools/state.js'
+import { userChatEvents } from '~/plugins/user-chat/plugin.js'
 
 // ============================================================================
 // Session stats state
@@ -17,35 +19,57 @@ export interface ProviderStats {
 	totalCost: number
 }
 
+export interface AgentStats {
+	llmCalls: number
+	promptTokens: number
+	completionTokens: number
+	totalCost: number
+}
+
 export interface SessionStatsState {
 	totalTokens: number
 	promptTokens: number
 	completionTokens: number
+	/** Prompt tokens served from the provider cache (a subset of promptTokens) */
+	cacheReadTokens: number
+	/** Prompt tokens written to the provider cache */
+	cacheWriteTokens: number
 	totalCost: number
 	llmCalls: number
 	llmErrors: number
 	toolCalls: number
 	toolErrors: number
+	/** Chat messages received from the user */
+	userMessages: number
+	/** Context compactions performed in this session */
+	compactions: number
 	agentCount: number
 	firstEventAt: number | null
 	lastEventAt: number | null
 	/** Per-provider breakdown of LLM usage */
 	byProvider: Record<string, ProviderStats>
+	/** Per agent-definition breakdown of LLM usage (keyed by definition name, not agent id) */
+	byAgent: Record<string, AgentStats>
 }
 
 const createInitialStats = (): SessionStatsState => ({
 	totalTokens: 0,
 	promptTokens: 0,
 	completionTokens: 0,
+	cacheReadTokens: 0,
+	cacheWriteTokens: 0,
 	totalCost: 0,
 	llmCalls: 0,
 	llmErrors: 0,
 	toolCalls: 0,
 	toolErrors: 0,
+	userMessages: 0,
+	compactions: 0,
 	agentCount: 0,
 	firstEventAt: null,
 	lastEventAt: null,
 	byProvider: {},
+	byAgent: {},
 })
 
 const PLUGIN_STATE_KEY = 'sessionStats'
@@ -62,11 +86,11 @@ export function selectSessionStats(sessionState: SessionState): SessionStatsStat
 // ============================================================================
 
 export const sessionStatsPlugin = definePlugin('session-stats')
-	.events([agentEvents, llmEvents, toolEvents])
+	.events([agentEvents, llmEvents, toolEvents, contextEvents, userChatEvents])
 	.state({
 		key: PLUGIN_STATE_KEY,
 		initial: createInitialStats,
-		reduce: (stats, event) => {
+		reduce: (stats, event, sessionState) => {
 			const now = event.timestamp
 			const withTimestamp = (partial: Partial<SessionStatsState>): SessionStatsState => ({
 				...stats,
@@ -97,13 +121,29 @@ export const sessionStatsPlugin = definePlugin('session-stats')
 							},
 						}
 						: stats.byProvider
+					// Core reducer runs before plugin slices, so the spawning agent is already in state.
+					const definitionName = sessionState.agents.get(event.agentId)?.definitionName
+					const byAgent = definitionName
+						? {
+							...stats.byAgent,
+							[definitionName]: {
+								llmCalls: (stats.byAgent[definitionName]?.llmCalls ?? 0) + 1,
+								promptTokens: (stats.byAgent[definitionName]?.promptTokens ?? 0) + event.metrics.promptTokens,
+								completionTokens: (stats.byAgent[definitionName]?.completionTokens ?? 0) + event.metrics.completionTokens,
+								totalCost: (stats.byAgent[definitionName]?.totalCost ?? 0) + (event.metrics.cost ?? 0),
+							},
+						}
+						: stats.byAgent
 					return withTimestamp({
 						llmCalls: stats.llmCalls + 1,
 						totalTokens: stats.totalTokens + event.metrics.totalTokens,
 						promptTokens: stats.promptTokens + event.metrics.promptTokens,
 						completionTokens: stats.completionTokens + event.metrics.completionTokens,
+						cacheReadTokens: stats.cacheReadTokens + (event.metrics.cachedTokens ?? 0),
+						cacheWriteTokens: stats.cacheWriteTokens + (event.metrics.cacheWriteTokens ?? 0),
 						totalCost: stats.totalCost + (event.metrics.cost ?? 0),
 						byProvider,
+						byAgent,
 					})
 				}
 
@@ -116,6 +156,12 @@ export const sessionStatsPlugin = definePlugin('session-stats')
 				case 'tool_failed':
 					return withTimestamp({ toolErrors: stats.toolErrors + 1 })
 
+				case 'user_chat_message_received':
+					return withTimestamp({ userMessages: stats.userMessages + 1 })
+
+				case 'context_compacted':
+					return withTimestamp({ compactions: stats.compactions + 1 })
+
 				default:
 					return stats
 			}