@namzu/sdk 14.0.7 → 15.0.0

package/src/gateway/__tests__/list-survives-eviction.test.ts

@@ -1,124 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-
-import type { AgentTask } from '../../types/agent/task.js'
-import type { TaskId } from '../../types/ids/index.js'
-import { LocalTaskGateway } from '../local.js'
-
-/**
- * `listTasks` skipped every task the manager had evicted.
- *
- * Terminal tasks are dropped from the manager 30 seconds after they settle,
- * and the gateway's list is built by looking each tracked id back up. A
- * task that finished 31 seconds ago therefore vanished — from the exact
- * tool whose description says to call it before declaring multi-worker work
- * done, to "confirm every launched task reached completed".
- *
- * A supervisor that fanned out five workers and checked at the end saw
- * three, and could not tell a task that was evicted from one that never
- * launched. Both look like absence.
- *
- * Eviction exists to release the heavy per-task state — messages, abort
- * controllers, spawn records — not to forget that a task existed. The
- * gateway keeps the settled summary, which is a few fields.
- */
-
-function terminalTask(taskId: string, state: 'completed' | 'failed'): AgentTask {
-	return {
-		taskId: taskId as TaskId,
-		agentId: 'worker',
-		state,
-		createdAt: 1_000,
-		completedAt: 2_000,
-		pendingMessages: [],
-		childAbortController: new AbortController(),
-		context: {},
-		result: { status: state === 'failed' ? 'failed' : 'completed' },
-	} as unknown as AgentTask
-}
-
-/** A manager that forgets a task, exactly as eviction does. */
-function managerWith(tasks: Map<string, AgentTask>) {
-	return {
-		getInstance: (id: TaskId) => tasks.get(id),
-		waitForCompletion: vi.fn(async () => {}),
-		cancel: vi.fn(),
-		spawn: vi.fn(),
-	}
-}
-
-function gatewayOver(manager: ReturnType<typeof managerWith>, trackedIds: string[]) {
-	const gateway = Object.create(LocalTaskGateway.prototype) as LocalTaskGateway
-	Object.assign(gateway, {
-		agentManager: manager,
-		trackedTaskIds: new Set(trackedIds as TaskId[]),
-		completionListeners: new Set(),
-		settledHandles: new Map(),
-		siblingFailurePolicy: 'continue',
-	})
-	return gateway
-}
-
-describe('a finished task stays listed after it is evicted', () => {
-	it('lists a task the manager still holds', () => {
-		const tasks = new Map([['task_a', terminalTask('task_a', 'completed')]])
-		const gateway = gatewayOver(managerWith(tasks), ['task_a'])
-
-		gateway.rememberSettled('task_a' as TaskId)
-		tasks.delete('task_a')
-
-		const listed = gateway.listTasks()
-		expect(listed).toHaveLength(1)
-		expect(listed[0]?.taskId).toBe('task_a')
-		expect(listed[0]?.state).toBe('completed')
-	})
-
-	it('keeps a failure visible, which is the one that matters most', () => {
-		const tasks = new Map([['task_b', terminalTask('task_b', 'failed')]])
-		const gateway = gatewayOver(managerWith(tasks), ['task_b'])
-
-		gateway.rememberSettled('task_b' as TaskId)
-		tasks.delete('task_b')
-
-		expect(gateway.listTasks()[0]?.state).toBe('failed')
-	})
-
-	it('prefers the live task over the remembered one while both exist', () => {
-		const live = terminalTask('task_c', 'completed')
-		const tasks = new Map([['task_c', live]])
-		const gateway = gatewayOver(managerWith(tasks), ['task_c'])
-
-		gateway.rememberSettled('task_c' as TaskId)
-		// The snapshot is now stale. The live record is authoritative: a
-		// remembered handle must never shadow state still being updated —
-		// a `continueTask` reopens a task the gateway already snapshotted.
-		;(live as { completedAt: number }).completedAt = 9_999
-		;(live as { state: string }).state = 'running'
-
-		expect(gateway.listTasks()[0]?.completedAt).toBe(9_999)
-		expect(gateway.listTasks()[0]?.state).toBe('running')
-	})
-
-	it('reports nothing for a tracked id that never settled and is already gone', () => {
-		const gateway = gatewayOver(managerWith(new Map()), ['task_d'])
-
-		// Nothing to report is still correct here — the point is that a task
-		// which DID settle is not silently indistinguishable from this.
-		expect(gateway.listTasks()).toHaveLength(0)
-	})
-
-	it('lists every worker after all of them are evicted', () => {
-		const tasks = new Map([
-			['task_1', terminalTask('task_1', 'completed')],
-			['task_2', terminalTask('task_2', 'failed')],
-			['task_3', terminalTask('task_3', 'completed')],
-		])
-		const gateway = gatewayOver(managerWith(tasks), ['task_1', 'task_2', 'task_3'])
-
-		for (const id of tasks.keys()) gateway.rememberSettled(id as TaskId)
-		tasks.clear()
-
-		const listed = gateway.listTasks()
-		expect(listed).toHaveLength(3)
-		expect(listed.filter((h) => h.state === 'failed')).toHaveLength(1)
-	})
-})

