@namzu/sdk 0.4.1 → 0.4.3

package/src/runtime/query/replay/__tests__/prepare.test.ts

@@ -0,0 +1,207 @@
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import type { CheckpointId, IterationCheckpoint } from '../../../../types/hitl/index.js'
+import type { EmergencySaveId, RunId, ToolCallId } from '../../../../types/ids/index.js'
+import type { AssistantMessage, ToolMessage } from '../../../../types/message/index.js'
+import type { EmergencySaveData } from '../../../../types/run/emergency.js'
+import type { Mutation } from '../../../../types/run/replay.js'
+import { prepareReplayState } from '../prepare.js'
+
+const RUN_ID = 'run_source' as RunId
+
+function makeCheckpoint(overrides: Partial<IterationCheckpoint>): IterationCheckpoint {
+	return {
+		id: 'cp_default' as CheckpointId,
+		runId: RUN_ID,
+		iteration: 1,
+		messages: [{ role: 'user', content: 'hi' }],
+		tokenUsage: {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		},
+		costInfo: { inputCostPer1M: 0, outputCostPer1M: 0, totalCost: 0, cacheDiscount: 0 },
+		guardState: { iterationCount: 1, elapsedMs: 0 },
+		createdAt: Date.now(),
+		...overrides,
+	}
+}
+
+async function seedCheckpoint(baseDir: string, cp: IterationCheckpoint): Promise<void> {
+	const cpDir = join(baseDir, cp.runId, 'checkpoints')
+	await mkdir(cpDir, { recursive: true })
+	await writeFile(join(cpDir, `${cp.id}.json`), JSON.stringify(cp), 'utf-8')
+}
+
+async function seedEmergency(emergencyDir: string, dump: EmergencySaveData): Promise<void> {
+	await mkdir(emergencyDir, { recursive: true })
+	await writeFile(join(emergencyDir, `${dump.runId}.json`), JSON.stringify(dump), 'utf-8')
+}
+
+describe('prepareReplayState', () => {
+	let baseDir: string
+	let emergencyDir: string
+
+	beforeEach(async () => {
+		const wrapper = await mkdtemp(join(tmpdir(), 'namzu-prepare-replay-'))
+		baseDir = join(wrapper, 'runs')
+		emergencyDir = join(wrapper, 'emergency')
+		await mkdir(baseDir, { recursive: true })
+	})
+
+	afterEach(async () => {
+		// Per-test tmpdir isolation; vitest cleans tmpdir between runs.
+	})
+
+	it('resolves a specific CheckpointId and returns the checkpoint messages', async () => {
+		const cp = makeCheckpoint({
+			id: 'cp_one' as CheckpointId,
+			iteration: 3,
+			messages: [
+				{ role: 'user', content: 'start' },
+				{ role: 'assistant', content: 'ok' },
+			],
+		})
+		await seedCheckpoint(baseDir, cp)
+
+		const prepared = await prepareReplayState({
+			baseDir,
+			runId: RUN_ID,
+			fromCheckpoint: 'cp_one' as CheckpointId,
+		})
+
+		expect(prepared.sourceCheckpoint.id).toBe('cp_one')
+		expect(prepared.messages).toEqual(cp.messages)
+		expect(prepared.attribution.sourceRunId).toBe(RUN_ID)
+		expect(prepared.attribution.fromCheckpointId).toBe('cp_one')
+		expect(prepared.attribution.mutations).toEqual([])
+		expect(prepared.attribution.replayedAt).toBeGreaterThan(0)
+	})
+
+	it("resolves 'latest' to the checkpoint with the highest iteration", async () => {
+		await seedCheckpoint(baseDir, makeCheckpoint({ id: 'cp_a' as CheckpointId, iteration: 1 }))
+		await seedCheckpoint(baseDir, makeCheckpoint({ id: 'cp_b' as CheckpointId, iteration: 5 }))
+		await seedCheckpoint(baseDir, makeCheckpoint({ id: 'cp_c' as CheckpointId, iteration: 3 }))
+
+		const prepared = await prepareReplayState({
+			baseDir,
+			runId: RUN_ID,
+			fromCheckpoint: 'latest',
+		})
+
+		expect(prepared.sourceCheckpoint.id).toBe('cp_b')
+		expect(prepared.sourceCheckpoint.iteration).toBe(5)
+	})
+
+	it("throws when 'latest' is requested but no checkpoints exist", async () => {
+		await expect(
+			prepareReplayState({
+				baseDir,
+				runId: RUN_ID,
+				fromCheckpoint: 'latest',
+			}),
+		).rejects.toThrow(/No checkpoints found/)
+	})
+
+	it('throws when a specific CheckpointId does not resolve', async () => {
+		await expect(
+			prepareReplayState({
+				baseDir,
+				runId: RUN_ID,
+				fromCheckpoint: 'cp_missing' as CheckpointId,
+			}),
+		).rejects.toThrow(/not found/)
+	})
+
+	it('applies injectToolResponse mutations at the fork point', async () => {
+		const assistantMsg: AssistantMessage = {
+			role: 'assistant',
+			content: null,
+			toolCalls: [{ id: 'call_a', type: 'function', function: { name: 'noop', arguments: '{}' } }],
+		}
+		const cp = makeCheckpoint({
+			id: 'cp_with_tool' as CheckpointId,
+			messages: [{ role: 'user', content: 'run tool' }, assistantMsg],
+		})
+		await seedCheckpoint(baseDir, cp)
+
+		const mutations: Mutation[] = [
+			{
+				type: 'injectToolResponse',
+				toolCallId: 'call_a' as ToolCallId,
+				response: { success: true, output: 'mocked-a' },
+			},
+		]
+
+		const prepared = await prepareReplayState({
+			baseDir,
+			runId: RUN_ID,
+			fromCheckpoint: 'cp_with_tool' as CheckpointId,
+			mutate: mutations,
+		})
+
+		expect(prepared.messages).toHaveLength(3)
+		const appended = prepared.messages[2] as ToolMessage
+		expect(appended.role).toBe('tool')
+		expect(appended.toolCallId).toBe('call_a')
+		expect(appended.content).toBe('mocked-a')
+		expect(prepared.attribution.mutations).toEqual(mutations)
+	})
+
+	it("resolves 'emergency' via the emergency dump and projects it to a checkpoint", async () => {
+		const dump: EmergencySaveData = {
+			id: 'esave_xyz' as EmergencySaveId,
+			runId: RUN_ID,
+			messages: [{ role: 'user', content: 'before crash' }],
+			tokenUsage: {
+				promptTokens: 4,
+				completionTokens: 2,
+				totalTokens: 6,
+				cachedTokens: 0,
+				cacheWriteTokens: 0,
+			},
+			currentIteration: 9,
+			startedAt: 1_000,
+			savedAt: 2_000,
+			processSignal: 'SIGTERM',
+		}
+		await seedEmergency(emergencyDir, dump)
+
+		const prepared = await prepareReplayState({
+			baseDir,
+			runId: RUN_ID,
+			fromCheckpoint: 'emergency',
+			emergencyDir,
+		})
+
+		expect(prepared.sourceCheckpoint.id).toBe('cp_emergency_xyz')
+		expect(prepared.sourceCheckpoint.iteration).toBe(9)
+		expect(prepared.messages).toEqual(dump.messages)
+		expect(prepared.attribution.fromCheckpointId).toBe('cp_emergency_xyz')
+	})
+
+	it("throws when 'emergency' is requested without emergencyDir", async () => {
+		await expect(
+			prepareReplayState({
+				baseDir,
+				runId: RUN_ID,
+				fromCheckpoint: 'emergency',
+			}),
+		).rejects.toThrow(/emergencyDir/)
+	})
+
+	it("throws when 'emergency' dump file is missing", async () => {
+		await expect(
+			prepareReplayState({
+				baseDir,
+				runId: RUN_ID,
+				fromCheckpoint: 'emergency',
+				emergencyDir,
+			}),
+		).rejects.toThrow(/No emergency dump/)
+	})
+})

