@namzu/sdk 0.1.8 → 0.3.0

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

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

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

@@ -0,0 +1,288 @@
+/**
+ * Integration — Thread archive gate enforced at session-creation ingress
+ * sites (Phase 2.6).
+ *
+ * The Phase 2.5 commit flagged this as a known gap:
+ *   > spawn and handoff paths do not yet invoke `ThreadManager.requireOpen`
+ *   > before creating a child session. Until they do, the archive invariant
+ *   > is best-effort.
+ *
+ * Phase 2.6 wires `requireOpen` into `AgentManager.provisionSpawn` + both
+ * handoff flows. These tests drive the archived-thread-then-attempt-creation
+ * scenarios end-to-end against the real stack.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+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 { generateHandoffId } from '../../../utils/id.js'
+import { ThreadClosedError } from '../../errors.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 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 {
+	DEFAULT_TENANT,
+	buildAgent,
+	buildDefinition,
+	buildHarness,
+	buildSendMessageOptions,
+	buildTaskContext,
+	okExec,
+	seedActiveParent,
+	stubLogger,
+	userActor,
+} from './_fixtures.js'
+
+describe('Integration — archive gate (Phase 2.6)', () => {
+	it('AgentManager spawn: rejects with ThreadClosedError when parent thread is archived', async () => {
+		const harness = buildHarness()
+		const { project, thread, session, actor } = await seedActiveParent(harness)
+
+		// Archive the thread via the manager so the invariant is enforced — no
+		// in-flight sessions under this thread, so archive succeeds.
+		await harness.store.updateSession({ ...session, status: 'idle' }, DEFAULT_TENANT)
+		await harness.threadManager.archive(thread.id, DEFAULT_TENANT)
+		// Flip session back to active so the spawn's capacity path reaches
+		// provisionSpawn (the archive gate should still reject).
+		await harness.store.updateSession({ ...session, status: 'active' }, DEFAULT_TENANT)
+
+		harness.registry.register(buildDefinition(buildAgent('worker')))
+
+		await expect(
+			harness.manager.sendMessage(
+				buildSendMessageOptions({
+					agentId: 'worker',
+					parentSessionId: session.id,
+					projectId: project.id,
+					tenantId: DEFAULT_TENANT,
+					parentActor: actor,
+				}),
+				buildTaskContext({
+					sessionId: session.id,
+					projectId: project.id,
+					threadId: thread.id,
+					tenantId: DEFAULT_TENANT,
+					parentActor: actor,
+				}),
+			),
+		).rejects.toBeInstanceOf(ThreadClosedError)
+
+		// Archive invariant held: no new child sessions under the archived thread.
+		const underThread = await harness.store.listSessions(thread.id, DEFAULT_TENANT)
+		expect(underThread).toHaveLength(1)
+		expect(underThread[0]?.id).toBe(session.id)
+	})
+
+	it('Single handoff: rejects with ThreadClosedError when thread is archived (before CAS lock)', async () => {
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const project = await store.createProject(
+			{ tenantId: DEFAULT_TENANT, name: 'archive-single' },
+			DEFAULT_TENANT,
+		)
+		const thread = await threadStore.createThread(
+			{ projectId: project.id, title: 'archive-single' },
+			DEFAULT_TENANT,
+		)
+		const sourceActor: ActorRef = {
+			kind: 'user',
+			userId: 'usr_source' as UserId,
+			tenantId: DEFAULT_TENANT,
+		}
+		const session = await store.createSession(
+			{ threadId: thread.id, projectId: project.id, currentActor: sourceActor },
+			DEFAULT_TENANT,
+		)
+
+		// Archive the thread directly — session is idle, so archive precondition
+		// holds via listSessions.
+		const threadManager = new ThreadManager({ threadStore, sessionStore: store })
+		await threadManager.archive(thread.id, DEFAULT_TENANT)
+
+		const driver = new GitWorktreeDriver({
+			repoRoot: '/repo',
+			logger: stubLogger(),
+			execFile: async () => okExec(),
+		})
+		const workspaceRegistry = new WorkspaceBackendRegistry()
+		workspaceRegistry.register(driver)
+
+		const events: HandoffEventSink = {
+			onLocked: vi.fn(),
+			onUnlocked: vi.fn(),
+			onCommitted: vi.fn(),
+			onBroadcastRollback: vi.fn(),
+		}
+		const deps: SingleHandoffDeps = {
+			store,
+			workspaceRegistry,
+			capacity: new DefaultCapacityValidator(store),
+			events,
+			threadManager,
+		}
+
+		const assignment: HandoffAssignment = {
+			id: generateHandoffId(),
+			mode: 'single',
+			sourceSessionId: session.id,
+			tenantId: DEFAULT_TENANT,
+			threadId: thread.id,
+			projectId: project.id,
+			sourceActor,
+			recipientActor: userActor('usr_target'),
+			expectedOwnerVersion: 0,
+			createdAt: new Date('2026-04-19'),
+		}
+
+		await expect(executeSingleHandoff(deps, assignment, DEFAULT_TENANT)).rejects.toBeInstanceOf(
+			ThreadClosedError,
+		)
+
+		// Critical: source session must still be idle (lock never acquired).
+		const reloaded = await store.getSession(session.id, DEFAULT_TENANT)
+		expect(reloaded?.status).toBe('idle')
+		expect(reloaded?.ownerVersion).toBe(0)
+		expect(events.onLocked).not.toHaveBeenCalled()
+	})
+
+	it('Broadcast handoff: rejects with ThreadClosedError when thread is archived (no CAS, no worktrees)', async () => {
+		const store = new InMemorySessionStore()
+		const threadStore = new InMemoryThreadStore()
+		const project = await store.createProject(
+			{ tenantId: DEFAULT_TENANT, name: 'archive-bc' },
+			DEFAULT_TENANT,
+		)
+		const thread = await threadStore.createThread(
+			{ projectId: project.id, title: 'archive-bc' },
+			DEFAULT_TENANT,
+		)
+		const source = await store.createSession(
+			{ threadId: thread.id, projectId: project.id, currentActor: userActor('usr_source') },
+			DEFAULT_TENANT,
+		)
+
+		const threadManager = new ThreadManager({ threadStore, sessionStore: store })
+		await threadManager.archive(thread.id, DEFAULT_TENANT)
+
+		let worktreeAdds = 0
+		const driver = new GitWorktreeDriver({
+			repoRoot: '/repo',
+			logger: stubLogger(),
+			execFile: async (_file, args) => {
+				if (args.includes('add')) worktreeAdds += 1
+				return okExec()
+			},
+		})
+		const workspaceRegistry = new WorkspaceBackendRegistry()
+		workspaceRegistry.register(driver)
+
+		const events: HandoffEventSink = {
+			onLocked: vi.fn(),
+			onUnlocked: vi.fn(),
+			onCommitted: vi.fn(),
+			onBroadcastRollback: vi.fn(),
+		}
+		const deps: BroadcastHandoffDeps = {
+			store,
+			workspaceRegistry,
+			capacity: new DefaultCapacityValidator(store),
+			events,
+			threadManager,
+		}
+
+		const assignments: HandoffAssignment[] = [userActor('usr_b'), userActor('usr_c')].map(
+			(recipientActor) => ({
+				id: generateHandoffId(),
+				mode: 'broadcast' as const,
+				sourceSessionId: source.id,
+				tenantId: DEFAULT_TENANT,
+				threadId: thread.id,
+				projectId: project.id,
+				sourceActor: userActor('usr_source'),
+				recipientActor,
+				expectedOwnerVersion: 0,
+				broadcastId: 'bc_archive',
+				createdAt: new Date('2026-04-19'),
+			}),
+		)
+
+		await expect(executeBroadcastHandoff(deps, assignments, DEFAULT_TENANT)).rejects.toBeInstanceOf(
+			ThreadClosedError,
+		)
+
+		// Source never locked, no worktrees provisioned, no rollback event —
+		// the archive gate short-circuited before any side-effect landed.
+		const reloaded = await store.getSession(source.id, DEFAULT_TENANT)
+		expect(reloaded?.status).toBe('idle')
+		expect(reloaded?.ownerVersion).toBe(0)
+		expect(events.onLocked).not.toHaveBeenCalled()
+		expect(events.onBroadcastRollback).not.toHaveBeenCalled()
+		expect(worktreeAdds).toBe(0)
+	})
+
+	it('Phase 2.6 closure: post-archive spawn via AgentManager rejects (kernel ingress path gated)', async () => {
+		// End-to-end proof that the production ingress path honors the
+		// archive status. Direct `SessionStore.createSession` / `updateSession`
+		// remain ungated at the store layer (by design — the store has no
+		// cross-store awareness), so this test exercises the manager path,
+		// not the store boundary.
+		const harness = buildHarness()
+		const { project, thread, session } = await seedActiveParent(harness)
+
+		await harness.store.updateSession({ ...session, status: 'idle' }, DEFAULT_TENANT)
+		await harness.threadManager.archive(thread.id, DEFAULT_TENANT)
+
+		// Attempt to spawn directly via context threading (bypass the fixture
+		// builder to prove the gate trips from AgentManager, not from the
+		// fixture).
+		harness.registry.register(buildDefinition(buildAgent('leaker')))
+
+		const childActor: ActorRef = {
+			kind: 'agent',
+			agentId: 'leaker' as AgentId,
+			tenantId: DEFAULT_TENANT,
+		}
+
+		// Flip session to active again so capacity checks pass and the
+		// archive-gate is what fails — not an earlier guard.
+		await harness.store.updateSession({ ...session, status: 'active' }, DEFAULT_TENANT)
+
+		await expect(
+			harness.manager.sendMessage(
+				{
+					agentId: 'leaker',
+					input: { messages: [], workingDirectory: '/tmp' },
+					parentSessionId: session.id,
+					tenantId: DEFAULT_TENANT,
+					projectId: project.id,
+					parentActor: childActor,
+				},
+				{
+					parentRunId: 'run_post_archive' as RunId,
+					parentAgentId: 'supervisor',
+					parentAbortController: new AbortController(),
+					depth: 0,
+					budgetTracker: { total: 10_000, remaining: 10_000 },
+					tenantId: DEFAULT_TENANT,
+					threadId: thread.id,
+					sessionId: session.id,
+					projectId: project.id,
+					parentActor: childActor,
+				},
+			),
+		).rejects.toBeInstanceOf(ThreadClosedError)
+
+		// The gate tripped before any observable side effect — listSessions
+		// still shows only the original seeded session, not a smuggled child.
+		const underThread = await harness.store.listSessions(thread.id, DEFAULT_TENANT)
+		expect(underThread).toHaveLength(1)
+		expect(underThread[0]?.id).toBe(session.id)
+	})
+})