package/src/manager/agent/__tests__/a-fan-out-to-one-agent-id.test.ts

@@ -1,118 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { ReactiveAgent } from '../../../agents/ReactiveAgent.js'
-import { ToolRegistry } from '../../../registry/index.js'
-import type { AgentDefinition } from '../../../types/agent/factory.js'
-
-/**
- * A fan-out naming the same agent four times ran one child and lost three.
- *
- * `AgentRegistry` hands out ONE `typedAgent` per registered id, and an instance
- * refuses a second concurrent `run` — correctly, because its abort controller
- * and run id are instance state and two overlapping runs would cancel each
- * other. So four `create_task` calls at one specialist produced one result and
- * three `ConcurrentInvocationError`s.
- *
- * The prescribed remedy already existed in the docs — "a host that wants
- * parallelism constructs a second instance" — and was unreachable from
- * delegation, where the definition owns the instance and the caller has only an
- * id. Observed live on published 12.0.1: four launches, three lost.
- *
- * These cover the shell itself. That the manager USES it per spawn is covered
- * where the manager is driven; what has to hold here is that asking for a
- * per-run shell gives you a genuinely separate one.
- */
-
-const metadata = {
-	id: 'worker',
-	name: 'worker',
-	version: '1.0.0',
-	category: 'general',
-	description: 'a worker',
-}
-
-describe('an agent can hand out a shell a single run has to itself', () => {
-	it('returns a different instance', () => {
-		const agent = new ReactiveAgent(metadata)
-
-		expect(agent.forRun()).not.toBe(agent)
-	})
-
-	it('keeps the identity, because it is the same agent', () => {
-		const agent = new ReactiveAgent(metadata)
-		const shell = agent.forRun()
-
-		expect(shell.metadata.id).toBe('worker')
-		expect(shell.type).toBe(agent.type)
-		expect(shell.getCapabilities()).toEqual(agent.getCapabilities())
-	})
-
-	it('gives each shell its own invocation lock, which is the whole point', async () => {
-		// Locking one must not lock the other. Asserted through the public
-		// surface: a run that never settles holds the lock, and a second run on
-		// a SEPARATE shell must still be admitted.
-		// ONE registered agent, two shells — the registry's shape, and the
-		// shape the fan-out actually hits.
-		const registered = new ReactiveAgent(metadata)
-		const first = registered.forRun()
-		const second = registered.forRun()
-
-		// A provider that starts and never finishes, so each run holds its
-		// shell's lock for the duration of the assertion.
-		const provider = {
-			// biome-ignore lint/correctness/useYield: it never produces anything, on purpose
-			async *chatStream() {
-				await new Promise<never>(() => {})
-			},
-		}
-		const config = {
-			model: 'mock',
-			tokenBudget: 10_000,
-			timeoutMs: 10_000,
-			maxIterations: 2,
-			provider,
-			tools: new ToolRegistry(),
-			systemPrompt: 'hold',
-			sessionId: 'ses_fan' as never,
-			threadId: 'thd_fan' as never,
-			projectId: 'prj_fan' as never,
-			tenantId: 'tnt_fan' as never,
-		}
-
-		// Start one run on each shell; neither resolves, and neither should
-		// refuse. A shared shell would reject the second synchronously.
-		const a = first.run({ messages: [], workingDirectory: '/tmp' } as never, config as never)
-		const b = second.run({ messages: [], workingDirectory: '/tmp' } as never, config as never)
-
-		await expect(
-			Promise.race([
-				Promise.all([a, b]).then(() => 'settled'),
-				new Promise((r) => setTimeout(() => r('still running'), 50)),
-			]),
-		).resolves.toBe('still running')
-
-		void a.catch(() => {})
-		void b.catch(() => {})
-	})
-
-	it('a definition may override the shell with its own factory', () => {
-		// The escape hatch for an agent that needs real construction
-		// arguments, which `forRun`'s metadata-only rebuild cannot supply.
-		let built = 0
-		const definition: AgentDefinition = {
-			info: { ...metadata, tools: [], defaults: {} } as never,
-			typedAgent: new ReactiveAgent(metadata) as never,
-			createAgent: () => {
-				built += 1
-				return new ReactiveAgent(metadata) as never
-			},
-		}
-
-		const one = definition.createAgent?.()
-		const two = definition.createAgent?.()
-
-		expect(built).toBe(2)
-		expect(one).not.toBe(two)
-		expect(one).not.toBe(definition.typedAgent)
-	})
-})