package/src/runtime/query/replay/list.ts

@@ -0,0 +1,32 @@
+import { RunDiskStore } from '../../../store/run/disk.js'
+import type { RunId } from '../../../types/ids/index.js'
+import type { CheckpointListEntry } from '../../../types/run/replay.js'
+import type { Logger } from '../../../utils/logger.js'
+import { CheckpointManager } from '../checkpoint.js'
+
+export interface ListCheckpointsInput {
+	/** Directory that contains `<runId>/` for the target run. */
+	baseDir: string
+	/** Run whose checkpoints should be listed. */
+	runId: RunId
+	logger?: Logger
+}
+
+/**
+ * Read-only listing of a run's checkpoints for use with {@link
+ * import('./prepare.js').prepareReplayState}. Returns the public
+ * {@link CheckpointListEntry} projection — just enough for a caller to
+ * pick a fork point — not the full `IterationCheckpoint` payload.
+ *
+ * Entries are returned in the order the underlying store returns them
+ * (disk store sorts by `createdAt` ascending). Callers that want a
+ * specific order should sort client-side.
+ *
+ * See ses_005-deterministic-replay/design.md §3.1.
+ */
+export async function listCheckpoints(input: ListCheckpointsInput): Promise<CheckpointListEntry[]> {
+	const store = new RunDiskStore({ baseDir: input.baseDir, logger: input.logger })
+	await store.initRun(input.runId)
+	const mgr = new CheckpointManager(store)
+	return mgr.listEntries()
+}

