@namzu/sdk 0.1.7 → 0.2.0

package/src/manager/agent/lifecycle.ts

@@ -1,6 +1,17 @@
 import { AGENT_MANAGER_DEFAULTS } from '../../constants/agent/index.js'
 import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
 import type { AgentRegistry } from '../../registry/agent/definitions.js'
+import { RUN_EVENT_SCHEMA_VERSION } from '../../session/events/schema-version.js'
+import {
+	type CapacityValidator,
+	DelegationCapacityExceeded,
+} from '../../session/handoff/capacity.js'
+import type { ActorRef } from '../../session/hierarchy/actor.js'
+import type { Lineage } from '../../session/hierarchy/lineage.js'
+import type { SessionSummaryMaterializer } from '../../session/summary/materialize.js'
+import type { SessionSummaryOutcome } from '../../session/summary/ref.js'
+import type { WorkspaceRef } from '../../session/workspace/ref.js'
+import type { WorkspaceBackendRegistry } from '../../session/workspace/registry.js'
 import type { BaseAgentConfig, BaseAgentResult } from '../../types/agent/base.js'
 import type {
 	AgentLifecycleEvent,
@@ -14,33 +25,79 @@ import type {
 	SendMessageOptions,
 } from '../../types/agent/task.js'
 import { isTerminalAgentTaskState } from '../../types/agent/task.js'
-import type { RunId, TaskId } from '../../types/ids/index.js'
+import type { AgentId, RunId, SessionId, TaskId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
+import type { RunEvent, RunEventListener } from '../../types/run/events.js'
+import type { SubSessionId } from '../../types/session/ids.js'
+import type { SessionStore } from '../../types/session/store.js'
 import { createChildAbortController } from '../../utils/abort.js'
 import { ZERO_COST } from '../../utils/cost.js'
 import { toErrorMessage } from '../../utils/error.js'
 import { generateTaskId } from '../../utils/id.js'
 import { type Logger, getRootLogger } from '../../utils/logger.js'
 
+/**
+ * Dependencies threaded into {@link AgentManager}. Phase 6 promoted the
+ * SubSession + Session + WorkspaceRef triple to mandatory spawn primitives —
+ * these collaborators replace the old `Object.assign({sourceAgentId,
+ * parentTaskId})` loose-cast cadence with a typed {@link Lineage} +
+ * {@link SessionSummaryMaterializer} closure of the parent→child message gap.
+ *
+ * Phase 9 Known Delta #5: fields are now unconditional required. The legacy
+ * "run without deps" compat branch was removed; every `AgentManager` consumer
+ * (SDK internals, `@namzu/agents`, `@namzu/api`, `@namzu/cli`) MUST wire the
+ * full set before instantiating. Convention #0 (no workarounds): the
+ * partially-wired mode was a migration-window bridge; 0.2.0 closes it.
+ *
+ * `workspaceRegistry` is required but may be empty — spawns without a
+ * registered workspace backend still succeed with `workspaceRef: undefined`
+ * (the runtime uses `.has(backend)` to gate provisioning). This keeps the
+ * registry deny-by-default while matching pattern doc §7.1 (lazy workspace
+ * provisioning).
+ */
+export interface AgentManagerDeps {
+	readonly sessionStore: SessionStore
+	readonly workspaceRegistry: WorkspaceBackendRegistry
+	readonly summaryMaterializer: SessionSummaryMaterializer
+	readonly capacity: CapacityValidator
+}
+
+interface ChildSpawnRecord {
+	subSessionId: SubSessionId
+	childSessionId: SessionId
+	tenantId: TenantId
+	parentSessionId: SessionId
+	rootSessionId: SessionId
+	childDepth: number
+	workspaceRef?: WorkspaceRef
+}
+
 export class AgentManager {
 	private registry: AgentRegistry
 	private instances: Map<TaskId, AgentTask> = new Map()
+	private spawnRecords: Map<TaskId, ChildSpawnRecord> = new Map()
 	private completionCallbacks: Map<TaskId, Array<() => void>> = new Map()
 	private listeners: AgentLifecycleListener[] = []
 	private log: Logger
 	private config: Readonly<AgentManagerConfig>
 	private evictionTimers: Map<TaskId, ReturnType<typeof setTimeout>> = new Map()
+	private deps: AgentManagerDeps
 
-	constructor(registry: AgentRegistry, config?: Partial<AgentManagerConfig>) {
+	constructor(
+		registry: AgentRegistry,
+		config: Partial<AgentManagerConfig> | undefined,
+		deps: AgentManagerDeps,
+	) {
 		this.registry = registry
 		this.config = { ...AGENT_MANAGER_DEFAULTS, ...config }
 		this.log = getRootLogger().child({ component: 'AgentManager' })
+		this.deps = deps
 	}
 
 	async sendMessage(
 		options: SendMessageOptions,
 		context: AgentTaskContext,
-		listener?: import('../../types/run/events.js').RunEventListener,
+		listener?: RunEventListener,
 	): Promise<AgentTask> {
 		if (context.depth >= this.config.maxDepth) {
 			throw new Error(
@@ -48,6 +105,12 @@ export class AgentManager {
 			)
 		}
 
+		if (options.tenantId !== context.tenantId) {
+			throw new Error(
+				`Tenant mismatch: options.tenantId=${options.tenantId} differs from context.tenantId=${context.tenantId}. Cross-tenant spawn rejected (Convention #17).`,
+			)
+		}
+
 		const agent = this.registry.resolve(options.agentId)
 
 		const childAbortController = createChildAbortController(context.parentAbortController)
@@ -61,13 +124,39 @@ export class AgentManager {
 		)
 		context.budgetTracker.remaining -= allocatedTokens
 
+		// Phase 6: SubSession + child Session + WorkspaceRef triple. Happens
+		// before taskId minting so a capacity failure short-circuits cleanly
+		// with no observable state change.
+		const spawnRecord = await this.provisionSpawn(options, context)
+
 		const taskId = generateTaskId()
+
+		const childParentActor: ActorRef = {
+			kind: 'agent',
+			agentId: context.parentAgentId as AgentId,
+			tenantId: context.tenantId,
+			parentActor: context.parentActor,
+		}
+
+		const childContext: AgentTaskContext = {
+			parentRunId: context.parentRunId,
+			parentAgentId: context.parentAgentId,
+			parentAbortController: context.parentAbortController,
+			depth: context.depth + 1,
+			budgetTracker: context.budgetTracker,
+			factoryOptions: context.factoryOptions,
+			tenantId: context.tenantId,
+			sessionId: spawnRecord.childSessionId,
+			projectId: context.projectId,
+			parentActor: childParentActor,
+		}
+
 		const agentTask: AgentTask = {
 			taskId,
 			agentId: options.agentId,
 			agent,
 			childAbortController,
-			context,
+			context: childContext,
 			state: 'pending',
 			pendingMessages: [],
 			createdAt: Date.now(),
@@ -75,6 +164,7 @@ export class AgentManager {
 		}
 
 		this.instances.set(taskId, agentTask)
+		this.spawnRecords.set(taskId, spawnRecord)
 		this.emit({
 			type: 'pending',
 			taskId,
@@ -92,6 +182,22 @@ export class AgentManager {
 				childAgentId: options.agentId,
 				depth: context.depth,
 			})
+
+			const lineage: Lineage = {
+				parentSessionId: spawnRecord.parentSessionId,
+				rootSessionId: spawnRecord.rootSessionId,
+				depth: spawnRecord.childDepth,
+			}
+			listener({
+				type: 'subsession_spawned',
+				runId: context.parentRunId,
+				subSessionId: spawnRecord.subSessionId,
+				parentSessionId: spawnRecord.parentSessionId,
+				spawnedBy: context.parentActor,
+				lineage,
+				schemaVersion: RUN_EVENT_SCHEMA_VERSION,
+				at: new Date(),
+			})
 		}
 		this.log.info(`Agent task pending: ${taskId} (${options.agentId}, depth=${context.depth})`)
 
@@ -102,7 +208,7 @@ export class AgentManager {
 				...context.factoryOptions,
 				tokenBudget: allocatedTokens,
 				timeoutMs: options.budgetAllocation?.timeoutMs ?? context.budgetTracker.remaining,
-				threadId: context.threadId as string | undefined,
+				threadId: context.projectId as string,
 				parentRunId: context.parentRunId as string | undefined,
 				depth: context.depth + 1,
 				...options.configOverrides,
@@ -111,6 +217,13 @@ export class AgentManager {
 			if (!childConfig.contextLevel && definition.contextLevel) {
 				childConfig.contextLevel = definition.contextLevel
 			}
+
+			// Propagate session-hierarchy scoping onto the child config. The
+			// configBuilder may not have been updated to emit these yet; we
+			// stamp them here so query() sees them regardless.
+			childConfig.sessionId = spawnRecord?.childSessionId ?? context.sessionId
+			childConfig.projectId = context.projectId
+			childConfig.tenantId = context.tenantId
 		} else {
 			this.log.warn('No configBuilder or factoryOptions, using bare config', {
 				agentId: options.agentId,
@@ -123,7 +236,10 @@ export class AgentManager {
 				maxIterations: options.configOverrides?.maxIterations,
 				maxResponseTokens: options.configOverrides?.maxResponseTokens,
 				env: options.configOverrides?.env,
-				threadId: context.threadId,
+				threadId: context.projectId,
+				sessionId: spawnRecord.childSessionId,
+				projectId: context.projectId,
+				tenantId: context.tenantId,
 				parentRunId: context.parentRunId,
 				depth: context.depth + 1,
 			}
@@ -193,6 +309,10 @@ export class AgentManager {
 		return this.instances.get(taskId)
 	}
 
+	getSpawnRecord(taskId: TaskId): ChildSpawnRecord | undefined {
+		return this.spawnRecords.get(taskId)
+	}
+
 	listByParent(parentRunId: RunId): AgentTask[] {
 		return Array.from(this.instances.values()).filter((t) => t.context.parentRunId === parentRunId)
 	}
@@ -223,6 +343,7 @@ export class AgentManager {
 			if (isTerminalAgentTaskState(agentTask.state)) {
 				this.clearEvictionTimer(taskId)
 				this.instances.delete(taskId)
+				this.spawnRecords.delete(taskId)
 			}
 		}
 	}
@@ -233,14 +354,110 @@ export class AgentManager {
 		}
 		this.cancelAll('' as RunId)
 		this.instances.clear()
+		this.spawnRecords.clear()
 		this.listeners.length = 0
 	}
 
+	private async provisionSpawn(
+		options: SendMessageOptions,
+		context: AgentTaskContext,
+	): Promise<ChildSpawnRecord> {
+		// Phase 9: deps are unconditional required. Every spawn produces a
+		// SubSession + Session + WorkspaceRef triple (Convention #0: no
+		// partial/legacy path).
+		const store = this.deps.sessionStore
+
+		const project = await store.getProject(context.projectId, context.tenantId)
+		if (!project) {
+			throw new Error(
+				`Project ${context.projectId} not found for tenant ${context.tenantId} — spawn rejected`,
+			)
+		}
+
+		// Capacity: depth + width. Depth uses the parent session's ancestry
+		// chain; width counts existing direct children of the parent.
+		await this.deps.capacity.validateDepth(
+			options.parentSessionId,
+			project.config.maxDelegationDepth,
+			context.tenantId,
+		)
+		await this.deps.capacity.validateWidth(
+			options.parentSessionId,
+			1,
+			project.config.maxDelegationWidth,
+			context.tenantId,
+		)
+
+		// Ancestry walk gives both the child depth and the root session id
+		// attached to every sub-session event from here down.
+		const parentAncestry = await store.getAncestry(options.parentSessionId, context.tenantId)
+		const rootSessionId = parentAncestry[0] ?? options.parentSessionId
+		const childDepth = parentAncestry.length
+
+		const childActor: ActorRef = {
+			kind: 'agent',
+			agentId: options.agentId as AgentId,
+			tenantId: context.tenantId,
+			parentActor: context.parentActor,
+		}
+
+		const childSession = await store.createSession(
+			{ projectId: context.projectId, currentActor: childActor },
+			context.tenantId,
+		)
+
+		// Flip to 'active' so the materializer's atomic write + status flip
+		// lands on terminal — §5.3: pending→active→idle.
+		await store.updateSession({ ...childSession, status: 'active' }, context.tenantId)
+
+		const subSession = await store.createSubSession(
+			{
+				parentSessionId: options.parentSessionId,
+				childSessionId: childSession.id,
+				kind: 'agent_spawn',
+				spawnedBy: context.parentActor,
+				failureMode: 'delegate',
+				completionMode: 'summary_ref',
+			},
+			context.tenantId,
+		)
+
+		// Workspace provisioning — best-effort. When the requested backend is
+		// registered we create a new workspace for the child; failures surface
+		// as WorkspaceBackendError and abort the spawn (Convention #0: no
+		// silent fallback). Pattern doc §7.1 allows lazy provisioning: an
+		// unregistered backend leaves `workspaceRef: undefined` on the spawn
+		// record, not a hard error — the registry is the capability surface.
+		let workspaceRef: WorkspaceRef | undefined
+		const backend = options.workspaceBackend ?? 'git-worktree'
+		if (this.deps.workspaceRegistry.has(backend)) {
+			const driver = this.deps.workspaceRegistry.get(backend)
+			try {
+				workspaceRef = await driver.create({ label: subSession.id })
+			} catch (err) {
+				// Surface the failure — the subsession record exists but is
+				// unusable without a workspace. Dispose any partial state.
+				await store.updateSubSession({ ...subSession, status: 'failed' }, context.tenantId)
+				throw err
+			}
+		}
+
+		return {
+			subSessionId: subSession.id,
+			childSessionId: childSession.id,
+			tenantId: context.tenantId,
+			parentSessionId: options.parentSessionId,
+			rootSessionId,
+			childDepth,
+			workspaceRef,
+		}
+	}
+
 	private async runChild(
 		agentTask: AgentTask,
 		options: SendMessageOptions,
 		childConfig: BaseAgentConfig,
-		listener?: import('../../types/run/events.js').RunEventListener,
+		listener?: RunEventListener,
 	): Promise<void> {
 		this.updateState(agentTask.taskId, 'running')
 		this.emit({ type: 'running', taskId: agentTask.taskId })
@@ -250,17 +467,135 @@ export class AgentManager {
 			signal: agentTask.childAbortController.signal,
 		}
 
-		const childListener = listener
-			? async (event: import('../../types/run/events.js').RunEvent): Promise<void> => {
-					const annotated = Object.assign({}, event, {
-						sourceAgentId: agentTask.agentId,
-						parentTaskId: agentTask.taskId,
+		const spawnRecord = this.spawnRecords.get(agentTask.taskId)
+		const childListener = this.wrapChildListener(listener, spawnRecord)
+
+		const result = await agentTask.agent.run(input, childConfig, childListener)
+		await this.finalizeChild(agentTask, result)
+	}
+
+	/**
+	 * Wraps the parent listener so every event emitted from the child's run
+	 * carries the session-hierarchy `lineage` + `schemaVersion: 2` stamp.
+	 * Replaces the old `Object.assign({sourceAgentId, parentTaskId}, event)`
+	 * loose-cast pattern entirely — the types now encode the linkage.
+	 */
+	private wrapChildListener(
+		listener: RunEventListener | undefined,
+		spawnRecord: ChildSpawnRecord | undefined,
+	): RunEventListener | undefined {
+		if (!listener) return undefined
+		if (!spawnRecord) return listener
+
+		const lineage: Lineage = {
+			parentSessionId: spawnRecord.parentSessionId,
+			rootSessionId: spawnRecord.rootSessionId,
+			depth: spawnRecord.childDepth,
+		}
+
+		return async (event: RunEvent): Promise<void> => {
+			const stamped: RunEvent = {
+				...(event as RunEvent),
+				lineage,
+				schemaVersion: RUN_EVENT_SCHEMA_VERSION,
+			} as RunEvent
+			await listener(stamped)
+		}
+	}
+
+	private async finalizeChild(agentTask: AgentTask, result: BaseAgentResult): Promise<void> {
+		const spawnRecord = this.spawnRecords.get(agentTask.taskId)
+
+		// Kernel terminalization (§8.1): Materializer seals the summary and
+		// atomically flips the child session active→idle. Only run when the
+		// child actually succeeded; failed sub-sessions skip materialization
+		// and transition the sub-session record to 'failed' (§5.5).
+		if (spawnRecord) {
+			const store = this.deps.sessionStore
+			try {
+				if (result.status === 'completed') {
+					const outcome: SessionSummaryOutcome = deriveOutcome(result)
+					const agentSummary = deriveAgentSummary(result)
+					const summary = await this.deps.summaryMaterializer.materialize({
+						sessionId: spawnRecord.childSessionId,
+						tenantId: spawnRecord.tenantId,
+						finalOutcome: outcome,
+						agentSummary,
+						declaredDeliverables: [],
+						keyDecisions: [],
 					})
-					await listener(annotated as import('../../types/run/events.js').RunEvent)
+
+					const subSession = await store.getSubSession(
+						spawnRecord.subSessionId,
+						spawnRecord.tenantId,
+					)
+					if (subSession) {
+						await store.updateSubSession(
+							{ ...subSession, status: 'idle', summaryRef: summary.id },
+							spawnRecord.tenantId,
+						)
+					}
+				} else {
+					// Non-success: mark sub-session failed and, when we own a
+					// workspace, dispose it. Dispose errors are logged but not
+					// propagated — the sub-session state is already persisted.
+					const subSession = await store.getSubSession(
+						spawnRecord.subSessionId,
+						spawnRecord.tenantId,
+					)
+					if (subSession) {
+						await store.updateSubSession({ ...subSession, status: 'failed' }, spawnRecord.tenantId)
+					}
+					if (spawnRecord.workspaceRef) {
+						const backend = spawnRecord.workspaceRef.meta.backend
+						if (this.deps.workspaceRegistry.has(backend)) {
+							await this.deps.workspaceRegistry
+								.get(backend)
+								.dispose(spawnRecord.workspaceRef)
+								.catch((disposeErr) => {
+									this.log.warn('Workspace dispose failed', {
+										backend,
+										error: toErrorMessage(disposeErr),
+									})
+								})
+						}
+					}
 				}
-			: undefined
+			} catch (err) {
+				this.log.error('Sub-session finalization failed', {
+					taskId: agentTask.taskId,
+					error: toErrorMessage(err),
+				})
+			}
+		}
+
+		// Emit subsession_idled event on success before marking the task
+		// completed — consumers expect the ordering `run_completed (child) →
+		// subsession_idled → run_completed (parent)` per §10.5.
+		if (spawnRecord && agentTask.runEventListener && result.status === 'completed') {
+			const lineage: Lineage = {
+				parentSessionId: spawnRecord.parentSessionId,
+				rootSessionId: spawnRecord.rootSessionId,
+				depth: spawnRecord.childDepth,
+			}
+			try {
+				await agentTask.runEventListener({
+					type: 'subsession_idled',
+					runId: agentTask.context.parentRunId,
+					subSessionId: spawnRecord.subSessionId,
+					parentSessionId: spawnRecord.parentSessionId,
+					lineage,
+					schemaVersion: RUN_EVENT_SCHEMA_VERSION,
+					at: new Date(),
+				})
+			} catch (err) {
+				this.log.error('subsession_idled emission error', {
+					taskId: agentTask.taskId,
+					error: toErrorMessage(err),
+				})
+			}
+		}
 
-		const result = await agentTask.agent.run(input, childConfig, childListener)
 		this.markCompleted(agentTask.taskId, result)
 	}
 
@@ -307,10 +642,45 @@ export class AgentManager {
 			error,
 		})
 		this.log.error(`Agent task failed: ${taskId}`, { error })
+
+		// Best-effort: mark sub-session failed + dispose workspace. The result
+		// emission path already synthesized a failure result above.
+		const spawnRecord = this.spawnRecords.get(taskId)
+		if (spawnRecord) {
+			this.failSubSession(spawnRecord).catch((err) => {
+				this.log.warn('SubSession failure update failed', {
+					taskId,
+					error: toErrorMessage(err),
+				})
+			})
+		}
+
 		this.scheduleEviction(taskId)
 		this.resolveCompletionCallbacks(taskId)
 	}
 
+	private async failSubSession(spawnRecord: ChildSpawnRecord): Promise<void> {
+		const subSession = await this.deps.sessionStore.getSubSession(
+			spawnRecord.subSessionId,
+			spawnRecord.tenantId,
+		)
+		if (subSession && subSession.status !== 'failed') {
+			await this.deps.sessionStore.updateSubSession(
+				{ ...subSession, status: 'failed' },
+				spawnRecord.tenantId,
+			)
+		}
+		if (spawnRecord.workspaceRef) {
+			const backend = spawnRecord.workspaceRef.meta.backend
+			if (this.deps.workspaceRegistry.has(backend)) {
+				await this.deps.workspaceRegistry
+					.get(backend)
+					.dispose(spawnRecord.workspaceRef)
+					.catch(() => undefined)
+			}
+		}
+	}
+
 	private markCanceled(taskId: TaskId): void {
 		const agentTask = this.instances.get(taskId)
 		if (!agentTask || isTerminalAgentTaskState(agentTask.state)) return
@@ -351,6 +721,7 @@ export class AgentManager {
 
 		const timer = setTimeout(() => {
 			this.instances.delete(taskId)
+			this.spawnRecords.delete(taskId)
 			this.evictionTimers.delete(taskId)
 			this.log.info(`Agent task evicted: ${taskId}`)
 		}, this.config.evictionMs)
@@ -387,10 +758,7 @@ export class AgentManager {
 		}
 	}
 
-	private emitRunEvent(
-		agentTask: AgentTask,
-		event: import('../../types/run/events.js').RunEvent,
-	): void {
+	private emitRunEvent(agentTask: AgentTask, event: RunEvent): void {
 		if (!agentTask.runEventListener) return
 		try {
 			agentTask.runEventListener(event)
@@ -403,3 +771,50 @@ export class AgentManager {
 		}
 	}
 }
+
+/**
+ * Maps a {@link BaseAgentResult} to {@link SessionSummaryOutcome}. Phase 6
+ * INTERPRETATION: `completed` → `succeeded`; any other status → `failed`.
+ * A dedicated `partial` signal requires structured-output contracts on the
+ * child's terminal turn (§8.1) which lands in a later phase.
+ */
+function deriveOutcome(result: BaseAgentResult): SessionSummaryOutcome {
+	if (result.status === 'completed') {
+		return { status: 'succeeded' }
+	}
+	const verdict = result.lastError ?? String(result.status)
+	return { status: 'failed', verdict }
+}
+
+const SUMMARY_FALLBACK_MAX_CHARS = 4000
+
+/**
+ * Pulls the agent's own narration from the final assistant message. §8.1:
+ * agents may register a structured-output contract for this; when absent
+ * we fall back to the last text block. Bounded by the summary char cap so
+ * the materializer never rejects on length at this seam.
+ */
+function deriveAgentSummary(result: BaseAgentResult): string {
+	const fromResult = result.result?.trim()
+	if (fromResult) {
+		return fromResult.length > SUMMARY_FALLBACK_MAX_CHARS
+			? fromResult.slice(0, SUMMARY_FALLBACK_MAX_CHARS)
+			: fromResult
+	}
+	for (let i = result.messages.length - 1; i >= 0; i--) {
+		const msg = result.messages[i]
+		if (msg?.role === 'assistant') {
+			const content = typeof msg.content === 'string' ? msg.content : ''
+			if (content.trim().length > 0) {
+				return content.length > SUMMARY_FALLBACK_MAX_CHARS
+					? content.slice(0, SUMMARY_FALLBACK_MAX_CHARS)
+					: content
+			}
+		}
+	}
+	return ''
+}
+
+// Re-export the capacity-violation type so downstream consumers that import
+// via the AgentManager module surface don't reach into session/handoff/.
+export { DelegationCapacityExceeded }

package/src/manager/run/persistence.ts

@@ -1,10 +1,11 @@
 import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
 import { RunDiskStore } from '../../store/run/disk.js'
 import { type CostInfo, type TokenUsage, accumulateTokenUsage } from '../../types/common/index.js'
-import type { RunId } from '../../types/ids/index.js'
+import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { AssistantMessage, Message } from '../../types/message/index.js'
 import type { EmergencySaveData } from '../../types/run/emergency.js'
 import type { AgentRun, RunPersistenceConfig, StopReason } from '../../types/run/index.js'
+import type { ProjectId } from '../../types/session/ids.js'
 import { type ModelPricing, ZERO_COST, accumulateCost } from '../../utils/cost.js'
 import { generateEmergencySaveId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
@@ -14,10 +15,16 @@ export class RunPersistence {
 	private runStore: RunDiskStore
 	private pricing?: ModelPricing
 	private log: Logger
+	private readonly _sessionId: SessionId
+	private readonly _tenantId: TenantId
+	private readonly _projectId: ProjectId
 
 	constructor(config: RunPersistenceConfig) {
 		this.pricing = config.pricing
 		this.log = config.log
+		this._sessionId = config.sessionId
+		this._tenantId = config.tenantId
+		this._projectId = config.projectId
 
 		this.runStore = new RunDiskStore({
 			baseDir: config.outputDir,
@@ -47,6 +54,18 @@ export class RunPersistence {
 		return this.run.id
 	}
 
+	get sessionId(): SessionId {
+		return this._sessionId
+	}
+
+	get tenantId(): TenantId {
+		return this._tenantId
+	}
+
+	get projectId(): ProjectId {
+		return this._projectId
+	}
+
 	get status() {
 		return this.run.status
 	}

package/src/run/reporter.ts

@@ -194,6 +194,34 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'subsession_spawned':
+				log.debug('Sub-session spawned', {
+					runId: event.runId,
+					subSessionId: event.subSessionId,
+					parentSessionId: event.parentSessionId,
+					depth: event.lineage.depth,
+				})
+				break
+
+			case 'subsession_messaged':
+				log.debug('Sub-session message', {
+					runId: event.runId,
+					subSessionId: event.subSessionId,
+					parentSessionId: event.parentSessionId,
+					messageId: event.messageId,
+					depth: event.lineage.depth,
+				})
+				break
+
+			case 'subsession_idled':
+				log.debug('Sub-session idled', {
+					runId: event.runId,
+					subSessionId: event.subSessionId,
+					parentSessionId: event.parentSessionId,
+					depth: event.lineage.depth,
+				})
+				break
+
 			default: {
 				const _exhaustive: never = event
 				throw new Error(`Unhandled run event type: ${(_exhaustive as RunEvent).type}`)