package/src/manager/agent/__tests__/an-env-reaches-the-child-it-was-set-for.test.ts

@@ -1,196 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { EMPTY_TOKEN_USAGE } from '../../../constants/limits.js'
-import { AgentRegistry } from '../../../registry/agent/definitions.js'
-import { DefaultCapacityValidator } from '../../../session/handoff/capacity.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 { 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 } from '../../../types/agent/task.js'
-import type { AgentId, TenantId } from '../../../types/ids/index.js'
-import type { SummaryId } from '../../../types/session/ids.js'
-import { ZERO_COST } from '../../../utils/cost.js'
-import { ThreadManager } from '../../thread/lifecycle.js'
-import { AgentManager } from '../lifecycle.js'
-
-/**
- * A delegate registered the normal way inherited no environment at all.
- *
- * `AgentManager` builds a child's config on two branches. The bare-config
- * branch — taken only when a definition has NO `configBuilder` — has always
- * carried `env`. The `configBuilder` branch, which is what a host registering
- * a real agent actually uses, never stamped it. So a run given an environment
- * handed its delegates none of it.
- *
- * This is the third field to go the same way: `parentSpan` and `resumeHandler`
- * are both stamped after the builder returns, each with a comment saying the
- * builder is written by whoever registered the agent and cannot be expected to
- * forward something it was never told about. `env` was missed, and it went
- * unnoticed because a missing environment does not fail — the child just runs
- * somewhere else.
- *
- * These drive the real `AgentManager` rather than re-implementing the merge.
- * A test that restates the logic proves the logic agrees with itself; what has
- * to hold is that the manager applies it.
- */
-
-const TENANT = 'tnt_env' as TenantId
-
-/** Records the config it is run with, so the assertion is on what shipped. */
-function recordingAgent(seen: { config?: BaseAgentConfig }) {
-	return {
-		type: 'reactive',
-		metadata: {
-			id: 'worker',
-			name: 'worker',
-			version: '1.0.0',
-			category: 'general',
-			description: 'records its config',
-			type: 'reactive',
-			capabilities: {},
-		},
-		async run(_input: unknown, config: BaseAgentConfig): Promise<BaseAgentResult> {
-			seen.config = config
-			return {
-				runId: 'run_child',
-				status: 'completed',
-				result: 'ok',
-				usage: { ...EMPTY_TOKEN_USAGE },
-				cost: { ...ZERO_COST },
-				iterations: 1,
-				durationMs: 0,
-				messages: [],
-			} as BaseAgentResult
-		},
-		async cancel() {},
-		getCapabilities() {
-			return {} as never
-		},
-	} as unknown as Agent<BaseAgentConfig, BaseAgentResult>
-}
-
-/** A definition WITH a configBuilder — the branch that dropped `env`. */
-function definitionWithBuilder(
-	agent: Agent<BaseAgentConfig, BaseAgentResult>,
-	builderEnv?: Record<string, string>,
-): AgentDefinition {
-	return {
-		info: {
-			id: 'worker',
-			name: 'worker',
-			version: '1.0.0',
-			category: 'general',
-			description: 'a worker',
-			tools: [],
-			defaults: { model: 'test', tokenBudget: 1_000 },
-		},
-		typedAgent: agent,
-		configBuilder: () =>
-			({
-				model: 'test',
-				tokenBudget: 1_000,
-				timeoutMs: 10_000,
-				...(builderEnv ? { env: builderEnv } : {}),
-			}) as BaseAgentConfig,
-	} as AgentDefinition
-}
-
-async function spawnWith(options: {
-	builderEnv?: Record<string, string>
-	overrideEnv?: Record<string, string>
-}): Promise<BaseAgentConfig | undefined> {
-	const seen: { config?: BaseAgentConfig } = {}
-	const store = new InMemorySessionStore()
-	const threadStore = new InMemoryThreadStore()
-	const project = await store.createProject({ tenantId: TENANT, name: 'p' }, TENANT)
-	const thread = await threadStore.createThread({ projectId: project.id, title: 't' }, TENANT)
-	const parentActor = { kind: 'agent', agentId: 'sup' as AgentId, tenantId: TENANT } as const
-	const parentSession = await store.createSession(
-		{ threadId: thread.id, projectId: project.id, currentActor: parentActor },
-		TENANT,
-	)
-	await store.updateSession({ ...parentSession, status: 'active' }, TENANT)
-
-	const registry = new AgentRegistry()
-	registry.register(definitionWithBuilder(recordingAgent(seen), options.builderEnv))
-
-	let n = 0
-	const manager = new AgentManager(registry, undefined, {
-		sessionStore: store,
-		threadManager: new ThreadManager({ threadStore, sessionStore: store }),
-		workspaceRegistry: new WorkspaceBackendRegistry(),
-		capacity: new DefaultCapacityValidator(store),
-		summaryMaterializer: new SessionSummaryMaterializer({
-			store,
-			generateSummaryId: () => `sum_${++n}` as SummaryId,
-		}),
-	})
-
-	const context: AgentTaskContext = {
-		parentRunId: 'run_parent' as never,
-		parentAgentId: 'sup',
-		parentAbortController: new AbortController(),
-		depth: 0,
-		budgetTracker: { total: 100_000, remaining: 100_000 },
-		tenantId: TENANT,
-		threadId: thread.id,
-		sessionId: parentSession.id,
-		projectId: project.id,
-		parentActor,
-	} as AgentTaskContext
-
-	const task = await manager.sendMessage(
-		{
-			agentId: 'worker',
-			input: { messages: [], workingDirectory: '/tmp' } as never,
-			parentSessionId: parentSession.id,
-			tenantId: TENANT,
-			projectId: project.id,
-			parentActor,
-			...(options.overrideEnv ? { configOverrides: { env: options.overrideEnv } } : {}),
-		} as never,
-		context,
-	)
-
-	await manager.waitForCompletion(task.taskId)
-	return seen.config
-}
-
-describe('an environment survives a configBuilder that never heard of it', () => {
-	it('reaches a child whose builder sets none', async () => {
-		const config = await spawnWith({ overrideEnv: { API_BASE: 'https://staging' } })
-
-		expect(config?.env).toEqual({ API_BASE: 'https://staging' })
-	})
-
-	it('keeps the builder keys the caller did not restate', async () => {
-		// Why this is a merge and not an assignment: `configOverrides` is a
-		// Partial, so replacing the map would drop everything the builder set,
-		// and a caller overriding one variable is not saying the rest should
-		// vanish.
-		const config = await spawnWith({
-			builderEnv: { REGION: 'eu', TIER: 'free' },
-			overrideEnv: { TIER: 'paid' },
-		})
-
-		expect(config?.env).toEqual({ REGION: 'eu', TIER: 'paid' })
-	})
-
-	it('leaves the builder environment alone when nothing overrides it', async () => {
-		const config = await spawnWith({ builderEnv: { REGION: 'eu' } })
-
-		expect(config?.env).toEqual({ REGION: 'eu' })
-	})
-
-	it('gives a child with no environment undefined rather than an empty map', async () => {
-		// An agent that never had an environment must not gain an empty object
-		// that every reader then has to tell apart from a real one.
-		const config = await spawnWith({})
-
-		expect(config?.env).toBeUndefined()
-	})
-})

