@namzu/sdk 0.1.7 → 0.2.0

package/src/runtime/query/__tests__/context.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from 'vitest'
+import { DefaultPathBuilder, type PathBuilder } from '../../../session/workspace/path-builder.js'
+import type { RunId, SessionId, TenantId } from '../../../types/ids/index.js'
+import type { LLMProvider } from '../../../types/provider/index.js'
+import type { AgentRunConfig } from '../../../types/run/index.js'
+import type { ProjectId } from '../../../types/session/ids.js'
+import { RunContextFactory } from '../context.js'
+
+function mockProvider(): LLMProvider {
+	return {
+		id: 'mock',
+		supports: () => true,
+		chat: async () => ({ message: { role: 'assistant', content: '' } }),
+	} as unknown as LLMProvider
+}
+
+function buildConfig(overrides: Partial<Parameters<typeof RunContextFactory.build>[0]> = {}) {
+	const sessionId = 'ses_test' as SessionId
+	const projectId = 'prj_test' as ProjectId
+	const tenantId = 'tnt_test' as TenantId
+	const runConfig: AgentRunConfig = {
+		model: 'test',
+		tokenBudget: 1_000,
+		timeoutMs: 5_000,
+	}
+
+	return {
+		agentId: 'agent-1',
+		agentName: 'agent-1',
+		runConfig,
+		provider: mockProvider(),
+		messages: [],
+		sessionId,
+		projectId,
+		tenantId,
+		workingDirectory: '/tmp/run-context-test',
+		...overrides,
+	}
+}
+
+describe('RunContextFactory.build — Phase 6', () => {
+	it('requires sessionId, projectId, tenantId and returns them on the context', () => {
+		const cfg = buildConfig()
+		const ctx = RunContextFactory.build(cfg)
+
+		expect(ctx.sessionId).toBe(cfg.sessionId)
+		expect(ctx.projectId).toBe(cfg.projectId)
+		expect(ctx.tenantId).toBe(cfg.tenantId)
+		// threadId remains as a deprecated mirror of projectId.
+		expect(ctx.threadId).toBe(cfg.projectId)
+	})
+
+	it('uses the injected PathBuilder to resolve the output dir (no hardcoded .namzu/threads)', () => {
+		const pathBuilderMock: PathBuilder = {
+			rootDir: vi.fn(() => '/mock/root'),
+			projectDir: vi.fn((pid) => `/mock/root/projects/${pid}`),
+			sessionDir: vi.fn((pid, sid) => `/mock/root/projects/${pid}/sessions/${sid}`),
+			subSessionDir: vi.fn(),
+			runDir: vi.fn(),
+		}
+
+		const cfg = buildConfig({ pathBuilder: pathBuilderMock })
+		const ctx = RunContextFactory.build(cfg)
+
+		expect(pathBuilderMock.sessionDir).toHaveBeenCalledWith(cfg.projectId, cfg.sessionId)
+		expect(ctx.outputDir).toBe(`/mock/root/projects/${cfg.projectId}/sessions/${cfg.sessionId}`)
+		// Legacy hardcoded path must not leak.
+		expect(ctx.outputDir).not.toContain('.namzu/threads')
+	})
+
+	it('falls back to DefaultPathBuilder rooted at {cwd}/.namzu when no pathBuilder is provided', () => {
+		const cfg = buildConfig()
+		const ctx = RunContextFactory.build(cfg)
+
+		// No more `/.namzu/threads/{threadId}/runs` — the new layout lives under
+		// projects/{pid}/sessions/{sid}.
+		expect(ctx.outputDir).toContain('/.namzu/projects/prj_test/sessions/ses_test')
+		expect(ctx.outputDir).not.toContain('threads')
+	})
+
+	it('seeds RunPersistence with propagated sessionId/tenantId/projectId', () => {
+		const cfg = buildConfig()
+		const ctx = RunContextFactory.build(cfg)
+
+		expect(ctx.runMgr.sessionId).toBe(cfg.sessionId)
+		expect(ctx.runMgr.tenantId).toBe(cfg.tenantId)
+		expect(ctx.runMgr.projectId).toBe(cfg.projectId)
+	})
+
+	it('reuses the runId supplied by the caller', () => {
+		const runId = 'run_fixed' as RunId
+		const ctx = RunContextFactory.build(buildConfig({ runId }))
+		expect(ctx.runId).toBe(runId)
+	})
+
+	it('DefaultPathBuilder lays out runs under sessions/{sessionId}/runs', () => {
+		const builder = new DefaultPathBuilder('/base/.namzu')
+		const runDir = builder.runDir('prj_x' as ProjectId, 'ses_y' as SessionId, 'run_z' as RunId)
+		expect(runDir).toBe('/base/.namzu/projects/prj_x/sessions/ses_y/runs/run_z')
+	})
+})

