@namzu/sdk 0.2.0 → 0.4.0

package/src/manager/thread/lifecycle.ts

@@ -0,0 +1,217 @@
+/**
+ * ThreadManager — thin orchestrator over {@link ThreadStore} and
+ * {@link SessionStore}.
+ *
+ * Owns user-facing lifecycle operations on the Thread topic layer plus the
+ * archive-gate contract enforced at session-creation ingress sites.
+ *
+ * Phase 2.6 wired `ThreadManager.requireOpen` into three ingress paths:
+ *   - {@link AgentManager.provisionSpawn} (child session creation)
+ *   - `executeSingleHandoff` (recipient session creation)
+ *   - `executeBroadcastHandoff` (N recipient sessions per fan-out)
+ * Those call sites depend on this manager, so the one-method indirection
+ * stopped being "structural overhead" the moment archive/delete needed the
+ * session-presence cross-check anyway.
+ *
+ * Archive + delete require cross-store preconditions (session-presence
+ * checks) — enforced here where both stores are in scope. The stores
+ * themselves stay unaware of each other's layout (Convention #0), which is
+ * why the gate lives at the manager layer rather than as a universal store
+ * interceptor (see `archive` JSDoc for the direct-store-bypass boundary).
+ */
+
+import {
+	THREAD_NOT_EMPTY_SAMPLE_LIMIT,
+	ThreadClosedError,
+	ThreadNotEmptyError,
+} from '../../session/errors.js'
+import type { Session, SessionStatus } from '../../session/hierarchy/session.js'
+import type { Thread } from '../../session/hierarchy/thread.js'
+import type { TenantId } from '../../types/ids/index.js'
+import type { ProjectId, ThreadId } from '../../types/session/ids.js'
+import type { SessionStore } from '../../types/session/store.js'
+import type { CreateThreadParams, ThreadStore } from '../../types/thread/store.js'
+
+export interface ThreadManagerDeps {
+	readonly threadStore: ThreadStore
+	readonly sessionStore: SessionStore
+}
+
+/**
+ * Session statuses that block Thread archival. A session in any of these
+ * states has live work in-flight (mid-run, mid-handoff, blocked on human
+ * input, or orchestrating a broadcast merge) — freezing the Thread while any
+ * of them are active would strand resumable work.
+ *
+ * `idle`, `failed`, and `archived` are archival-compatible: they are
+ * quiescent or already-terminal, so a newly-frozen Thread can safely contain
+ * them. This list mirrors the `SessionStatus` discriminants that represent
+ * "not-yet-done" work (session-hierarchy.md §5.1).
+ */
+const ARCHIVAL_BLOCKING_STATUSES: ReadonlySet<SessionStatus> = new Set([
+	'active',
+	'locked',
+	'awaiting_hitl',
+	'awaiting_merge',
+])
+
+export class ThreadManager {
+	private readonly deps: ThreadManagerDeps
+
+	constructor(deps: ThreadManagerDeps) {
+		this.deps = deps
+	}
+
+	/** Persist a new Thread. Thin passthrough for uniformity at the manager surface. */
+	create(params: CreateThreadParams, tenantId: TenantId): Promise<Thread> {
+		return this.deps.threadStore.createThread(params, tenantId)
+	}
+
+	/** Read a Thread by id; returns `null` when absent for the tenant. */
+	get(threadId: ThreadId, tenantId: TenantId): Promise<Thread | null> {
+		return this.deps.threadStore.getThread(threadId, tenantId)
+	}
+
+	/**
+	 * CAS update on a Thread. Propagates {@link import('../../session/errors.js').StaleThreadError}
+	 * from the store on `ownerVersion` mismatch — callers re-read, re-apply,
+	 * and retry.
+	 */
+	update(thread: Thread, tenantId: TenantId): Promise<void> {
+		return this.deps.threadStore.updateThread(thread, tenantId)
+	}
+
+	/** List Threads under a Project, ordered by `createdAt` ascending. */
+	list(projectId: ProjectId, tenantId: TenantId): Promise<readonly Thread[]> {
+		return this.deps.threadStore.listThreads(projectId, tenantId)
+	}
+
+	/**
+	 * Load a Thread and assert it is in `'open'` state. Used by the spawn path
+	 * as a precondition — a SubSession cannot be created under an archived
+	 * Thread. Throws on absence and on archival; returns the loaded Thread on
+	 * success so callers can avoid the second round-trip.
+	 *
+	 * Convention #5: deny-by-default. A missing Thread is a hard error, not a
+	 * silent "assume archived".
+	 */
+	async requireOpen(threadId: ThreadId, tenantId: TenantId): Promise<Thread> {
+		const thread = await this.deps.threadStore.getThread(threadId, tenantId)
+		if (!thread) {
+			throw new Error(`Thread ${threadId} not found`)
+		}
+		if (thread.status === 'archived') {
+			throw new ThreadClosedError({ threadId, op: 'require-open' })
+		}
+		return thread
+	}
+
+	/**
+	 * Flip a Thread to `'archived'` via CAS on {@link Thread.ownerVersion}.
+	 *
+	 * Preconditions (checked in order):
+	 *   1. Thread exists for the tenant (throws on absence).
+	 *   2. No attached Session is in a non-terminal state (see
+	 *      {@link ARCHIVAL_BLOCKING_STATUSES}). The presence check runs
+	 *      **before** the idempotent-archive short-circuit so that an already
+	 *      archived thread harboring a live session still surfaces as
+	 *      {@link ThreadNotEmptyError} rather than a silent success.
+	 *   3. If the thread is already `'archived'` the method short-circuits
+	 *      without an `updateThread` write (idempotent re-archival). The
+	 *      returned record reflects the current persisted state.
+	 *
+	 * On a fresh archive transition the underlying
+	 * {@link ThreadStore.updateThread} call commits with `ownerVersion + 1`.
+	 * A {@link import('../../session/errors.js').StaleThreadError} from a
+	 * concurrent writer propagates unchanged — the caller is expected to
+	 * re-read + retry (mirrors the `updateThread` contract).
+	 *
+	 * Gate scope (Phase 2.6): `ThreadManager.requireOpen` is wired into
+	 * `AgentManager.provisionSpawn` and both handoff flows, so the production
+	 * ingress paths cannot attach new sessions under an archived thread.
+	 * `SessionStore.createSession` / `updateSession` remain public and
+	 * ungated at the store layer — a direct caller can still mutate a
+	 * session after archival (the store has no `ThreadStore` handle by
+	 * design; cross-store awareness lives in the manager). The defensive
+	 * re-check above catches a smuggled live session on a subsequent
+	 * archive call, but does not prevent the direct-store write from
+	 * landing. That's an acceptable boundary — kernel callers must go
+	 * through the ingress paths; direct store consumers are out of scope
+	 * for the archive invariant.
+	 */
+	async archive(threadId: ThreadId, tenantId: TenantId): Promise<Thread> {
+		const thread = await this.deps.threadStore.getThread(threadId, tenantId)
+		if (!thread) {
+			throw new Error(`Thread ${threadId} not found`)
+		}
+
+		// Always enforce the blocking-session invariant — even on re-archival.
+		// If the thread is already archived but somehow gained a live session
+		// (direct store mutation, concurrent spawn before a write-barrier
+		// existed), surfacing that via ThreadNotEmptyError is more useful to
+		// operators than a silent idempotent success.
+		const sessions = await this.deps.sessionStore.listSessions(threadId, tenantId)
+		const blocking = sessions.filter((s) => ARCHIVAL_BLOCKING_STATUSES.has(s.status))
+		if (blocking.length > 0) {
+			throw new ThreadNotEmptyError({
+				threadId,
+				tenantId,
+				op: 'archive',
+				blockingSessions: summarizeBlocking(blocking),
+				totalBlockingSessions: blocking.length,
+			})
+		}
+
+		if (thread.status === 'archived') {
+			// Idempotent: already archived, no live sessions attached. Skip the
+			// write (updateThread would still bump ownerVersion for no semantic
+			// change).
+			return thread
+		}
+
+		const next: Thread = { ...thread, status: 'archived' }
+		await this.deps.threadStore.updateThread(next, tenantId)
+		// updateThread advances ownerVersion + updatedAt; re-read so the returned
+		// record reflects the persisted state (callers rely on version monotonicity).
+		const reloaded = await this.deps.threadStore.getThread(threadId, tenantId)
+		if (!reloaded) {
+			throw new Error(`Thread ${threadId} vanished between archive and read-back`)
+		}
+		return reloaded
+	}
+
+	/**
+	 * Hard-delete a Thread record. Rejects with {@link ThreadNotEmptyError}
+	 * (`op: 'delete'`) when ANY Session still references the Thread —
+	 * deletion is stricter than archival, which tolerates quiescent sessions.
+	 * Callers must first delete or archive-and-tombstone every attached
+	 * session (via {@link SessionStore.deleteSession}) before invoking.
+	 *
+	 * The session scan runs unconditionally, so orphaned sessions pointing at
+	 * a missing thread are still detected and reject the delete. Idempotent
+	 * for genuinely absent threads (no sessions, no thread record) — missing
+	 * thread + empty session list is a no-op at the store layer. Convention
+	 * #5: deny-by-default; no implicit cascade into SessionStore.
+	 */
+	async delete(threadId: ThreadId, tenantId: TenantId): Promise<void> {
+		const sessions = await this.deps.sessionStore.listSessions(threadId, tenantId)
+		if (sessions.length > 0) {
+			throw new ThreadNotEmptyError({
+				threadId,
+				tenantId,
+				op: 'delete',
+				blockingSessions: summarizeBlocking(sessions),
+				totalBlockingSessions: sessions.length,
+			})
+		}
+		await this.deps.threadStore.deleteThread(threadId, tenantId)
+	}
+}
+
+function summarizeBlocking(
+	sessions: readonly Session[],
+): ReadonlyArray<{ sessionId: Session['id']; status: SessionStatus }> {
+	return sessions
+		.slice(0, THREAD_NOT_EMPTY_SAMPLE_LIMIT)
+		.map((s) => ({ sessionId: s.id, status: s.status }))
+}

