@namzu/sdk 14.0.7 → 15.0.0

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

@@ -1,310 +0,0 @@
-/**
- * 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 { 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 { 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/a-successful-delegation-disposes-its-workspace.test.ts

@@ -1,270 +0,0 @@
-/**
- * A worktree provisioned for a delegated child outlived the child that used it.
- *
- * `finalizeChild` had two dispose sites and both were failure paths — the
- * non-success branch, and the rollback in `failSubSession`. The success branch
- * disposed nothing, so `.namzu/worktrees/` grew once per successful delegation:
- * the more reliable the workers, the faster it filled.
- *
- * The backstop could not fire either. `ArchivalManager` resolves a workspace
- * only when `SubSession.workspaceId` is set, and for a spawn-created
- * sub-session that field was written `null` and never updated —
- * `provisionSpawn` kept the ref on the in-memory `ChildSpawnRecord` and nowhere
- * else. So the one record that could have named the leaked worktree said there
- * was none.
- *
- * Both halves are pinned here, and the failure path is re-asserted alongside
- * them: a test that only counted disposals would pass on the old code by
- * reading the failure branch's disposal and calling it the success branch's.
- */
-
-import { describe, expect, it } 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 { RunId, TenantId, UserId, WorkspaceId } 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 { SessionSummaryMaterializer } from '../../summary/materialize.js'
-import type {
-	BranchWorkspaceParams,
-	CreateWorkspaceParams,
-	WorkspaceBackendDriver,
-	WorkspaceInspection,
-} from '../../workspace/driver.js'
-import { WorkspaceBackendRegistry } from '../../workspace/registry.js'
-
-const tenant = 'tnt_alpha' as TenantId
-
-const capabilities: AgentCapabilities = {
-	supportsTools: false,
-	supportsStreaming: false,
-	supportsConcurrency: false,
-	supportsSubAgents: false,
-}
-
-/** A child that settles the way `outcome` says, so both branches are reachable. */
-function buildAgent(
-	id: string,
-	outcome: 'completed' | 'failed',
-): Agent<BaseAgentConfig, BaseAgentResult> {
-	return {
-		type: 'reactive',
-		metadata: {
-			type: 'reactive',
-			id,
-			name: id,
-			version: '1.0.0',
-			category: 'test',
-			description: id,
-			capabilities,
-		},
-		run: async (_input: AgentInput, _config: BaseAgentConfig): Promise<BaseAgentResult> => ({
-			runId: 'run_child' as RunId,
-			status: outcome,
-			usage: { ...EMPTY_TOKEN_USAGE },
-			cost: { ...ZERO_COST },
-			iterations: 1,
-			durationMs: 1,
-			messages: [createAssistantMessage('child did the work')],
-			result: 'child did the work',
-		}),
-		cancel: async () => undefined,
-		getCapabilities: () => capabilities,
-	}
-}
-
-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,
-	}
-}
-
-/** Provisions successfully and records every ref it is asked to dispose. */
-class RecordingWorkspaceDriver implements WorkspaceBackendDriver {
-	readonly kind = 'git-worktree' as const
-	readonly created: WorkspaceRef[] = []
-	readonly disposed: WorkspaceId[] = []
-	private counter = 0
-
-	async create(params: CreateWorkspaceParams): Promise<WorkspaceRef> {
-		const ref: WorkspaceRef = {
-			id: `wsp_test_${++this.counter}` as WorkspaceId,
-			meta: {
-				backend: 'git-worktree',
-				repoRoot: '/tmp/repo',
-				branch: `namzu/${params.label ?? 'unlabelled'}`,
-				worktreePath: `/tmp/repo/.namzu/worktrees/${params.label ?? 'unlabelled'}`,
-			},
-			createdAt: new Date(),
-		}
-		this.created.push(ref)
-		return ref
-	}
-
-	async branch(_source: WorkspaceRef, _params: BranchWorkspaceParams): Promise<WorkspaceRef> {
-		throw new Error('unused in this test')
-	}
-
-	async dispose(ref: WorkspaceRef): Promise<void> {
-		this.disposed.push(ref.id)
-	}
-
-	async inspect(_ref: WorkspaceRef): Promise<WorkspaceInspection> {
-		throw new Error('unused in this test')
-	}
-}
-
-/**
- * Stands up a Project → Thread → parent Session and an AgentManager wired to a
- * recording workspace driver. `outcome` decides how the delegated child ends;
- * `registerBackend: false` leaves the registry empty, which is the supported
- * lazy-provisioning configuration rather than an error (pattern doc §7.1).
- */
-async function harness(
-	outcome: 'completed' | 'failed',
-	{ registerBackend = true }: { registerBackend?: boolean } = {},
-) {
-	const store = new InMemorySessionStore()
-	const threadStore = new InMemoryThreadStore()
-	const project = await store.createProject({ tenantId: tenant, name: 'workspace-project' }, tenant)
-	const thread = await threadStore.createThread(
-		{ projectId: project.id, title: 'workspace-topic' },
-		tenant,
-	)
-
-	const userActor: ActorRef = { kind: 'user', userId: 'usr_root' as UserId, tenantId: tenant }
-
-	const parentSession = await store.createSession(
-		{ threadId: thread.id, projectId: project.id, currentActor: userActor },
-		tenant,
-	)
-	await store.updateSession({ ...parentSession, status: 'active' }, tenant)
-
-	let summaryCounter = 0
-	const materializer = new SessionSummaryMaterializer({
-		store,
-		generateSummaryId: () => `sum_test_${++summaryCounter}` as SummaryId,
-	})
-
-	const registry = new AgentRegistry()
-	registry.register(buildDefinition(buildAgent('worker', outcome)))
-
-	const workspaceRegistry = new WorkspaceBackendRegistry()
-	const driver = new RecordingWorkspaceDriver()
-	if (registerBackend) workspaceRegistry.register(driver)
-
-	const manager = new AgentManager(registry, undefined, {
-		sessionStore: store,
-		summaryMaterializer: materializer,
-		workspaceRegistry,
-		capacity: new DefaultCapacityValidator(store),
-		threadManager: new ThreadManager({ threadStore, sessionStore: store }),
-	})
-
-	const taskContext: AgentTaskContext = {
-		parentRunId: 'run_parent' as RunId,
-		parentAgentId: 'supervisor',
-		parentAbortController: new AbortController(),
-		depth: 0,
-		budgetTracker: { total: 100_000, remaining: 100_000 },
-		tenantId: tenant,
-		threadId: thread.id,
-		sessionId: parentSession.id,
-		projectId: project.id,
-		parentActor: userActor,
-	}
-
-	const options: SendMessageOptions = {
-		agentId: 'worker',
-		input: { messages: [], workingDirectory: '/tmp' },
-		parentSessionId: parentSession.id,
-		tenantId: tenant,
-		projectId: project.id,
-		parentActor: userActor,
-		workspaceBackend: 'git-worktree',
-	}
-
-	return { store, manager, driver, parentSession, options, taskContext }
-}
-
-describe('a delegated child does not outlive its workspace', () => {
-	it('disposes the workspace when the child SUCCEEDS', async () => {
-		const { manager, driver, options, taskContext } = await harness('completed')
-
-		const task = await manager.sendMessage(options, taskContext)
-		await manager.waitForCompletion(task.taskId)
-
-		expect(manager.getState(task.taskId)).toBe('completed')
-		expect(driver.created).toHaveLength(1)
-		// The assertion the leak fails: one workspace made, the same one released.
-		expect(driver.disposed).toEqual([driver.created[0]?.id])
-	})
-
-	it('still disposes the workspace when the child FAILS', async () => {
-		const { manager, driver, options, taskContext } = await harness('failed')
-
-		const task = await manager.sendMessage(options, taskContext)
-		await manager.waitForCompletion(task.taskId)
-
-		expect(driver.created).toHaveLength(1)
-		expect(driver.disposed).toEqual([driver.created[0]?.id])
-	})
-
-	it('records the workspace on the sub-session, so archival can find it', async () => {
-		const { store, manager, driver, parentSession, options, taskContext } =
-			await harness('completed')
-
-		const task = await manager.sendMessage(options, taskContext)
-		await manager.waitForCompletion(task.taskId)
-
-		const [subSession] = await store.getChildren(parentSession.id, tenant)
-		expect(subSession).toBeDefined()
-		// Was `null` on every spawn-created sub-session, which is what made
-		// `ArchivalManager`'s `sub.workspaceId &&` guard unreachable here.
-		expect(subSession?.workspaceId).toBe(driver.created[0]?.id)
-	})
-
-	it('leaves workspaceId null when no backend is registered', async () => {
-		// Lazy provisioning stays legal (pattern doc §7.1): an unregistered
-		// backend is not an error, and the record must not claim a workspace
-		// that was never made.
-		const { store, manager, driver, parentSession, options, taskContext } = await harness(
-			'completed',
-			{ registerBackend: false },
-		)
-
-		const task = await manager.sendMessage(options, taskContext)
-		await manager.waitForCompletion(task.taskId)
-
-		expect(manager.getState(task.taskId)).toBe('completed')
-		expect(driver.created).toHaveLength(0)
-		const [subSession] = await store.getChildren(parentSession.id, tenant)
-		expect(subSession?.workspaceId).toBeNull()
-	})
-})