@namzu/sdk 0.2.0 → 0.4.0

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
 	}

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

@@ -0,0 +1,286 @@
+import { describe, expect, it } from 'vitest'
+import { ThreadClosedError, ThreadNotEmptyError } from '../../../session/errors.js'
+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, TenantId, UserId } from '../../../types/ids/index.js'
+import type { ThreadId } from '../../../types/session/ids.js'
+import { ThreadManager } from '../lifecycle.js'
+
+const MISSING_THREAD_ID = 'thd_missing' as ThreadId
+
+const tenantA = 'tnt_alpha' as TenantId
+const tenantB = 'tnt_beta' as TenantId
+
+function userActor(tenantId: TenantId): ActorRef {
+	return { kind: 'user', userId: 'usr_a' as UserId, tenantId }
+}
+
+function agentActor(tenantId: TenantId): ActorRef {
+	return { kind: 'agent', agentId: 'agt_a' as AgentId, tenantId }
+}
+
+async function harness(tenantId: TenantId = tenantA) {
+	const threadStore = new InMemoryThreadStore()
+	const sessionStore = new InMemorySessionStore()
+	const project = await sessionStore.createProject({ tenantId, name: 'p1' }, tenantId)
+	const thread = await threadStore.createThread({ projectId: project.id, title: 't' }, tenantId)
+	const manager = new ThreadManager({ threadStore, sessionStore })
+	return { threadStore, sessionStore, project, thread, manager }
+}
+
+describe('ThreadManager', () => {
+	describe('requireOpen', () => {
+		it('returns the thread when open', async () => {
+			const { thread, manager } = await harness()
+			await expect(manager.requireOpen(thread.id, tenantA)).resolves.toMatchObject({
+				id: thread.id,
+				status: 'open',
+			})
+		})
+
+		it('throws ThreadClosedError when archived', async () => {
+			const { thread, manager, threadStore } = await harness()
+			await threadStore.updateThread({ ...thread, status: 'archived' }, tenantA)
+			await expect(manager.requireOpen(thread.id, tenantA)).rejects.toBeInstanceOf(
+				ThreadClosedError,
+			)
+		})
+
+		it('throws when the thread does not exist', async () => {
+			const { manager } = await harness()
+			await expect(manager.requireOpen(MISSING_THREAD_ID, tenantA)).rejects.toThrow(/not found/)
+		})
+	})
+
+	describe('archive', () => {
+		it('flips status to archived and bumps ownerVersion', async () => {
+			const { thread, manager } = await harness()
+			const archived = await manager.archive(thread.id, tenantA)
+			expect(archived.status).toBe('archived')
+			expect(archived.ownerVersion).toBe(thread.ownerVersion + 1)
+		})
+
+		it('is idempotent on an already-archived thread (no store write)', async () => {
+			const { thread, manager, threadStore } = await harness()
+			await threadStore.updateThread({ ...thread, status: 'archived' }, tenantA)
+			const before = await threadStore.getThread(thread.id, tenantA)
+
+			const result = await manager.archive(thread.id, tenantA)
+			expect(result.status).toBe('archived')
+			// Re-archival must NOT advance ownerVersion — the store would have
+			// rejected a second updateThread as stale anyway; we assert the
+			// short-circuit path held instead.
+			expect(result.ownerVersion).toBe(before?.ownerVersion)
+		})
+
+		it('throws when the thread does not exist', async () => {
+			const { manager } = await harness()
+			await expect(manager.archive(MISSING_THREAD_ID, tenantA)).rejects.toThrow(/not found/)
+		})
+
+		it('rejects with ThreadNotEmptyError when a session is active', async () => {
+			const { thread, project, manager, sessionStore } = await harness()
+			const session = await sessionStore.createSession(
+				{
+					threadId: thread.id,
+					projectId: project.id,
+					currentActor: userActor(tenantA),
+				},
+				tenantA,
+			)
+			await sessionStore.updateSession({ ...session, status: 'active' }, tenantA)
+
+			await expect(manager.archive(thread.id, tenantA)).rejects.toMatchObject({
+				name: 'ThreadNotEmptyError',
+				details: {
+					threadId: thread.id,
+					tenantId: tenantA,
+					op: 'archive',
+					totalBlockingSessions: 1,
+					blockingSessions: [{ sessionId: session.id, status: 'active' }],
+				},
+			})
+		})
+
+		it('defensive re-check: already-archived thread with a smuggled active session still rejects', async () => {
+			// Flip the thread to archived directly (bypassing manager.archive so
+			// no check runs), then attach an active session via direct store
+			// mutation. A subsequent manager.archive() must surface the offender
+			// as ThreadNotEmptyError, not short-circuit as "already archived".
+			const { thread, project, manager, sessionStore, threadStore } = await harness()
+			await threadStore.updateThread({ ...thread, status: 'archived' }, tenantA)
+			const smuggled = await sessionStore.createSession(
+				{
+					threadId: thread.id,
+					projectId: project.id,
+					currentActor: userActor(tenantA),
+				},
+				tenantA,
+			)
+			await sessionStore.updateSession({ ...smuggled, status: 'active' }, tenantA)
+
+			await expect(manager.archive(thread.id, tenantA)).rejects.toMatchObject({
+				name: 'ThreadNotEmptyError',
+				details: {
+					op: 'archive',
+					totalBlockingSessions: 1,
+					blockingSessions: [{ sessionId: smuggled.id, status: 'active' }],
+				},
+			})
+		})
+
+		it.each(['locked', 'awaiting_hitl', 'awaiting_merge'] as const)(
+			'rejects when a session is %s',
+			async (status) => {
+				const { thread, project, manager, sessionStore } = await harness()
+				const session = await sessionStore.createSession(
+					{
+						threadId: thread.id,
+						projectId: project.id,
+						currentActor: userActor(tenantA),
+					},
+					tenantA,
+				)
+				await sessionStore.updateSession({ ...session, status }, tenantA)
+
+				await expect(manager.archive(thread.id, tenantA)).rejects.toBeInstanceOf(
+					ThreadNotEmptyError,
+				)
+			},
+		)
+
+		it('allows archival when every session is quiescent (idle / failed / archived)', async () => {
+			const { thread, project, manager, sessionStore } = await harness()
+			// `createSession` defaults to `idle`; force the others via updateSession.
+			await sessionStore.createSession(
+				{
+					threadId: thread.id,
+					projectId: project.id,
+					currentActor: userActor(tenantA),
+				},
+				tenantA,
+			)
+			const sFailed = await sessionStore.createSession(
+				{
+					threadId: thread.id,
+					projectId: project.id,
+					currentActor: agentActor(tenantA),
+				},
+				tenantA,
+			)
+			await sessionStore.updateSession({ ...sFailed, status: 'failed' }, tenantA)
+
+			const archived = await manager.archive(thread.id, tenantA)
+			expect(archived.status).toBe('archived')
+		})
+
+		it('ignores sessions attached to a sibling thread', async () => {
+			const { thread, project, manager, sessionStore, threadStore } = await harness()
+			const other = await threadStore.createThread(
+				{ projectId: project.id, title: 'other' },
+				tenantA,
+			)
+			// Active session under the OTHER thread must not block archival of
+			// `thread`.
+			const otherSession = await sessionStore.createSession(
+				{
+					threadId: other.id,
+					projectId: project.id,
+					currentActor: userActor(tenantA),
+				},
+				tenantA,
+			)
+			await sessionStore.updateSession({ ...otherSession, status: 'active' }, tenantA)
+
+			await expect(manager.archive(thread.id, tenantA)).resolves.toMatchObject({
+				status: 'archived',
+			})
+		})
+
+		it('does not leak cross-tenant sessions into the precondition', async () => {
+			// Shared stores across tenants (production shape). A session with
+			// the same threadId string under tenantB must not block archival
+			// of tenantA's thread.
+			const threadStore = new InMemoryThreadStore()
+			const sessionStore = new InMemorySessionStore()
+			const manager = new ThreadManager({ threadStore, sessionStore })
+
+			const pA = await sessionStore.createProject({ tenantId: tenantA, name: 'pa' }, tenantA)
+			const pB = await sessionStore.createProject({ tenantId: tenantB, name: 'pb' }, tenantB)
+			const tA = await threadStore.createThread({ projectId: pA.id, title: 'ta' }, tenantA)
+
+			// Cross-tenant session with the same threadId string as tA.
+			const bSession = await sessionStore.createSession(
+				{ threadId: tA.id, projectId: pB.id, currentActor: userActor(tenantB) },
+				tenantB,
+			)
+			await sessionStore.updateSession({ ...bSession, status: 'active' }, tenantB)
+
+			await expect(manager.archive(tA.id, tenantA)).resolves.toMatchObject({
+				status: 'archived',
+			})
+		})
+	})
+
+	describe('delete', () => {
+		it('deletes an empty thread', async () => {
+			const { thread, manager, threadStore } = await harness()
+			await manager.delete(thread.id, tenantA)
+			expect(await threadStore.getThread(thread.id, tenantA)).toBeNull()
+		})
+
+		it('rejects with ThreadNotEmptyError when any session references the thread', async () => {
+			const { thread, project, manager, sessionStore } = await harness()
+			const session = await sessionStore.createSession(
+				{
+					threadId: thread.id,
+					projectId: project.id,
+					currentActor: userActor(tenantA),
+				},
+				tenantA,
+			)
+			// Idle — allowed under archive, still blocks delete.
+			await expect(manager.delete(thread.id, tenantA)).rejects.toMatchObject({
+				name: 'ThreadNotEmptyError',
+				details: {
+					threadId: thread.id,
+					tenantId: tenantA,
+					op: 'delete',
+					totalBlockingSessions: 1,
+					blockingSessions: [{ sessionId: session.id, status: 'idle' }],
+				},
+			})
+		})
+
+		it('detects orphaned sessions referencing a missing thread', async () => {
+			// Thread record is destroyed via the store directly, but a session
+			// still carries its threadId. Manager.delete must reject rather
+			// than silently succeed on the "thread is already gone" short-cut
+			// (the session scan runs unconditionally).
+			const { thread, project, manager, sessionStore, threadStore } = await harness()
+			const orphan = await sessionStore.createSession(
+				{
+					threadId: thread.id,
+					projectId: project.id,
+					currentActor: userActor(tenantA),
+				},
+				tenantA,
+			)
+			await threadStore.deleteThread(thread.id, tenantA)
+
+			await expect(manager.delete(thread.id, tenantA)).rejects.toMatchObject({
+				name: 'ThreadNotEmptyError',
+				details: {
+					op: 'delete',
+					blockingSessions: [{ sessionId: orphan.id, status: 'idle' }],
+				},
+			})
+		})
+
+		it('is idempotent for an absent thread with no orphans', async () => {
+			const { manager } = await harness()
+			await expect(manager.delete(MISSING_THREAD_ID, tenantA)).resolves.toBeUndefined()
+		})
+	})
+})