package/src/rag/retriever.ts

@@ -57,11 +57,11 @@ export class DefaultRetriever implements Retriever {
 	}
 
 	private expandQuery(query: RetrievalQuery): string {
-		if (!query.threadMessages || query.threadMessages.length === 0) {
+		if (!query.recentMessages || query.recentMessages.length === 0) {
 			return query.text
 		}
 
-		const recentContext = query.threadMessages.slice(-3).join(' ')
+		const recentContext = query.recentMessages.slice(-3).join(' ')
 		return `${query.text}\n\nContext: ${recentContext}`
 	}
 

package/src/registry/tool/execute.ts

@@ -1,7 +1,7 @@
 import { SpanStatusCode } from '@opentelemetry/api'
 import { zodToJsonSchema } from 'zod-to-json-schema'
-import { getTracer } from '../../provider/telemetry/setup.js'
 import { GENAI, NAMZU, toolSpanName } from '../../telemetry/attributes.js'
+import { getTracer } from '../../telemetry/runtime-accessors.js'
 import type {
 	LLMToolSchema,
 	ToolAvailability,

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

@@ -3,7 +3,7 @@ import { DefaultPathBuilder, type PathBuilder } from '../../../session/workspace
 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 type { ProjectId, ThreadId } from '../../../types/session/ids.js'
 import { RunContextFactory } from '../context.js'
 
 function mockProvider(): LLMProvider {
@@ -16,6 +16,7 @@ function mockProvider(): LLMProvider {
 
 function buildConfig(overrides: Partial<Parameters<typeof RunContextFactory.build>[0]> = {}) {
 	const sessionId = 'ses_test' as SessionId
+	const threadId = 'thd_test' as ThreadId
 	const projectId = 'prj_test' as ProjectId
 	const tenantId = 'tnt_test' as TenantId
 	const runConfig: AgentRunConfig = {
@@ -31,6 +32,7 @@ function buildConfig(overrides: Partial<Parameters<typeof RunContextFactory.buil
 		provider: mockProvider(),
 		messages: [],
 		sessionId,
+		threadId,
 		projectId,
 		tenantId,
 		workingDirectory: '/tmp/run-context-test',
@@ -38,16 +40,15 @@ function buildConfig(overrides: Partial<Parameters<typeof RunContextFactory.buil
 	}
 }
 
-describe('RunContextFactory.build — Phase 6', () => {
-	it('requires sessionId, projectId, tenantId and returns them on the context', () => {
+describe('RunContextFactory.build', () => {
+	it('requires sessionId, threadId, projectId, tenantId and returns them on the context', () => {
 		const cfg = buildConfig()
 		const ctx = RunContextFactory.build(cfg)
 
 		expect(ctx.sessionId).toBe(cfg.sessionId)
+		expect(ctx.threadId).toBe(cfg.threadId)
 		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)', () => {
@@ -72,17 +73,17 @@ describe('RunContextFactory.build — Phase 6', () => {
 		const cfg = buildConfig()
 		const ctx = RunContextFactory.build(cfg)
 
-		// No more `/.namzu/threads/{threadId}/runs` — the new layout lives under
-		// projects/{pid}/sessions/{sid}.
+		// Layout lives under projects/{pid}/sessions/{sid} — no `.namzu/threads/`.
 		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', () => {
+	it('seeds RunPersistence with propagated sessionId/threadId/tenantId/projectId', () => {
 		const cfg = buildConfig()
 		const ctx = RunContextFactory.build(cfg)
 
 		expect(ctx.runMgr.sessionId).toBe(cfg.sessionId)
+		expect(ctx.runMgr.threadId).toBe(cfg.threadId)
 		expect(ctx.runMgr.tenantId).toBe(cfg.tenantId)
 		expect(ctx.runMgr.projectId).toBe(cfg.projectId)
 	})

package/src/runtime/query/context-cache.ts

@@ -1,14 +1,14 @@
 import { createHash } from 'node:crypto'
 import type { AgentContextLevel } from '../../types/agent/factory.js'
-import type { ThreadId } from '../../types/ids/index.js'
 import type { AgentPersona } from '../../types/persona/index.js'
+import type { ProjectId } from '../../types/session/ids.js'
 import type { Skill } from '../../types/skills/index.js'
 import type { ToolRegistryContract } from '../../types/tool/index.js'
 import { PromptBuilder, type PromptSegments } from './prompt.js'
 
 export interface ContextCacheConfig {
 	agentId: string
-	threadId: ThreadId
+	projectId: ProjectId
 }
 
 export interface PromptCacheInput {
@@ -21,7 +21,7 @@ export interface PromptCacheInput {
 }
 
 export class ContextCache {
-	readonly threadId: ThreadId
+	readonly projectId: ProjectId
 	readonly agentId: string
 
 	private cachedPrompt: string | undefined
@@ -30,7 +30,7 @@ export class ContextCache {
 	private cachedStaticHash: string | undefined
 
 	constructor(config: ContextCacheConfig) {
-		this.threadId = config.threadId
+		this.projectId = config.projectId
 		this.agentId = config.agentId
 	}
 

package/src/runtime/query/context.ts

@@ -11,29 +11,27 @@ import {
 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, SessionId, TenantId, ThreadId } from '../../types/ids/index.js'
+import type { RunId, SessionId, TenantId } 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 { ProjectId, ThreadId } 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.
+ * Config accepted by {@link RunContextFactory.build}. `sessionId`,
+ * `threadId`, `projectId`, and `tenantId` are required — runs carry the full
+ * five-layer scope (Tenant → Project → Thread → Session → Run) per
+ * Convention #17.
  *
  * `pathBuilder` is optional; when absent a {@link DefaultPathBuilder} is
- * constructed against `{workingDirectory}/.namzu` — no more hardcoded
- * `.namzu/threads` path.
+ * constructed against `{workingDirectory}/.namzu`.
  *
- * Phase 7 adds `filesystemMigrator` + `migrationSink`. These are also
- * optional; when absent a {@link DefaultFilesystemMigrator} wired to the
+ * `filesystemMigrator` + `migrationSink` are 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
@@ -51,6 +49,7 @@ export interface RunContextConfig {
 	signal?: AbortSignal
 
 	sessionId: SessionId
+	threadId: ThreadId
 	projectId: ProjectId
 	tenantId: TenantId
 
@@ -73,21 +72,13 @@ 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).
- */
+/** Result of {@link RunContextFactory.build}. */
 export interface RunContext {
 	runId: RunId
 	sessionId: SessionId
+	threadId: ThreadId
 	projectId: ProjectId
 	tenantId: TenantId
-	/**
-	 * @deprecated Mirrors `projectId` — remove when callers migrate off the
-	 * legacy name.
-	 */
-	threadId: ThreadId
 	runMgr: RunPersistence
 	activityStore: ActivityStore
 	planManager: PlanManager
@@ -156,6 +147,7 @@ export class RunContextFactory {
 			agent: config.agentName,
 			runId,
 			sessionId: config.sessionId,
+			threadId: config.threadId,
 			projectId: config.projectId,
 			tenantId: config.tenantId,
 		})
@@ -170,6 +162,7 @@ export class RunContextFactory {
 			pricing: config.pricing,
 			log,
 			sessionId: config.sessionId,
+			threadId: config.threadId,
 			tenantId: config.tenantId,
 			projectId: config.projectId,
 			parentRunId: config.parentRunId,
@@ -183,9 +176,9 @@ export class RunContextFactory {
 		return {
 			runId,
 			sessionId: config.sessionId,
+			threadId: config.threadId,
 			projectId: config.projectId,
 			tenantId: config.tenantId,
-			threadId: config.projectId as ThreadId,
 			runMgr,
 			activityStore,
 			planManager,

package/src/runtime/query/index.ts

@@ -7,9 +7,9 @@ import {
 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 { getTracer } from '../../telemetry/runtime-accessors.js'
 import { buildAdvisoryTools } from '../../tools/advisory/index.js'
 import { SearchToolsTool } from '../../tools/builtins/search-tools.js'
 import { buildTaskTools } from '../../tools/task/index.js'
@@ -21,7 +21,7 @@ import {
 	type ResumeHandler,
 	autoApproveHandler,
 } from '../../types/hitl/index.js'
-import type { RunId, SessionId, TenantId, ThreadId } from '../../types/ids/index.js'
+import type { RunId, SessionId, TenantId } 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'
@@ -29,7 +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 { ProjectId, ThreadId } 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'
@@ -67,30 +67,28 @@ export interface QueryParams {
 	resumeHandler: ResumeHandler
 	resumeFromCheckpoint?: CheckpointId
 
+	/** Session scope for the run. Required — every run is attributed to a Session. */
+	sessionId: SessionId
+
 	/**
-	 * Session scope for the run. Required in 0.2.0 — every run is attributed to
-	 * a Session (session-hierarchy.md §12.1).
+	 * Topic the Session lives under. Required in 0.3.0 — every run carries
+	 * the full five-layer scope (Tenant → Project → Thread → Session →
+	 * Run). Denormalized from `session.threadId`; callers build this
+	 * alongside `sessionId` so the query pipeline never needs a second
+	 * SessionStore round-trip to recover it.
 	 */
-	sessionId: SessionId
+	threadId: ThreadId
 
 	/** Long-lived goal scope for the run. Required. */
 	projectId: ProjectId
 
-	/** Isolation boundary. Required. */
+	/** Isolation boundary (Convention #17). 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.
+	 * rooted at `{workingDirectory}/.namzu`. First-call filesystem migration
+	 * runs on this same entry point.
 	 */
 	pathBuilder?: PathBuilder
 
@@ -158,6 +156,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Agen
 		messages: params.messages,
 		signal: params.signal,
 		sessionId: params.sessionId,
+		threadId: params.threadId,
 		projectId: params.projectId,
 		tenantId: params.tenantId,
 		pathBuilder: params.pathBuilder,

package/src/runtime/query/iteration/index.ts

@@ -5,9 +5,9 @@ import type { WorkingStateManager } from '../../../compaction/manager.js'
 import type { CompactionConfig } from '../../../config/runtime.js'
 import type { PlanManager } from '../../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../../manager/run/persistence.js'
-import { getTracer } from '../../../provider/telemetry/setup.js'
 import type { ActivityStore } from '../../../store/activity/memory.js'
 import { GENAI, NAMZU, agentIterationSpanName } from '../../../telemetry/attributes.js'
+import { getTracer } from '../../../telemetry/runtime-accessors.js'
 import type { ResumeHandler } from '../../../types/hitl/index.js'
 import { createAssistantMessage, createUserMessage } from '../../../types/message/index.js'
 import type { LLMProvider } from '../../../types/provider/index.js'

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

@@ -15,8 +15,10 @@
 import { vi } from 'vitest'
 import { EMPTY_TOKEN_USAGE } from '../../../constants/limits.js'
 import { AgentManager } from '../../../manager/agent/lifecycle.js'
+import { ThreadManager } from '../../../manager/thread/lifecycle.js'
 import { AgentRegistry } from '../../../registry/agent/definitions.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type {
 	AgentCapabilities,
 	AgentInput,
@@ -28,7 +30,7 @@ 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 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'
@@ -149,6 +151,8 @@ export function buildDefinition(agent: Agent<BaseAgentConfig, BaseAgentResult>):
 
 export interface IntegrationHarness {
 	readonly store: InMemorySessionStore
+	readonly threadStore: InMemoryThreadStore
+	readonly threadManager: ThreadManager
 	readonly registry: AgentRegistry
 	readonly manager: AgentManager
 	readonly materializer: SessionSummaryMaterializer
@@ -178,6 +182,7 @@ export interface IntegrationHarnessOptions {
 export function buildHarness(options: IntegrationHarnessOptions = {}): IntegrationHarness {
 	const tenantId = options.tenantId ?? DEFAULT_TENANT
 	const store = new InMemorySessionStore()
+	const threadStore = new InMemoryThreadStore()
 
 	const workspaceRegistry = new WorkspaceBackendRegistry()
 	if (options.withWorktreeDriver !== false) {
@@ -200,25 +205,42 @@ export function buildHarness(options: IntegrationHarnessOptions = {}): Integrati
 	})
 
 	const capacity = new DefaultCapacityValidator(store)
+	const threadManager = new ThreadManager({ threadStore, sessionStore: store })
 	const registry = new AgentRegistry()
 	const manager = new AgentManager(registry, undefined, {
 		sessionStore: store,
 		summaryMaterializer: materializer,
 		workspaceRegistry,
 		capacity,
+		threadManager,
 	})
 
-	return { store, registry, manager, materializer, workspaceRegistry, capacity, tenantId }
+	return {
+		store,
+		threadStore,
+		threadManager,
+		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.
+ * Seeds a Tenant → Project → Thread → Session quadruple and flips the session
+ * into `active` so it is a legal spawn parent. Returns the project, thread,
+ * and active session for the caller to drive spawns against.
  */
 export async function seedActiveParent(
 	harness: IntegrationHarness,
-	options?: { actor?: ActorRef; projectName?: string; tenantId?: TenantId },
+	options?: {
+		actor?: ActorRef
+		projectName?: string
+		tenantId?: TenantId
+		threadTitle?: string
+	},
 ) {
 	const tenantId = options?.tenantId ?? harness.tenantId
 	const actor: ActorRef = options?.actor ?? userActor('usr_root', tenantId)
@@ -226,12 +248,16 @@ export async function seedActiveParent(
 		{ tenantId, name: options?.projectName ?? 'integration-project' },
 		tenantId,
 	)
+	const thread = await harness.threadStore.createThread(
+		{ projectId: project.id, title: options?.threadTitle ?? 'default' },
+		tenantId,
+	)
 	const session = await harness.store.createSession(
-		{ projectId: project.id, currentActor: actor },
+		{ threadId: thread.id, projectId: project.id, currentActor: actor },
 		tenantId,
 	)
 	await harness.store.updateSession({ ...session, status: 'active' as Session['status'] }, tenantId)
-	return { project, session, actor }
+	return { project, thread, session, actor }
 }
 
 /**
@@ -242,6 +268,7 @@ export async function seedActiveParent(
 export function buildTaskContext(params: {
 	sessionId: SessionId
 	projectId: ProjectId
+	threadId: ThreadId
 	tenantId: TenantId
 	parentActor: ActorRef
 	depth?: number
@@ -258,6 +285,7 @@ export function buildTaskContext(params: {
 			remaining: params.budget ?? 100_000,
 		},
 		tenantId: params.tenantId,
+		threadId: params.threadId,
 		sessionId: params.sessionId,
 		projectId: params.projectId,
 		parentActor: params.parentActor,