@namzu/sdk 0.2.0 → 0.3.0

package/src/manager/agent/__tests__/lifecycle.test.ts

@@ -10,6 +10,7 @@ import type { DeliverableRef } from '../../../session/summary/deliverable.js'
 import { SessionSummaryMaterializer } from '../../../session/summary/materialize.js'
 import { WorkspaceBackendRegistry } from '../../../session/workspace/registry.js'
 import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
 import type {
 	AgentCapabilities,
 	AgentInput,
@@ -23,8 +24,9 @@ import type { AgentTaskContext, SendMessageOptions } from '../../../types/agent/
 import type { AgentId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
 import { createAssistantMessage } from '../../../types/message/index.js'
 import type { RunEvent } from '../../../types/run/events.js'
-import type { SummaryId } from '../../../types/session/ids.js'
+import type { SummaryId, ThreadId } from '../../../types/session/ids.js'
 import { ZERO_COST } from '../../../utils/cost.js'
+import { ThreadManager } from '../../thread/lifecycle.js'
 import { AgentManager } from '../lifecycle.js'
 
 const tenant = 'tnt_alpha' as TenantId
@@ -113,10 +115,13 @@ function agentActor(id: string, tid: TenantId = tenant): ActorRef {
 
 interface Harness {
 	store: InMemorySessionStore
+	threadStore: InMemoryThreadStore
+	threadManager: ThreadManager
 	materializer: SessionSummaryMaterializer
 	manager: AgentManager
 	parentSession: Awaited<ReturnType<InMemorySessionStore['createSession']>>
 	projectId: import('../../../types/session/ids.js').ProjectId
+	threadId: ThreadId
 	registry: AgentRegistry
 }
 
@@ -125,9 +130,15 @@ async function buildHarness(
 	tenantId: TenantId = tenant,
 ): Promise<Harness> {
 	const store = new InMemorySessionStore()
+	const threadStore = new InMemoryThreadStore()
+	const threadManager = new ThreadManager({ threadStore, sessionStore: store })
 	const project = await store.createProject({ tenantId, name: 'p1' }, tenantId)
+	const thread = await threadStore.createThread(
+		{ projectId: project.id, title: 'lifecycle-test' },
+		tenantId,
+	)
 	const parentSession = await store.createSession(
-		{ projectId: project.id, currentActor: user(tenantId) },
+		{ threadId: thread.id, projectId: project.id, currentActor: user(tenantId) },
 		tenantId,
 	)
 	// Parent runs kick the session into 'active' so the materializer can
@@ -148,14 +159,18 @@ async function buildHarness(
 		summaryMaterializer: materializer,
 		workspaceRegistry: new WorkspaceBackendRegistry(),
 		capacity: new DefaultCapacityValidator(store),
+		threadManager,
 	})
 
 	return {
 		store,
+		threadStore,
+		threadManager,
 		materializer,
 		manager,
 		parentSession: { ...parentSession, status: 'active' },
 		projectId: project.id,
+		threadId: thread.id,
 		registry,
 	}
 }
@@ -163,6 +178,7 @@ async function buildHarness(
 function buildContext(
 	parentSessionId: SessionId,
 	projectId: import('../../../types/session/ids.js').ProjectId,
+	threadId: ThreadId,
 	tenantId: TenantId = tenant,
 	depth = 0,
 ): AgentTaskContext {
@@ -173,6 +189,7 @@ function buildContext(
 		depth,
 		budgetTracker: { total: 100_000, remaining: 100_000 },
 		tenantId,
+		threadId,
 		sessionId: parentSessionId,
 		projectId,
 		parentActor: user(tenantId),
@@ -214,7 +231,7 @@ describe('AgentManager.sendMessage — Phase 6 SubSession spawn', () => {
 
 		const task = await harness.manager.sendMessage(
 			buildOptions('child-1', harness.parentSession.id, harness.projectId),
-			buildContext(harness.parentSession.id, harness.projectId),
+			buildContext(harness.parentSession.id, harness.projectId, harness.threadId),
 			listener,
 		)
 		await waitForTask(harness.manager, task.taskId)
@@ -259,7 +276,11 @@ describe('AgentManager.sendMessage — Phase 6 SubSession spawn', () => {
 		// Pre-fill 8 direct sub-sessions under the parent, up to the default width cap.
 		for (let i = 0; i < 8; i++) {
 			const sibling = await harness.store.createSession(
-				{ projectId: harness.projectId, currentActor: agentActor('sibling') },
+				{
+					threadId: harness.threadId,
+					projectId: harness.projectId,
+					currentActor: agentActor('sibling'),
+				},
 				tenant,
 			)
 			await harness.store.createSubSession(
@@ -276,7 +297,7 @@ describe('AgentManager.sendMessage — Phase 6 SubSession spawn', () => {
 		await expect(
 			harness.manager.sendMessage(
 				buildOptions('child-1', harness.parentSession.id, harness.projectId),
-				buildContext(harness.parentSession.id, harness.projectId),
+				buildContext(harness.parentSession.id, harness.projectId, harness.threadId),
 			),
 		).rejects.toBeInstanceOf(DelegationCapacityExceeded)
 	})
@@ -290,7 +311,7 @@ describe('AgentManager.sendMessage — Phase 6 SubSession spawn', () => {
 		let parentId: SessionId = harness.parentSession.id
 		for (let i = 0; i < 4; i++) {
 			const child = await harness.store.createSession(
-				{ projectId: harness.projectId, currentActor: agentActor('c') },
+				{ threadId: harness.threadId, projectId: harness.projectId, currentActor: agentActor('c') },
 				tenant,
 			)
 			await harness.store.createSubSession(
@@ -308,7 +329,7 @@ describe('AgentManager.sendMessage — Phase 6 SubSession spawn', () => {
 		await expect(
 			harness.manager.sendMessage(
 				buildOptions('child-1', parentId, harness.projectId),
-				buildContext(parentId, harness.projectId, tenant, 0),
+				buildContext(parentId, harness.projectId, harness.threadId, tenant, 0),
 			),
 		).rejects.toBeInstanceOf(DelegationCapacityExceeded)
 	})
@@ -319,7 +340,7 @@ describe('AgentManager.sendMessage — Phase 6 SubSession spawn', () => {
 
 		const task = await harness.manager.sendMessage(
 			buildOptions('child-fail', harness.parentSession.id, harness.projectId),
-			buildContext(harness.parentSession.id, harness.projectId),
+			buildContext(harness.parentSession.id, harness.projectId, harness.threadId),
 		)
 		await waitForTask(harness.manager, task.taskId)
 
@@ -342,7 +363,7 @@ describe('AgentManager.sendMessage — Phase 6 SubSession spawn', () => {
 
 		const task = await harness.manager.sendMessage(
 			buildOptions('child-msgs', harness.parentSession.id, harness.projectId),
-			buildContext(harness.parentSession.id, harness.projectId),
+			buildContext(harness.parentSession.id, harness.projectId, harness.threadId),
 		)
 		await waitForTask(harness.manager, task.taskId)
 
@@ -364,7 +385,7 @@ describe('AgentManager.sendMessage — Phase 6 SubSession spawn', () => {
 
 		// Seed c1 under parentSession, c2 under c1.
 		const c1 = await harness.store.createSession(
-			{ projectId: harness.projectId, currentActor: agentActor('c1') },
+			{ threadId: harness.threadId, projectId: harness.projectId, currentActor: agentActor('c1') },
 			tenant,
 		)
 		await harness.store.createSubSession(
@@ -377,7 +398,7 @@ describe('AgentManager.sendMessage — Phase 6 SubSession spawn', () => {
 			tenant,
 		)
 		const c2 = await harness.store.createSession(
-			{ projectId: harness.projectId, currentActor: agentActor('c2') },
+			{ threadId: harness.threadId, projectId: harness.projectId, currentActor: agentActor('c2') },
 			tenant,
 		)
 		await harness.store.createSubSession(
@@ -393,7 +414,7 @@ describe('AgentManager.sendMessage — Phase 6 SubSession spawn', () => {
 		const events: RunEvent[] = []
 		const task = await harness.manager.sendMessage(
 			buildOptions('grandchild', c2.id, harness.projectId),
-			buildContext(c2.id, harness.projectId),
+			buildContext(c2.id, harness.projectId, harness.threadId),
 			(e) => {
 				events.push(e)
 			},
@@ -440,7 +461,7 @@ describe('AgentManager.sendMessage — Phase 6 SubSession spawn', () => {
 		await expect(
 			harness.manager.sendMessage(
 				mismatchedOptions,
-				buildContext(harness.parentSession.id, harness.projectId, tenant),
+				buildContext(harness.parentSession.id, harness.projectId, harness.threadId, tenant),
 			),
 		).rejects.toThrow(/Tenant mismatch/)
 	})

package/src/manager/agent/lifecycle.ts

@@ -35,6 +35,7 @@ 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'
+import type { ThreadManager } from '../thread/lifecycle.js'
 
 /**
  * Dependencies threaded into {@link AgentManager}. Phase 6 promoted the
@@ -60,6 +61,14 @@ export interface AgentManagerDeps {
 	readonly workspaceRegistry: WorkspaceBackendRegistry
 	readonly summaryMaterializer: SessionSummaryMaterializer
 	readonly capacity: CapacityValidator
+	/**
+	 * Gate session creation on the parent Thread being `'open'` via
+	 * {@link ThreadManager.requireOpen}. Added in Phase 2.6 to close the
+	 * archive-gate gap flagged by the Phase 2.5 commit: without this,
+	 * `ThreadManager.archive` was best-effort because spawn could still
+	 * attach a live session under an archived Thread.
+	 */
+	readonly threadManager: ThreadManager
 }
 
 interface ChildSpawnRecord {
@@ -146,6 +155,7 @@ export class AgentManager {
 			budgetTracker: context.budgetTracker,
 			factoryOptions: context.factoryOptions,
 			tenantId: context.tenantId,
+			threadId: context.threadId,
 			sessionId: spawnRecord.childSessionId,
 			projectId: context.projectId,
 			parentActor: childParentActor,
@@ -203,12 +213,16 @@ export class AgentManager {
 
 		const definition = this.registry.getOrThrow(options.agentId)
 		let childConfig: BaseAgentConfig
-		if (definition.configBuilder && context.factoryOptions) {
+		if (definition.configBuilder) {
+			// Call the configBuilder regardless of whether factoryOptions were
+			// supplied. BYO-provider flows (Bedrock IAM, custom ProviderRegistry)
+			// commonly omit factoryOptions because the provider resolves its own
+			// credentials; the builder still needs to run to wire provider+tools.
+			// Defaults: empty factoryOptions when omitted; configOverrides win.
 			childConfig = await definition.configBuilder({
-				...context.factoryOptions,
+				...(context.factoryOptions ?? {}),
 				tokenBudget: allocatedTokens,
 				timeoutMs: options.budgetAllocation?.timeoutMs ?? context.budgetTracker.remaining,
-				threadId: context.projectId as string,
 				parentRunId: context.parentRunId as string | undefined,
 				depth: context.depth + 1,
 				...options.configOverrides,
@@ -222,10 +236,11 @@ export class AgentManager {
 			// 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.threadId = context.threadId
 			childConfig.projectId = context.projectId
 			childConfig.tenantId = context.tenantId
 		} else {
-			this.log.warn('No configBuilder or factoryOptions, using bare config', {
+			this.log.warn('No configBuilder, using bare config', {
 				agentId: options.agentId,
 			})
 			childConfig = {
@@ -236,8 +251,8 @@ export class AgentManager {
 				maxIterations: options.configOverrides?.maxIterations,
 				maxResponseTokens: options.configOverrides?.maxResponseTokens,
 				env: options.configOverrides?.env,
-				threadId: context.projectId,
 				sessionId: spawnRecord.childSessionId,
+				threadId: context.threadId,
 				projectId: context.projectId,
 				tenantId: context.tenantId,
 				parentRunId: context.parentRunId,
@@ -367,6 +382,42 @@ export class AgentManager {
 		// partial/legacy path).
 		const store = this.deps.sessionStore
 
+		// Thread archive gate — runs FIRST so an archived thread fails fastest
+		// with the correct error (not DelegationCapacityExceeded or a project
+		// lookup error). Phase 2.6 closes the gap the Phase 2.5 commit
+		// flagged: without it, `ThreadManager.archive` could be undermined by
+		// a concurrent spawn landing a live session post-archival.
+		// Scope: this gate enforces the archive invariant at the production
+		// ingress path (AgentManager.sendMessage + handoff flows). Direct
+		// callers of `SessionStore.createSession` bypass it — the store layer
+		// is intentionally unaware of thread status to preserve its
+		// single-responsibility boundary.
+		await this.deps.threadManager.requireOpen(context.threadId, context.tenantId)
+
+		// Parent session cross-check: validate that `options.parentSessionId`
+		// exists for this tenant AND lives under the same thread as the
+		// context. A mismatched `context.threadId` would otherwise attach the
+		// child's sub-session edge to a parent in a different thread —
+		// corrupting the hierarchy invariant (cross-thread spawn is forbidden
+		// by design). Mirrors the `source.threadId === assignment.threadId`
+		// check in handoff (Phase 2.4).
+		const parentSession = await store.getSession(options.parentSessionId, context.tenantId)
+		if (!parentSession) {
+			throw new Error(
+				`Parent session ${options.parentSessionId} not found for tenant ${context.tenantId} — spawn rejected`,
+			)
+		}
+		if (parentSession.threadId !== context.threadId) {
+			throw new Error(
+				`Thread mismatch on spawn: parent session ${parentSession.id} is on thread ${parentSession.threadId}, but context.threadId=${context.threadId}. Cross-thread spawn is forbidden (session-hierarchy.md §6.3).`,
+			)
+		}
+		if (parentSession.projectId !== context.projectId) {
+			throw new Error(
+				`Project mismatch on spawn: parent session ${parentSession.id} is on project ${parentSession.projectId}, but context.projectId=${context.projectId}.`,
+			)
+		}
+
 		const project = await store.getProject(context.projectId, context.tenantId)
 		if (!project) {
 			throw new Error(
@@ -401,45 +452,73 @@ export class AgentManager {
 			parentActor: context.parentActor,
 		}
 
+		// Child session inherits the parent's threadId verbatim (cross-thread
+		// spawn is forbidden by design — a delegated sub-agent stays on the
+		// same topic). Phase 2.6 elides the previous parent-session read by
+		// carrying `threadId` on `AgentTaskContext`.
 		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',
+				threadId: context.threadId,
+				projectId: context.projectId,
+				currentActor: childActor,
 			},
 			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.
+		// Compensating rollback wraps every mutation after createSession so a
+		// mid-flight failure (status flip, subsession insert, workspace driver)
+		// leaves no orphan child session. Codex SPAWN-ROLLBACK critique (Phase
+		// 2 review, 2026-04-18): without this, `workspaceRegistry.get().create`
+		// throwing — or a concurrent `updateSession` race — strands an
+		// `active` child session with no subsession edge, invisible to the
+		// parent but counted against `maxDelegationWidth`.
+		let subSession: Awaited<ReturnType<typeof store.createSubSession>> | undefined
 		let workspaceRef: WorkspaceRef | undefined
-		const backend = options.workspaceBackend ?? 'git-worktree'
-		if (this.deps.workspaceRegistry.has(backend)) {
-			const driver = this.deps.workspaceRegistry.get(backend)
-			try {
+		try {
+			// 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)
+
+			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.
+			const backend = options.workspaceBackend ?? 'git-worktree'
+			if (this.deps.workspaceRegistry.has(backend)) {
+				const driver = this.deps.workspaceRegistry.get(backend)
 				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
 			}
+		} catch (err) {
+			// Compensating rollback order is mandated by the store's
+			// deny-by-default cascade policy (Convention #5): `deleteSession`
+			// throws when any subsession still references it, so the subsession
+			// record must be removed first. No failed-subsession audit row is
+			// kept — the `subsession_spawned` run event never fired (we aborted
+			// before `buildSpawnRecord`), so no observer is expecting one, and
+			// leaving a `status: 'failed'` breadcrumb would be a dangling
+			// record with no corresponding emission. The original `err` is the
+			// caller-visible signal; cleanup errors are swallowed so they
+			// cannot mask it.
+			if (subSession !== undefined) {
+				await store.deleteSubSession(subSession.id, context.tenantId).catch(() => undefined)
+			}
+			await store.deleteSession(childSession.id, context.tenantId).catch(() => undefined)
+			throw err
 		}
 
 		return {

package/src/manager/index.ts

@@ -16,4 +16,7 @@ export type {
 export { PlanManager } from './plan/lifecycle.js'
 export type { PlanEvent, PlanEventListener, PlanApprovalHandler } from './plan/lifecycle.js'
 
+export { ThreadManager } from './thread/lifecycle.js'
+export type { ThreadManagerDeps } from './thread/lifecycle.js'
+
 export { AgentManager } from './agent/lifecycle.js'

package/src/manager/run/persistence.ts

@@ -5,7 +5,7 @@ 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 { ProjectId, ThreadId } 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'
@@ -16,6 +16,7 @@ export class RunPersistence {
 	private pricing?: ModelPricing
 	private log: Logger
 	private readonly _sessionId: SessionId
+	private readonly _threadId: ThreadId
 	private readonly _tenantId: TenantId
 	private readonly _projectId: ProjectId
 
@@ -23,6 +24,7 @@ export class RunPersistence {
 		this.pricing = config.pricing
 		this.log = config.log
 		this._sessionId = config.sessionId
+		this._threadId = config.threadId
 		this._tenantId = config.tenantId
 		this._projectId = config.projectId
 
@@ -58,6 +60,10 @@ export class RunPersistence {
 		return this._sessionId
 	}
 
+	get threadId(): ThreadId {
+		return this._threadId
+	}
+
 	get tenantId(): TenantId {
 		return this._tenantId
 	}