package/src/manager/agent/__tests__/depth-limit-authority.test.ts

@@ -1,74 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-
-import type { AgentTaskContext } from '../../../types/agent/index.js'
-
-/**
- * Which `maxDepth` is in force.
- *
- * Two exist. `AgentManagerConfig.maxDepth` is enforced in
- * `AgentManager.sendMessage`; `SupervisorAgentConfig.maxDepth` is read by
- * nothing. For a recursion bound that is the worst way to be wrong — the
- * number a reviewer sees in the supervisor config is not the number
- * stopping runaway delegation.
- *
- * The first version of these tests passed the config where the registry
- * goes, so every case silently ran against the default of 3 — and the case
- * that used 3 "passed" while proving nothing. Configuring a value the
- * default is not is what makes this a test.
- */
-
-async function manager(maxDepth: number) {
-	const { AgentManager } = await import('../lifecycle.js')
-	const registry = { resolve: vi.fn(), get: vi.fn(), getAll: vi.fn(() => []) }
-	const deps = { createAgent: vi.fn(), taskStore: undefined }
-	return new AgentManager(registry as never, { maxDepth }, deps as never)
-}
-
-function contextAtDepth(depth: number): AgentTaskContext {
-	return {
-		parentRunId: 'run_x',
-		parentAgentId: 'agent_x',
-		parentAbortController: new AbortController(),
-		depth,
-		tenantId: 'tnt_x',
-	} as unknown as AgentTaskContext
-}
-
-function send(m: Awaited<ReturnType<typeof manager>>, depth: number) {
-	return m.sendMessage(
-		{ agentId: 'a', prompt: 'go', tenantId: 'tnt_x' } as never,
-		contextAtDepth(depth),
-	)
-}
-
-describe('the manager owns the recursion bound', () => {
-	it('refuses a task at the configured depth', async () => {
-		// 5, deliberately not the default of 3: a limit that happens to equal
-		// the default cannot tell "configured" from "ignored".
-		const mgr = await manager(5)
-
-		await expect(send(mgr, 5)).rejects.toThrow(/Max task depth 5/)
-	})
-
-	it('refuses past it too, not only exactly at it', async () => {
-		const mgr = await manager(2)
-
-		await expect(send(mgr, 7)).rejects.toThrow(/Max task depth 2/)
-	})
-
-	it('reports the depth reached alongside the limit', async () => {
-		const mgr = await manager(2)
-
-		// A limit without the current value sends someone to instrument the
-		// run to learn how deep it actually got.
-		await expect(send(mgr, 4)).rejects.toThrow(/current: 4/)
-	})
-
-	it('allows a task below the bound to proceed past this check', async () => {
-		const mgr = await manager(5)
-
-		// It gets past the depth gate and fails later on the stubbed
-		// registry — which is the point: the gate did not stop it.
-		await expect(send(mgr, 1)).rejects.not.toThrow(/Max task depth/)
-	})
-})

