@namzu/sdk 2.0.0 → 3.0.0

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

@@ -0,0 +1,124 @@
+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/gateway/local.ts

@@ -1,5 +1,10 @@
 import type { AgentInput } from '../types/agent/base.js'
-import type { CreateTaskOptions, TaskGateway, TaskHandle } from '../types/agent/gateway.js'
+import type {
+	CreateTaskOptions,
+	SiblingFailurePolicy,
+	TaskGateway,
+	TaskHandle,
+} from '../types/agent/gateway.js'
 import type { AgentManagerContract } from '../types/agent/manager.js'
 import type { AgentTaskContext } from '../types/agent/task.js'
 import type { TaskId } from '../types/ids/index.js'
@@ -18,16 +23,37 @@ export class LocalTaskGateway implements TaskGateway {
 
 	private completionListeners: Set<(handle: TaskHandle) => void> = new Set()
 
+	/**
+	 * The settled summary of each task, kept past the manager's eviction.
+	 *
+	 * Terminal tasks leave the manager 30 seconds after they finish, and
+	 * `listTasks` rebuilt itself by looking every tracked id back up — so a
+	 * task that finished a minute ago simply vanished from the tool whose
+	 * whole job is the end-of-run check. A supervisor could not tell an
+	 * evicted task from one that never launched; both read as absence.
+	 *
+	 * Eviction is there to release the heavy state — messages, controllers,
+	 * spawn records — not the fact that the task ran. This is a handful of
+	 * fields per task, bounded by the number the gateway itself launched.
+	 */
+	private settledHandles: Map<TaskId, TaskHandle> = new Map()
+
+	private siblingFailurePolicy: SiblingFailurePolicy = 'continue'
+
 	constructor(
 		agentManager: AgentManagerContract,
 		taskContext: AgentTaskContext,
 		listener?: RunEventListener,
 		parentInput?: Pick<AgentInput, 'taskStore' | 'runtimeToolOverrides' | 'runtimeContext'>,
+		options?: { siblingFailurePolicy?: SiblingFailurePolicy },
 	) {
 		this.agentManager = agentManager
 		this.taskContext = taskContext
 		this.listener = listener
 		this.parentInput = parentInput
+		if (options?.siblingFailurePolicy) {
+			this.siblingFailurePolicy = options.siblingFailurePolicy
+		}
 	}
 
 	async createTask(options: CreateTaskOptions): Promise<TaskHandle> {
@@ -47,8 +73,19 @@ export class LocalTaskGateway implements TaskGateway {
 				tenantId: this.taskContext.tenantId,
 				projectId: this.taskContext.projectId,
 				parentActor: this.taskContext.parentActor,
+				// Hang the child run off the span the caller supplied, so a
+				// delegated run joins the trace it belongs to instead of
+				// starting its own root.
+				...(options.parentSpan ? { configOverrides: { parentSpan: options.parentSpan } } : {}),
 			},
-			{ ...this.taskContext, budgetTracker: { ...this.taskContext.budgetTracker } },
+			// The budget tracker is SHARED on purpose and must not be cloned.
+			// `AgentManager.spawn` debits it (`remaining -= allocatedTokens`)
+			// so siblings divide one pool; handing each spawn a fresh copy
+			// made the debit land on a throwaway object, so every child saw
+			// the parent's untouched `remaining` and N children were each
+			// allocated `maxBudgetFraction` of the SAME number — N x 50% of a
+			// budget that only had 100% in it.
+			this.taskContext,
 			this.listener,
 		)
 
@@ -60,6 +97,10 @@ export class LocalTaskGateway implements TaskGateway {
 				const completed = this.agentManager.getInstance(task.taskId)
 				if (completed) {
 					const handle = toHandle(completed)
+					// Snapshot now, while the manager still holds it — in 30
+					// seconds eviction takes the record away.
+					this.settledHandles.set(task.taskId, handle)
+					this.applySiblingPolicy(handle)
 					for (const cb of this.completionListeners) {
 						cb(handle)
 					}
@@ -77,6 +118,48 @@ export class LocalTaskGateway implements TaskGateway {
 		return toHandle(task)
 	}
 
+	/**
+	 * Decide what a failed child means for the ones still running.
+	 *
+	 * The primitive to stop them already existed — every child holds an
+	 * abort controller chained to the parent's, and `AgentManager.cancel`
+	 * uses it — but nothing connected a failure to it. So a supervisor that
+	 * fanned out five tasks and watched one die had no way to say the other
+	 * four were now pointless: they ran to completion spending budget on
+	 * work whose premise had gone.
+	 *
+	 * `'continue'` stays the default, and deliberately. Partial results are
+	 * usually worth having, and a policy that tore down healthy siblings on
+	 * any failure would make one flaky child able to waste four good ones.
+	 * The point is that the choice is now expressible, not that the answer
+	 * changed.
+	 */
+	private applySiblingPolicy(finished: TaskHandle): void {
+		if (this.siblingFailurePolicy !== 'cancel-siblings') return
+		if (!hasFailed(finished)) return
+
+		const cancelled: TaskId[] = []
+		for (const taskId of this.trackedTaskIds) {
+			if (taskId === finished.taskId) continue
+			const sibling = this.agentManager.getInstance(taskId)
+			// `cancel` is already a no-op on a terminal task, but checking
+			// here keeps the log honest about what was actually stopped.
+			if (!sibling || sibling.state === 'completed' || sibling.state === 'failed') continue
+			this.agentManager.cancel(taskId)
+			cancelled.push(taskId)
+		}
+
+		if (cancelled.length > 0) {
+			getRootLogger()
+				.child({ component: 'LocalTaskGateway' })
+				.info('Cancelled siblings after a child failed', {
+					failed: finished.taskId,
+					agentId: finished.agentId,
+					cancelled,
+				})
+		}
+	}
+
 	async waitForTask(taskId: TaskId): Promise<TaskHandle> {
 		await this.agentManager.waitForCompletion(taskId)
 		const task = this.agentManager.getInstance(taskId)
@@ -99,11 +182,28 @@ export class LocalTaskGateway implements TaskGateway {
 		return task ? toHandle(task) : undefined
 	}
 
+	/**
+	 * Snapshots a task's terminal state so it survives eviction.
+	 *
+	 * Called when the task settles, while the manager still holds it.
+	 */
+	rememberSettled(taskId: TaskId): void {
+		const task = this.agentManager.getInstance(taskId)
+		if (task) this.settledHandles.set(taskId, toHandle(task))
+	}
+
 	listTasks(): TaskHandle[] {
 		const handles: TaskHandle[] = []
 		for (const taskId of this.trackedTaskIds) {
+			// The live task wins: a remembered snapshot must never shadow
+			// state that is still being updated.
 			const task = this.agentManager.getInstance(taskId)
-			if (task) handles.push(toHandle(task))
+			if (task) {
+				handles.push(toHandle(task))
+				continue
+			}
+			const settled = this.settledHandles.get(taskId)
+			if (settled) handles.push(settled)
 		}
 		return handles
 	}
@@ -116,6 +216,20 @@ export class LocalTaskGateway implements TaskGateway {
 	}
 }
 
+/**
+ * Did this child fail?
+ *
+ * Two answers have to agree. `state` is `'failed'` only when the spawn
+ * machinery itself threw; a child whose agent RAN and returned
+ * `status: 'failed'` lands in `markCompleted` regardless, carrying the
+ * failure in its result rather than its state. Reading only the state
+ * would therefore miss the ordinary case — an agent that tried and could
+ * not — and catch only the exceptional one.
+ */
+function hasFailed(handle: TaskHandle): boolean {
+	return handle.state === 'failed' || handle.result?.status === 'failed'
+}
+
 function toHandle(task: import('../types/agent/task.js').AgentTask): TaskHandle {
 	return {
 		taskId: task.taskId,

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

@@ -0,0 +1,104 @@
+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)
+	})
+})