package/src/runtime/query/replay/mutate.ts

@@ -0,0 +1,76 @@
+import type { ToolCallId } from '../../../types/ids/index.js'
+import {
+	type AssistantMessage,
+	type Message,
+	type ToolCall,
+	createToolMessage,
+} from '../../../types/message/index.js'
+import { type Mutation, MutationNotApplicableError } from '../../../types/run/replay.js'
+
+/**
+ * Returns the tool calls on the most recent assistant message that do not
+ * yet have a matching {@link import('../../../types/message/index.js').ToolMessage}
+ * response further down the message list. These are the fork-point "pending"
+ * tool calls that mutations may target.
+ */
+function findPendingToolCalls(messages: readonly Message[]): ToolCall[] {
+	let lastAssistantIdx = -1
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i]
+		if (msg && msg.role === 'assistant' && (msg.toolCalls?.length ?? 0) > 0) {
+			lastAssistantIdx = i
+			break
+		}
+	}
+	if (lastAssistantIdx === -1) return []
+
+	const assistant = messages[lastAssistantIdx] as AssistantMessage
+	const satisfied = new Set<string>()
+	for (let i = lastAssistantIdx + 1; i < messages.length; i++) {
+		const msg = messages[i]
+		if (msg && msg.role === 'tool') {
+			satisfied.add(msg.toolCallId)
+		}
+	}
+	return (assistant.toolCalls ?? []).filter((tc) => !satisfied.has(tc.id))
+}
+
+/**
+ * Apply an ordered list of {@link Mutation} to a checkpoint's message
+ * history at the fork point, producing a new message array that the
+ * resumed iteration loop consumes. Pure function; does not touch the run
+ * store, does not emit events.
+ *
+ * Throws {@link MutationNotApplicableError} when an `injectToolResponse`
+ * mutation targets a tool call id that is not pending at the fork point —
+ * the error payload carries the list of ids that *are* pending so the
+ * caller can recover without guessing.
+ *
+ * See ses_005-deterministic-replay design §3.3.
+ */
+export function applyMutations(
+	messages: readonly Message[],
+	mutations: readonly Mutation[],
+): Message[] {
+	let current: Message[] = [...messages]
+	for (const m of mutations) {
+		current = applyOne(current, m)
+	}
+	return current
+}
+
+function applyOne(messages: Message[], mutation: Mutation): Message[] {
+	switch (mutation.type) {
+		case 'injectToolResponse': {
+			const pending = findPendingToolCalls(messages)
+			const match = pending.find((tc) => tc.id === mutation.toolCallId)
+			if (!match) {
+				throw new MutationNotApplicableError(
+					`No pending tool call ${mutation.toolCallId} at fork point`,
+					pending.map((tc) => tc.id as ToolCallId),
+				)
+			}
+			return [...messages, createToolMessage(mutation.response.output, mutation.toolCallId)]
+		}
+	}
+}