package/src/runtime/query/context.ts

@@ -1,17 +1,44 @@
 import { join } from 'node:path'
 import { PlanManager } from '../../manager/plan/lifecycle.js'
 import { RunPersistence } from '../../manager/run/persistence.js'
+import {
+	DefaultFilesystemMigrator,
+	type FilesystemMigrationResult,
+	type FilesystemMigrationSink,
+	type FilesystemMigrator,
+	NOOP_FILESYSTEM_MIGRATION_SINK,
+} from '../../session/migration/index.js'
+import { DefaultPathBuilder, type PathBuilder } from '../../session/workspace/path-builder.js'
 import { ActivityStore } from '../../store/activity/memory.js'
 import { type ActivityTrackingConfig, resolveActivityTracking } from '../../types/activity/index.js'
-import type { RunId, ThreadId } from '../../types/ids/index.js'
+import type { RunId, SessionId, TenantId, ThreadId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
 import type { PermissionMode } from '../../types/permission/index.js'
 import type { LLMProvider } from '../../types/provider/index.js'
 import type { AgentRunConfig } from '../../types/run/index.js'
+import type { ProjectId } from '../../types/session/ids.js'
 import type { ModelPricing } from '../../utils/cost.js'
 import { generateRunId } from '../../utils/id.js'
 import { type Logger, getRootLogger } from '../../utils/logger.js'
 
+/**
+ * Config accepted by {@link RunContextFactory.build}. Phase 6 promotes
+ * `sessionId`, `projectId`, and `tenantId` to required — runs are scoped
+ * under a Session within a Project within a Tenant (session-hierarchy.md
+ * §12.1). `threadId` is retained only as a deprecated compat alias of
+ * `projectId` — consumers can still pass it, but no new path layout honors it.
+ *
+ * `pathBuilder` is optional; when absent a {@link DefaultPathBuilder} is
+ * constructed against `{workingDirectory}/.namzu` — no more hardcoded
+ * `.namzu/threads` path.
+ *
+ * Phase 7 adds `filesystemMigrator` + `migrationSink`. These are also
+ * optional; when absent a {@link DefaultFilesystemMigrator} wired to the
+ * {@link NOOP_FILESYSTEM_MIGRATION_SINK} is used. Migration runs once per
+ * process via {@link RunContextFactory.ensureMigrated}; the static `build`
+ * method stays synchronous so existing call sites are not broken — async
+ * callers (e.g. `query()`) invoke `ensureMigrated` themselves before build.
+ */
 export interface RunContextConfig {
 	agentId: string
 	agentName: string
@@ -23,7 +50,21 @@ export interface RunContextConfig {
 	messages: Message[]
 	signal?: AbortSignal
 
-	threadId: ThreadId
+	sessionId: SessionId
+	projectId: ProjectId
+	tenantId: TenantId
+
+	pathBuilder?: PathBuilder
+
+	/**
+	 * Optional injected migrator — tests pass a stub; production code relies
+	 * on the {@link DefaultFilesystemMigrator}. See session-hierarchy.md
+	 * §13.4.1.
+	 */
+	filesystemMigrator?: FilesystemMigrator
+
+	/** Optional sink for `filesystem.migrated` events. Defaults to no-op. */
+	migrationSink?: FilesystemMigrationSink
 
 	runId?: RunId
 
@@ -32,8 +73,20 @@ export interface RunContextConfig {
 	depth?: number
 }
 
+/**
+ * Result of {@link RunContextFactory.build}. `threadId` remains as a
+ * deprecated read-only mirror of `projectId` for consumers still referencing
+ * the old name — scheduled for removal in 0.3.0 (session-hierarchy.md §13.1).
+ */
 export interface RunContext {
 	runId: RunId
+	sessionId: SessionId
+	projectId: ProjectId
+	tenantId: TenantId
+	/**
+	 * @deprecated Mirrors `projectId` — remove when callers migrate off the
+	 * legacy name.
+	 */
 	threadId: ThreadId
 	runMgr: RunPersistence
 	activityStore: ActivityStore
@@ -46,7 +99,44 @@ export interface RunContext {
 	trackingConfig: ActivityTrackingConfig
 }
 
+/**
+ * Module-level first-call guard for the boot-time filesystem migration
+ * (session-hierarchy.md §13.4.1). Keyed on the root directory so a single
+ * process that spans multiple `.namzu` roots (unusual but legal) migrates
+ * each one once. Subsequent calls short-circuit via the cached promise —
+ * never re-reading the on-disk marker per call.
+ */
+const migrationPromises = new Map<string, Promise<FilesystemMigrationResult>>()
+
+/** Testing hook — clears the first-call guard cache. */
+export function __resetMigrationGuardForTests(): void {
+	migrationPromises.clear()
+}
+
 export class RunContextFactory {
+	/**
+	 * Run the boot-time filesystem migration for `rootDir` at most once per
+	 * process. Safe to `await` from any async entry point; concurrent callers
+	 * for the same root share a single migration promise (no duplicate work,
+	 * no race with the on-disk `.tmp` lock).
+	 */
+	static ensureMigrated(
+		rootDir: string,
+		migrator: FilesystemMigrator = new DefaultFilesystemMigrator(NOOP_FILESYSTEM_MIGRATION_SINK),
+	): Promise<FilesystemMigrationResult> {
+		const cached = migrationPromises.get(rootDir)
+		if (cached) return cached
+		const promise = migrator.migrate(rootDir)
+		migrationPromises.set(rootDir, promise)
+		// Crash-safety: if the migration rejects, drop the cached promise so
+		// the next caller gets a fresh attempt. Successful results stay cached
+		// (idempotency — further calls short-circuit without re-running).
+		promise.catch(() => {
+			migrationPromises.delete(rootDir)
+		})
+		return promise
+	}
+
 	static build(config: RunContextConfig): RunContext {
 		const abortController = new AbortController()
 		if (config.signal) {
@@ -57,17 +147,17 @@ export class RunContextFactory {
 		const permissionMode = config.runConfig.permissionMode ?? 'auto'
 		const runId = config.runId ?? generateRunId()
 
-		if (!config.threadId) {
-			throw new Error('threadId is required for run persistence — all runs must belong to a thread')
-		}
-		const threadId: ThreadId = config.threadId
-		const outputDir = join(cwd, '.namzu', 'threads', threadId, 'runs')
+		const pathBuilder = config.pathBuilder ?? new DefaultPathBuilder(join(cwd, '.namzu'))
+		const outputDir = pathBuilder.sessionDir(config.projectId, config.sessionId)
+		const runsDir = join(outputDir, 'runs')
 
 		const log = getRootLogger().child({
 			component: 'query',
 			agent: config.agentName,
 			runId,
-			threadId,
+			sessionId: config.sessionId,
+			projectId: config.projectId,
+			tenantId: config.tenantId,
 		})
 
 		const runMgr = new RunPersistence({
@@ -76,9 +166,12 @@ export class RunContextFactory {
 			agentName: config.agentName,
 			runConfig: config.runConfig,
 			providerId: config.provider.id,
-			outputDir,
+			outputDir: runsDir,
 			pricing: config.pricing,
 			log,
+			sessionId: config.sessionId,
+			tenantId: config.tenantId,
+			projectId: config.projectId,
 			parentRunId: config.parentRunId,
 			depth: config.depth,
 		})
@@ -89,7 +182,10 @@ export class RunContextFactory {
 
 		return {
 			runId,
-			threadId,
+			sessionId: config.sessionId,
+			projectId: config.projectId,
+			tenantId: config.tenantId,
+			threadId: config.projectId as ThreadId,
 			runMgr,
 			activityStore,
 			planManager,

package/src/runtime/query/events.ts

@@ -80,6 +80,10 @@ export class EventTranslator {
 					})
 					break
 				default: {
+					// `TaskEvent.type` is scoped to task-store events; sub-session
+					// lifecycle events (subsession_spawned / _messaged / _idled) and
+					// run-scoped `RunEvent` variants never reach this wrapper. The
+					// exhaustiveness guard below enforces that at compile time.
 					const _exhaustive: never = event.type
 					throw new Error(`Unhandled task event type: ${_exhaustive}`)
 				}
@@ -134,6 +138,10 @@ export class EventTranslator {
 				case 'plan.failed':
 					break
 				default: {
+					// `PlanEvent.type` is scoped to plan-manager events; sub-session
+					// lifecycle events and other `RunEvent` variants never reach this
+					// wrapper. The exhaustiveness guard below enforces that at compile
+					// time.
 					const _exhaustive: never = event.type
 					throw new Error(`Unhandled plan event type: ${_exhaustive}`)
 				}

package/src/runtime/query/index.ts

@@ -8,6 +8,7 @@ import { extractFromUserMessage } from '../../compaction/extractor.js'
 import { WorkingStateManager } from '../../compaction/manager.js'
 import type { CompactionConfig } from '../../config/runtime.js'
 import { getTracer } from '../../provider/telemetry/setup.js'
+import type { PathBuilder } from '../../session/workspace/path-builder.js'
 import { GENAI, NAMZU, agentRunSpanName } from '../../telemetry/attributes.js'
 import { buildAdvisoryTools } from '../../tools/advisory/index.js'
 import { SearchToolsTool } from '../../tools/builtins/search-tools.js'
@@ -20,7 +21,7 @@ import {
 	type ResumeHandler,
 	autoApproveHandler,
 } from '../../types/hitl/index.js'
-import type { RunId, ThreadId } from '../../types/ids/index.js'
+import type { RunId, SessionId, TenantId, ThreadId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import { type Message, createSystemMessage } from '../../types/message/index.js'
 import type { AgentPersona } from '../../types/persona/index.js'
@@ -28,6 +29,7 @@ import type { LLMProvider } from '../../types/provider/index.js'
 import type { TaskRouterConfig } from '../../types/router/index.js'
 import type { AgentRun, AgentRunConfig, RunEvent, RunEventListener } from '../../types/run/index.js'
 import type { Sandbox, SandboxProvider } from '../../types/sandbox/index.js'
+import type { ProjectId } from '../../types/session/ids.js'
 import type { Skill } from '../../types/skills/index.js'
 import type { TaskStore } from '../../types/task/index.js'
 import type { ToolRegistryContract } from '../../types/tool/index.js'
@@ -65,7 +67,32 @@ export interface QueryParams {
 	resumeHandler: ResumeHandler
 	resumeFromCheckpoint?: CheckpointId
 
-	threadId: ThreadId
+	/**
+	 * Session scope for the run. Required in 0.2.0 — every run is attributed to
+	 * a Session (session-hierarchy.md §12.1).
+	 */
+	sessionId: SessionId
+
+	/** Long-lived goal scope for the run. Required. */
+	projectId: ProjectId
+
+	/** Isolation boundary. Required. */
+	tenantId: TenantId
+
+	/**
+	 * @deprecated Pass `projectId` instead. When both are present, `projectId`
+	 * wins. During the 0.2.x migration window a caller supplying only
+	 * `threadId` must also supply `projectId` — the kernel no longer infers
+	 * `projectId` from a bare `threadId` on the QueryParams shape.
+	 */
+	threadId?: ThreadId
+
+	/**
+	 * Optional path layout override. Defaults to a {@link DefaultPathBuilder}
+	 * rooted at `{workingDirectory}/.namzu` (§13.4). Phase 7 wires first-call
+	 * filesystem migration onto this same entry point.
+	 */
+	pathBuilder?: PathBuilder
 
 	runId?: RunId
 
@@ -112,6 +139,14 @@ export interface QueryParams {
 }
 
 export async function* query(params: QueryParams): AsyncGenerator<RunEvent, AgentRun> {
+	// Boot-time filesystem migration (session-hierarchy.md §13.4.1). First
+	// call per process per root actually runs; subsequent calls short-circuit
+	// via the in-memory guard in `context.ts`. Kept here rather than inside
+	// the synchronous `RunContextFactory.build` so the factory signature stays
+	// sync for tests / non-async call sites.
+	const cwdForMigration = params.workingDirectory ?? process.cwd()
+	await RunContextFactory.ensureMigrated(`${cwdForMigration}/.namzu`)
+
 	const ctx = RunContextFactory.build({
 		agentId: params.agentId,
 		agentName: params.agentName,
@@ -122,7 +157,10 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Agen
 		enableActivityTracking: params.enableActivityTracking,
 		messages: params.messages,
 		signal: params.signal,
-		threadId: params.threadId,
+		sessionId: params.sessionId,
+		projectId: params.projectId,
+		tenantId: params.tenantId,
+		pathBuilder: params.pathBuilder,
 		runId: params.runId,
 		parentRunId: params.parentRunId,
 		depth: params.depth,

package/src/session/__tests__/integration/_fixtures.ts

@@ -0,0 +1,282 @@
+/**
+ * Shared test fixtures for the Task 10 integration coverage matrix.
+ *
+ * Factors out the `AgentManager` + `SessionStore` + `WorkspaceBackendRegistry`
+ * + `SessionSummaryMaterializer` + `DefaultCapacityValidator` wiring that
+ * every integration test rebuilds. Keeping this in an underscore-prefixed
+ * internal module (Convention #4: `_fixtures.ts` does not bleed into any
+ * barrel) lets the 11 integration files focus on invariant assertions rather
+ * than boilerplate.
+ *
+ * DO NOT export from `src/session/index.ts` or any other public barrel.
+ * This module is test-only and has no runtime consumers.
+ */
+
+import { vi } from 'vitest'
+import { EMPTY_TOKEN_USAGE } from '../../../constants/limits.js'
+import { AgentManager } from '../../../manager/agent/lifecycle.js'
+import { AgentRegistry } from '../../../registry/agent/definitions.js'
+import { InMemorySessionStore } from '../../../store/session/memory.js'
+import type {
+	AgentCapabilities,
+	AgentInput,
+	BaseAgentConfig,
+	BaseAgentResult,
+} from '../../../types/agent/base.js'
+import type { Agent } from '../../../types/agent/core.js'
+import type { AgentDefinition } from '../../../types/agent/factory.js'
+import type { AgentTaskContext, SendMessageOptions } from '../../../types/agent/task.js'
+import type { AgentId, RunId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
+import { createAssistantMessage } from '../../../types/message/index.js'
+import type { ProjectId, SummaryId } from '../../../types/session/ids.js'
+import { ZERO_COST } from '../../../utils/cost.js'
+import { DefaultCapacityValidator } from '../../handoff/capacity.js'
+import type { ActorRef } from '../../hierarchy/actor.js'
+import type { Session } from '../../hierarchy/session.js'
+import { SessionSummaryMaterializer } from '../../summary/materialize.js'
+import type { ExecFile, ExecFileResult } from '../../workspace/git-worktree.js'
+import { GitWorktreeDriver } from '../../workspace/git-worktree.js'
+import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
+
+export const DEFAULT_TENANT = 'tnt_alpha' as TenantId
+export const OTHER_TENANT = 'tnt_beta' as TenantId
+
+export function stubLogger() {
+	return {
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		child() {
+			return stubLogger()
+		},
+	}
+}
+
+export function okExec(stdout = '', stderr = ''): ExecFileResult {
+	return { stdout, stderr }
+}
+
+export function userActor(userId: string, tenantId: TenantId = DEFAULT_TENANT): ActorRef {
+	return { kind: 'user', userId: userId as UserId, tenantId }
+}
+
+export function agentActor(agentId: string, tenantId: TenantId = DEFAULT_TENANT): ActorRef {
+	return { kind: 'agent', agentId: agentId as AgentId, tenantId }
+}
+
+const BASE_CAPABILITIES: AgentCapabilities = {
+	supportsTools: false,
+	supportsStreaming: false,
+	supportsConcurrency: false,
+	supportsSubAgents: false,
+}
+
+/**
+ * Builds a minimal {@link Agent} whose `run` produces a deterministic
+ * assistant message. Tests that need custom output shape override via
+ * {@link buildAgentCustom}.
+ */
+export function buildAgent(
+	id: string,
+	result = 'child did the work',
+): Agent<BaseAgentConfig, BaseAgentResult> {
+	return {
+		type: 'reactive',
+		metadata: {
+			type: 'reactive',
+			id,
+			name: id,
+			version: '1.0.0',
+			category: 'test',
+			description: id,
+			capabilities: BASE_CAPABILITIES,
+		},
+		run: async (_input: AgentInput, _config: BaseAgentConfig): Promise<BaseAgentResult> => ({
+			runId: `run_${id}_result` as RunId,
+			status: 'completed',
+			usage: { ...EMPTY_TOKEN_USAGE },
+			cost: { ...ZERO_COST },
+			iterations: 1,
+			durationMs: 1,
+			messages: [createAssistantMessage(result)],
+			result,
+		}),
+		cancel: async () => undefined,
+		getCapabilities: () => BASE_CAPABILITIES,
+	}
+}
+
+/**
+ * Builds an agent with a caller-supplied `run`. Useful for tests that need
+ * to simulate failures or spawn cascading agents.
+ */
+export function buildAgentCustom(
+	id: string,
+	run: Agent<BaseAgentConfig, BaseAgentResult>['run'],
+): Agent<BaseAgentConfig, BaseAgentResult> {
+	return {
+		type: 'reactive',
+		metadata: {
+			type: 'reactive',
+			id,
+			name: id,
+			version: '1.0.0',
+			category: 'test',
+			description: id,
+			capabilities: BASE_CAPABILITIES,
+		},
+		run,
+		cancel: async () => undefined,
+		getCapabilities: () => BASE_CAPABILITIES,
+	}
+}
+
+export function buildDefinition(agent: Agent<BaseAgentConfig, BaseAgentResult>): AgentDefinition {
+	return {
+		info: {
+			id: agent.metadata.id,
+			name: agent.metadata.name,
+			version: agent.metadata.version,
+			category: agent.metadata.category,
+			description: agent.metadata.description,
+			tools: [],
+			defaults: { model: 'test', tokenBudget: 1_000 },
+		},
+		typedAgent: agent,
+	}
+}
+
+export interface IntegrationHarness {
+	readonly store: InMemorySessionStore
+	readonly registry: AgentRegistry
+	readonly manager: AgentManager
+	readonly materializer: SessionSummaryMaterializer
+	readonly workspaceRegistry: WorkspaceBackendRegistry
+	readonly capacity: DefaultCapacityValidator
+	readonly tenantId: TenantId
+}
+
+export interface IntegrationHarnessOptions {
+	readonly tenantId?: TenantId
+	/** Pass `true` to register a no-op stubbed git-worktree driver. */
+	readonly withWorktreeDriver?: boolean
+	readonly execFile?: ExecFile
+	/**
+	 * Deterministic summary ID generator — defaults to `sum_test_<n>`. Tests
+	 * asserting on the exact id should override.
+	 */
+	readonly summaryIdGenerator?: () => SummaryId
+}
+
+/**
+ * Builds a full AgentManager + SessionStore + Materializer harness wired with
+ * real components (not mocks). The `GitWorktreeDriver` uses a stubbed
+ * `execFile` that returns empty stdout by default — tests exercising failure
+ * modes inject a real {@link ExecFile}.
+ */
+export function buildHarness(options: IntegrationHarnessOptions = {}): IntegrationHarness {
+	const tenantId = options.tenantId ?? DEFAULT_TENANT
+	const store = new InMemorySessionStore()
+
+	const workspaceRegistry = new WorkspaceBackendRegistry()
+	if (options.withWorktreeDriver !== false) {
+		const exec: ExecFile = options.execFile ?? (async () => okExec())
+		const driver = new GitWorktreeDriver({
+			repoRoot: '/repo',
+			logger: stubLogger(),
+			execFile: exec,
+		})
+		workspaceRegistry.register(driver)
+	}
+
+	let counter = 0
+	const generateSummaryId =
+		options.summaryIdGenerator ?? (() => `sum_test_${++counter}` as SummaryId)
+
+	const materializer = new SessionSummaryMaterializer({
+		store,
+		generateSummaryId,
+	})
+
+	const capacity = new DefaultCapacityValidator(store)
+	const registry = new AgentRegistry()
+	const manager = new AgentManager(registry, undefined, {
+		sessionStore: store,
+		summaryMaterializer: materializer,
+		workspaceRegistry,
+		capacity,
+	})
+
+	return { store, registry, manager, materializer, workspaceRegistry, capacity, tenantId }
+}
+
+/**
+ * Seeds a Tenant → Project → Session triple and flips the session into
+ * `active` so it is a legal spawn parent. Returns the project + active
+ * session for the caller to drive spawns against.
+ */
+export async function seedActiveParent(
+	harness: IntegrationHarness,
+	options?: { actor?: ActorRef; projectName?: string; tenantId?: TenantId },
+) {
+	const tenantId = options?.tenantId ?? harness.tenantId
+	const actor: ActorRef = options?.actor ?? userActor('usr_root', tenantId)
+	const project = await harness.store.createProject(
+		{ tenantId, name: options?.projectName ?? 'integration-project' },
+		tenantId,
+	)
+	const session = await harness.store.createSession(
+		{ projectId: project.id, currentActor: actor },
+		tenantId,
+	)
+	await harness.store.updateSession({ ...session, status: 'active' as Session['status'] }, tenantId)
+	return { project, session, actor }
+}
+
+/**
+ * Constructs a fully populated {@link AgentTaskContext} bound to the supplied
+ * parent session + actor. Tests override individual fields (depth, budget)
+ * by merging.
+ */
+export function buildTaskContext(params: {
+	sessionId: SessionId
+	projectId: ProjectId
+	tenantId: TenantId
+	parentActor: ActorRef
+	depth?: number
+	budget?: number
+	parentRunId?: RunId
+}): AgentTaskContext {
+	return {
+		parentRunId: params.parentRunId ?? ('run_parent' as RunId),
+		parentAgentId: 'supervisor',
+		parentAbortController: new AbortController(),
+		depth: params.depth ?? 0,
+		budgetTracker: {
+			total: params.budget ?? 100_000,
+			remaining: params.budget ?? 100_000,
+		},
+		tenantId: params.tenantId,
+		sessionId: params.sessionId,
+		projectId: params.projectId,
+		parentActor: params.parentActor,
+	}
+}
+
+export function buildSendMessageOptions(params: {
+	agentId: string
+	parentSessionId: SessionId
+	projectId: ProjectId
+	tenantId: TenantId
+	parentActor: ActorRef
+}): SendMessageOptions {
+	return {
+		agentId: params.agentId,
+		input: { messages: [], workingDirectory: '/tmp' },
+		parentSessionId: params.parentSessionId,
+		tenantId: params.tenantId,
+		projectId: params.projectId,
+		parentActor: params.parentActor,
+	}
+}