package/src/manager/agent/__tests__/dispose-cancels.test.ts

@@ -1,104 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { AgentRegistry } from '../../../registry/agent/definitions.js'
-import { DefaultCapacityValidator } from '../../../session/handoff/capacity.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 { RunId, TaskId } from '../../../types/ids/index.js'
-import type { SummaryId } from '../../../types/session/ids.js'
-import { ThreadManager } from '../../thread/lifecycle.js'
-import { AgentManager } from '../lifecycle.js'
-
-/**
- * `dispose()` cancelled nothing.
- *
- * It called `cancelAll('' as RunId)`, and `cancelAll` filters by
- * `context.parentRunId`. No task has an empty parent, so the filter matched
- * nothing — and the next lines cleared the instance map. Every live child
- * was released without its abort controller firing: the work kept running,
- * the budget kept draining, and nothing was left holding a reference to
- * stop it.
- *
- * The `'' as RunId` cast is the tell. A value invented to satisfy a
- * parameter usually means the parameter is the wrong one to pass.
- */
-
-function makeManager(): AgentManager {
-	const store = new InMemorySessionStore()
-	return new AgentManager(new AgentRegistry(), undefined, {
-		sessionStore: store,
-		summaryMaterializer: new SessionSummaryMaterializer({
-			store,
-			generateSummaryId: () => 'sum_dispose' as SummaryId,
-		}),
-		workspaceRegistry: new WorkspaceBackendRegistry(),
-		capacity: new DefaultCapacityValidator(store),
-		threadManager: new ThreadManager({
-			threadStore: new InMemoryThreadStore(),
-			sessionStore: store,
-		}),
-	})
-}
-
-/**
- * Registers a live task directly. Going through `sendMessage` would run the
- * agent to completion, and a terminal task is exactly the one `dispose` was
- * never broken for.
- */
-function addLiveTask(manager: AgentManager, taskId: string, parentRunId: string): AbortController {
-	const controller = new AbortController()
-	const instances = (manager as unknown as { instances: Map<TaskId, unknown> }).instances
-	instances.set(taskId as TaskId, {
-		taskId: taskId as TaskId,
-		state: 'running',
-		childAbortController: controller,
-		pendingMessages: [],
-		context: { parentRunId: parentRunId as RunId },
-	})
-	return controller
-}
-
-describe('disposing the manager stops the work it was holding', () => {
-	it('aborts a live child spawned under any run', () => {
-		const manager = makeManager()
-		// Two parents: the shape the old code could not see, because it
-		// looked for one specific parent and invented the value it looked for.
-		const a = addLiveTask(manager, 'task_a', 'run_1')
-		const b = addLiveTask(manager, 'task_b', 'run_2')
-
-		manager.dispose()
-
-		expect(a.signal.aborted).toBe(true)
-		expect(b.signal.aborted).toBe(true)
-	})
-
-	it('empties its maps afterwards', () => {
-		const manager = makeManager()
-		addLiveTask(manager, 'task_a', 'run_1')
-
-		manager.dispose()
-
-		expect((manager as unknown as { instances: Map<TaskId, unknown> }).instances.size).toBe(0)
-	})
-
-	it('is safe to call twice', () => {
-		const manager = makeManager()
-		addLiveTask(manager, 'task_a', 'run_1')
-
-		manager.dispose()
-		expect(() => manager.dispose()).not.toThrow()
-	})
-
-	it('leaves cancelAll scoped to one parent, which is its whole job', () => {
-		const manager = makeManager()
-		const mine = addLiveTask(manager, 'task_a', 'run_1')
-		const theirs = addLiveTask(manager, 'task_b', 'run_2')
-
-		manager.cancelAll('run_1' as RunId)
-
-		expect(mine.signal.aborted).toBe(true)
-		expect(theirs.signal.aborted).toBe(false)
-	})
-})