package/src/runtime/query/replay/prepare.ts

@@ -0,0 +1,114 @@
+import { join } from 'node:path'
+import { EmergencySaveManager } from '../../../manager/run/emergency.js'
+import { RunDiskStore } from '../../../store/run/disk.js'
+import type { CheckpointId, IterationCheckpoint } from '../../../types/hitl/index.js'
+import type { RunId } from '../../../types/ids/index.js'
+import type { Message } from '../../../types/message/index.js'
+import type { Mutation, ReplayAttribution } from '../../../types/run/replay.js'
+import type { Logger } from '../../../utils/logger.js'
+import { projectEmergencyToCheckpoint } from '../checkpoint.js'
+import { applyMutations } from './mutate.js'
+
+export type CheckpointSelector = CheckpointId | 'latest' | 'emergency'
+
+export interface PrepareReplayInput {
+	/** Directory that contains `<runId>/` for the source run. */
+	baseDir: string
+	/** Source run to fork from. */
+	runId: RunId
+	/** Which checkpoint to fork at. */
+	fromCheckpoint: CheckpointSelector
+	/** Optional mutations applied at the fork point before the caller hands state to `query()`. */
+	mutate?: Mutation[]
+	/**
+	 * Directory that holds emergency dumps. Required only when `fromCheckpoint`
+	 * is `'emergency'`; conventionally sibling of `baseDir` (the `.namzu/emergency`
+	 * folder), but left explicit so callers with non-default layouts can redirect.
+	 */
+	emergencyDir?: string
+	logger?: Logger
+}
+
+export interface PreparedReplayState {
+	/**
+	 * Message history at the fork point, with mutations applied. Seed this
+	 * as the new run's initial messages and pass `sourceCheckpoint.id` as
+	 * `resumeFromCheckpoint` when you call `query()`.
+	 */
+	messages: Message[]
+	/** The checkpoint the replay forks from (already projected if emergency). */
+	sourceCheckpoint: IterationCheckpoint
+	/**
+	 * Attribution to stamp on the replay run once it is created. The caller
+	 * sets `Run.replayOf = buildAttribution(prepared, replayedAt)` on the
+	 * new `RunPersistence` before persisting the first time.
+	 */
+	attribution: ReplayAttribution
+}
+
+/**
+ * Produce the state materials needed to execute a replay run — the mutated
+ * message history, the resolved source checkpoint, and the replay
+ * attribution record. Pure read; does not touch the run store beyond
+ * reading the source run's checkpoint files.
+ *
+ * This is the state-preparation half of the replay primitive. The
+ * caller is expected to thread the returned `messages` +
+ * `sourceCheckpoint.id` into `query({ resumeFromCheckpoint, messages,
+ * ... })` and stamp `Run.replayOf = prepared.attribution` on the resulting
+ * run. The end-to-end `replay()` entry that does all of this in one call
+ * is a follow-up session (`ReplayEnvironment` shape).
+ *
+ * See `ses_005-deterministic-replay/design.md` §3.1.
+ */
+export async function prepareReplayState(input: PrepareReplayInput): Promise<PreparedReplayState> {
+	const sourceCheckpoint = await resolveCheckpoint(input)
+	const mutations = input.mutate ?? []
+	const messages = applyMutations(sourceCheckpoint.messages, mutations)
+
+	const attribution: ReplayAttribution = {
+		sourceRunId: input.runId,
+		fromCheckpointId: sourceCheckpoint.id,
+		mutations,
+		replayedAt: Date.now(),
+	}
+
+	return { messages, sourceCheckpoint, attribution }
+}
+
+async function resolveCheckpoint(input: PrepareReplayInput): Promise<IterationCheckpoint> {
+	if (input.fromCheckpoint === 'emergency') {
+		return resolveEmergency(input)
+	}
+	const store = new RunDiskStore({ baseDir: input.baseDir, logger: input.logger })
+	await store.initRun(input.runId)
+
+	if (input.fromCheckpoint === 'latest') {
+		const all = await store.listCheckpoints()
+		if (all.length === 0) {
+			throw new Error(`No checkpoints found for run ${input.runId} in ${input.baseDir}`)
+		}
+		return [...all].sort((a, b) => b.iteration - a.iteration)[0] as IterationCheckpoint
+	}
+
+	const checkpoint = await store.readCheckpoint(input.fromCheckpoint)
+	if (!checkpoint) {
+		throw new Error(`Checkpoint ${input.fromCheckpoint} not found for run ${input.runId}`)
+	}
+	return checkpoint
+}
+
+async function resolveEmergency(input: PrepareReplayInput): Promise<IterationCheckpoint> {
+	if (!input.emergencyDir) {
+		throw new Error(
+			"fromCheckpoint: 'emergency' requires an `emergencyDir` — conventionally sibling of baseDir",
+		)
+	}
+	const path = join(input.emergencyDir, `${input.runId}.json`)
+	try {
+		const dump = EmergencySaveManager.loadSave(path)
+		return projectEmergencyToCheckpoint(dump)
+	} catch (err) {
+		throw new Error(`No emergency dump found for run ${input.runId} at ${path}`, { cause: err })
+	}
+}

package/src/runtime/query/result.ts

@@ -3,7 +3,7 @@ import type { PlanManager } from '../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../manager/run/persistence.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import { GENAI, NAMZU } from '../../telemetry/attributes.js'
-import type { AgentRun, RunEvent } from '../../types/run/index.js'
+import type { Run, RunEvent } from '../../types/run/index.js'
 import { toErrorMessage } from '../../utils/error.js'
 import type { Logger } from '../../utils/logger.js'
 import type { EmitEvent } from './events.js'
@@ -87,7 +87,7 @@ export class ResultAssembler {
 		})
 	}
 
-	async finalize(): Promise<AgentRun> {
+	async finalize(): Promise<Run> {
 		await this.config.runMgr.persist()
 		return this.config.runMgr.getRun()
 	}

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

@@ -30,11 +30,11 @@ 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 { ActorRef } from '../../../types/session/actor.js'
+import type { Session } from '../../../types/session/entity.js'
 import type { ProjectId, SummaryId, ThreadId } 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'

package/src/session/__tests__/integration/archive-gate.test.ts

@@ -17,6 +17,7 @@ import { ThreadManager } from '../../../manager/thread/lifecycle.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { AgentId, RunId, UserId } from '../../../types/ids/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import { generateHandoffId } from '../../../utils/id.js'
 import { ThreadClosedError } from '../../errors.js'
 import type { HandoffAssignment } from '../../handoff/assignment.js'
@@ -24,7 +25,6 @@ import { type BroadcastHandoffDeps, executeBroadcastHandoff } from '../../handof
 import { DefaultCapacityValidator } from '../../handoff/capacity.js'
 import type { HandoffEventSink } from '../../handoff/events.js'
 import { type SingleHandoffDeps, executeSingleHandoff } from '../../handoff/single.js'
-import type { ActorRef } from '../../hierarchy/actor.js'
 import { GitWorktreeDriver } from '../../workspace/git-worktree.js'
 import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
 import {

package/src/session/__tests__/integration/capacity-caps.test.ts

@@ -11,8 +11,8 @@
  */
 
 import { describe, expect, it } from 'vitest'
+import type { ActorRef } from '../../../types/session/actor.js'
 import { DelegationCapacityExceeded } from '../../handoff/capacity.js'
-import type { ActorRef } from '../../hierarchy/actor.js'
 import {
 	DEFAULT_TENANT,
 	agentActor,

package/src/session/__tests__/integration/e2e-spawn.test.ts

@@ -34,10 +34,10 @@ import type { AgentTaskContext, SendMessageOptions } from '../../../types/agent/
 import type { RunId, TenantId, UserId } from '../../../types/ids/index.js'
 import { createAssistantMessage } from '../../../types/message/index.js'
 import type { RunEvent } from '../../../types/run/events.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import type { 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 { SessionSummaryMaterializer } from '../../summary/materialize.js'
 import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
 

package/src/session/__tests__/integration/handoff-broadcast-e2e.test.ts

@@ -14,13 +14,13 @@ import { ThreadManager } from '../../../manager/thread/lifecycle.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { SessionId } from '../../../types/ids/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
 import { generateHandoffId } from '../../../utils/id.js'
 import type { HandoffAssignment } from '../../handoff/assignment.js'
 import { type BroadcastHandoffDeps, executeBroadcastHandoff } from '../../handoff/broadcast.js'
 import { DefaultCapacityValidator } from '../../handoff/capacity.js'
 import type { HandoffEventSink } from '../../handoff/events.js'
-import type { ActorRef } from '../../hierarchy/actor.js'
 import type { ExecFile } from '../../workspace/git-worktree.js'
 import { GitWorktreeDriver } from '../../workspace/git-worktree.js'
 import { WorkspaceBackendRegistry } from '../../workspace/registry.js'

package/src/session/__tests__/integration/handoff-single-e2e.test.ts

@@ -17,13 +17,13 @@ import { ThreadManager } from '../../../manager/thread/lifecycle.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { TenantId } from '../../../types/ids/index.js'
+import type { Session } from '../../../types/session/entity.js'
 import { generateHandoffId } from '../../../utils/id.js'
 import { TenantIsolationError } from '../../errors.js'
 import type { HandoffAssignment } from '../../handoff/assignment.js'
 import { DefaultCapacityValidator } from '../../handoff/capacity.js'
 import type { HandoffEventSink } from '../../handoff/events.js'
 import { type SingleHandoffDeps, executeSingleHandoff } from '../../handoff/single.js'
-import type { Session } from '../../hierarchy/session.js'
 import { GitWorktreeDriver } from '../../workspace/git-worktree.js'
 import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
 import { DEFAULT_TENANT, OTHER_TENANT, okExec, stubLogger, userActor } from './_fixtures.js'

package/src/session/__tests__/integration/prev-artifact-dag.test.ts

@@ -20,13 +20,16 @@ import type {
 	SummaryId,
 	ThreadId,
 } from '../../../types/session/ids.js'
+import type {
+	DeliverableRef,
+	SessionSummaryDeliverable,
+} from '../../../types/summary/deliverable.js'
 import {
 	ArtifactRefCycleError,
 	type InterventionChainLoader,
 	InterventionDepthExceeded,
 	validatePrevArtifactChain,
 } from '../../intervention/prev-artifact.js'
-import type { DeliverableRef, SessionSummaryDeliverable } from '../../summary/deliverable.js'
 import { DEFAULT_TENANT, agentActor, userActor } from './_fixtures.js'
 
 const TEST_THREAD_ID = 'thd_test' as ThreadId

package/src/session/__tests__/integration/retention-archive.test.ts

@@ -16,9 +16,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import { createUserMessage } from '../../../types/message/index.js'
 import type { ThreadId, WorkspaceId } from '../../../types/session/ids.js'
+import type { WorkspaceRef } from '../../../types/workspace/ref.js'
 import { ArchivalManager, ArchiveNotConfiguredError } from '../../retention/archive.js'
 import { DiskArchiveBackend } from '../../retention/disk-backend.js'
-import type { WorkspaceRef } from '../../workspace/ref.js'
 import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
 import { DEFAULT_TENANT, agentActor, userActor } from './_fixtures.js'
 

package/src/session/__tests__/integration/spawn-rollback.test.ts

@@ -41,10 +41,11 @@ import type { AgentDefinition } from '../../../types/agent/factory.js'
 import type { AgentTaskContext, SendMessageOptions } from '../../../types/agent/task.js'
 import type { RunId, TenantId, UserId } from '../../../types/ids/index.js'
 import { createAssistantMessage } from '../../../types/message/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import type { SummaryId } from '../../../types/session/ids.js'
+import type { WorkspaceRef } from '../../../types/workspace/ref.js'
 import { ZERO_COST } from '../../../utils/cost.js'
 import { DefaultCapacityValidator } from '../../handoff/capacity.js'
-import type { ActorRef } from '../../hierarchy/actor.js'
 import { SessionSummaryMaterializer } from '../../summary/materialize.js'
 import type {
 	BranchWorkspaceParams,
@@ -52,7 +53,6 @@ import type {
 	WorkspaceBackendDriver,
 	WorkspaceInspection,
 } from '../../workspace/driver.js'
-import type { WorkspaceRef } from '../../workspace/ref.js'
 import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
 
 const tenant = 'tnt_alpha' as TenantId

package/src/session/__tests__/integration/summary-materialization-e2e.test.ts

@@ -19,8 +19,8 @@ import { describe, expect, it } from 'vitest'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import type { SessionId } from '../../../types/ids/index.js'
 import type { SummaryId, ThreadId } from '../../../types/session/ids.js'
+import { SessionAlreadySummarizedError } from '../../summary/errors.js'
 import { SessionSummaryMaterializer } from '../../summary/materialize.js'
-import { SessionAlreadySummarizedError } from '../../summary/ref.js'
 import { DEFAULT_TENANT, agentActor } from './_fixtures.js'
 
 const TEST_THREAD_ID = 'thd_test' as ThreadId

package/src/session/errors.ts

@@ -8,8 +8,8 @@
  */
 
 import type { SessionId, TenantId } from '../types/ids/index.js'
+import type { SessionStatus } from '../types/session/entity.js'
 import type { ThreadId } from '../types/session/ids.js'
-import type { SessionStatus } from './hierarchy/session.js'
 import type { WorkspaceBackendKind } from './workspace/driver.js'
 
 /**

package/src/session/events/index.ts

@@ -1,16 +1,17 @@
 // Sub-barrel for session-hierarchy run-event surface.
-// Convention #4: concrete types live in sibling files; re-export them here.
+// Shape types live under `types/run/` (subsession-events.ts + schema-version.ts);
+// this barrel only re-exports them. No runtime emitter lives here today.
 //
 // Phase 2 scope is limited to the sub-session lifecycle variants that are
 // spliced into `RunEvent`. A dedicated `SessionHierarchyEvent` top-level
 // union lands in a later phase (see session-hierarchy.md §10.2).
 
-export { RUN_EVENT_SCHEMA_VERSION } from './schema-version.js'
-export type { RunEventSchemaVersion } from './schema-version.js'
+export { RUN_EVENT_SCHEMA_VERSION } from '../../types/run/schema-version.js'
+export type { RunEventSchemaVersion } from '../../types/run/schema-version.js'
 
 export type {
 	SubsessionSpawnedEvent,
 	SubsessionMessagedEvent,
 	SubsessionIdledEvent,
 	SubsessionLifecycleEvent,
-} from './types.js'
+} from '../../types/run/subsession-events.js'

package/src/session/handoff/__tests__/broadcast.test.ts

@@ -1,6 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { ThreadManager } from '../../../manager/thread/lifecycle.js'
-import type { ActorRef } from '../../../session/hierarchy/actor.js'
 import {
 	type ExecFile,
 	type ExecFileResult,
@@ -10,6 +9,7 @@ import { WorkspaceBackendRegistry } from '../../../session/workspace/registry.js
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { SessionId, TenantId, UserId } from '../../../types/ids/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import type { ProjectId } from '../../../types/session/ids.js'
 import { generateHandoffId } from '../../../utils/id.js'
 import type { HandoffAssignment } from '../assignment.js'

package/src/session/handoff/__tests__/capacity.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest'
-import type { ActorRef } from '../../../session/hierarchy/actor.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
 import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type { AgentId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
+import type { ActorRef } from '../../../types/session/actor.js'
 import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
 import { DefaultCapacityValidator, DelegationCapacityExceeded } from '../capacity.js'