@namzu/sdk 46.0.0 → 48.1.0

package/src/manager/agent/lifecycle.ts

@@ -1,4 +1,5 @@
-import { rm } from 'node:fs/promises'
+import { realpath, rm, stat } from 'node:fs/promises'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
 import { AGENT_MANAGER_DEFAULTS } from '../../constants/agent/index.js'
 import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
 import { GENAI } from '../../constants/telemetry/index.js'
@@ -9,6 +10,7 @@ import {
 } from '../../session/handoff/capacity.js'
 import type { SessionLocator, SessionPaths } from '../../session/paths.js'
 import type { SessionSummaryMaterializer } from '../../session/summary/materialize.js'
+import type { WorkspaceBackendDriver } from '../../session/workspace/driver.js'
 import type { WorkspaceBackendRegistry } from '../../session/workspace/registry.js'
 import {
 	DiskSessionLog,
@@ -151,6 +153,7 @@ interface ChildSpawnRecord {
 	/** Removes the child's log from the process-local lookup. */
 	releaseLog?: () => void
 	workspaceRef?: WorkspaceRef
+	workspaceRetention?: 'retain'
 	/**
 	 * What this child was actually granted, after the ancestor union.
 	 *
@@ -180,6 +183,81 @@ function mergeEnv(
 	return { ...base, ...override }
 }
 
+/** A requested isolated child must never resolve to its caller's directory. */
+async function requireIsolatedWorktreePath(
+	ref: WorkspaceRef | undefined,
+	callerCwd?: string,
+	subdirectory?: string,
+): Promise<string> {
+	const meta = ref?.meta
+	if (
+		typeof ref?.id !== 'string' ||
+		ref.id.length === 0 ||
+		meta?.backend !== 'git-worktree' ||
+		typeof meta.repoRoot !== 'string' ||
+		!isAbsolute(meta.repoRoot) ||
+		typeof meta.branch !== 'string' ||
+		meta.branch.length === 0 ||
+		typeof meta.worktreePath !== 'string' ||
+		!isAbsolute(meta.worktreePath) ||
+		resolve(meta.worktreePath) === resolve(callerCwd ?? process.cwd())
+	) {
+		throw new Error('Isolated git-worktree driver returned an invalid workspace ref or path')
+	}
+	// A custom driver can return a different absolute spelling of the same
+	// directory (for example, a symlink to the caller). Both paths must exist
+	// before the child is admitted, and their physical roots must differ.
+	let physicalPaths: [string, string]
+	try {
+		physicalPaths = await Promise.all([
+			realpath(meta.worktreePath),
+			realpath(resolve(callerCwd ?? process.cwd())),
+		])
+		if (!(await stat(physicalPaths[0])).isDirectory()) {
+			throw new Error('The worktree path is not a directory')
+		}
+	} catch (cause) {
+		throw new Error('Isolated git-worktree driver returned an invalid workspace ref or path', {
+			cause,
+		})
+	}
+	if (physicalPaths[0] === physicalPaths[1]) {
+		throw new Error('Isolated git-worktree driver returned an invalid workspace ref or path')
+	}
+	if (subdirectory === undefined) return meta.worktreePath
+	if (typeof subdirectory !== 'string' || subdirectory.length === 0 || isAbsolute(subdirectory)) {
+		throw new Error('Isolated workspace subdirectory must be a nonempty relative path')
+	}
+	const lexicalChild = resolve(meta.worktreePath, subdirectory)
+	const lexicalRelative = relative(resolve(meta.worktreePath), lexicalChild)
+	if (
+		isAbsolute(lexicalRelative) ||
+		lexicalRelative === '..' ||
+		lexicalRelative.startsWith(`..${sep}`)
+	) {
+		throw new Error('Isolated workspace subdirectory escapes the worktree')
+	}
+	let physicalChild: string
+	try {
+		physicalChild = await realpath(lexicalChild)
+		if (!(await stat(physicalChild)).isDirectory()) {
+			throw new Error('The selected worktree path is not a directory')
+		}
+	} catch (cause) {
+		throw new Error('Isolated workspace subdirectory is missing or not a directory', { cause })
+	}
+	const physicalRelative = relative(physicalPaths[0], physicalChild)
+	if (
+		physicalRelative === '' ||
+		isAbsolute(physicalRelative) ||
+		physicalRelative === '..' ||
+		physicalRelative.startsWith(`..${sep}`)
+	) {
+		throw new Error('Isolated workspace subdirectory resolves outside its worktree')
+	}
+	return physicalChild
+}
+
 /**
  * One `reviewAllowedCalls` that answers `true` when any of `sources` does.
  *
@@ -283,7 +361,9 @@ export class AgentManager {
 			if (task.context === context || context.parentAbortController.signal.aborted)
 				this.cancel(task.taskId, 'parent')
 		}
-		task.childAbortController.signal.addEventListener('abort', onAbort, { once: true })
+		task.childAbortController.signal.addEventListener('abort', onAbort, {
+			once: true,
+		})
 		const entry: PendingSpawn = {
 			ready: false,
 			task,
@@ -522,9 +602,25 @@ export class AgentManager {
 			await childBudget.flush()
 			throw error
 		}
+		let childOptions: SendMessageOptions = options
 		let childAbortController: AbortController | undefined
 		let agentTask: AgentTask | undefined
 		try {
+			// Explicit isolation is the child's execution root, not a side
+			// resource. Keep validation in this rollback envelope too.
+			if (options.workspace?.mode === 'isolated') {
+				childOptions = {
+					...options,
+					input: {
+						...options.input,
+						workingDirectory: await requireIsolatedWorktreePath(
+							spawnRecord.workspaceRef,
+							options.input.workingDirectory,
+							options.workspace.subdirectory,
+						),
+					},
+				}
+			}
 			childAbortController =
 				queuedTask?.childAbortController ??
 				createChildAbortController(context.parentAbortController)
@@ -599,6 +695,7 @@ export class AgentManager {
 				state: 'pending',
 				pendingMessages: queuedTask?.pendingMessages ?? [],
 				createdAt: queuedTask?.createdAt ?? Date.now(),
+				workspace: options.workspace?.mode === 'isolated' ? spawnRecord.workspaceRef : undefined,
 				sessionEventListener: listener,
 			} satisfies AgentTask)
 
@@ -676,6 +773,7 @@ export class AgentManager {
 						...(context.factoryOptions ?? {}),
 						tokenBudget: allocatedTokens,
 						timeoutMs: options.budgetAllocation?.timeoutMs ?? this.config.childTimeoutMs,
+						workingDirectory: childOptions.input.workingDirectory,
 						sessionId: spawnRecord.childSessionId,
 						parentSessionId: spawnRecord.parentSessionId,
 						parentTurnId: spawnRecord.parentTurnId,
@@ -872,11 +970,11 @@ export class AgentManager {
 				spawnRecord,
 				childConfig,
 				context,
-				options,
+				childOptions,
 				taskId,
 			)
 			if (childLog) {
-				await this.startChildSessionLog(childLog, spawnRecord, context, options, taskId, {
+				await this.startChildSessionLog(childLog, spawnRecord, context, childOptions, taskId, {
 					id: agent.metadata.id,
 					name: agent.metadata.name,
 				})
@@ -903,7 +1001,7 @@ export class AgentManager {
 			childAbortController.signal.throwIfAborted()
 			this.executingTasks.add(taskId)
 			const runningTask = agentTask
-			this.runChild(runningTask, options, childConfig, listener)
+			this.runChild(runningTask, childOptions, childConfig, listener)
 				.catch(async (err) => {
 					// A thrown invocation supplied no final usage receipt. Keep its
 					// reservation, including when its task handle was canceled or evicted.
@@ -999,6 +1097,9 @@ export class AgentManager {
 			this.scheduleEviction(agentTask.taskId)
 		} else this.instances.delete(agentTask.taskId)
 		this.dropSpawnRecord(agentTask.taskId)
+		// Admission never completed. The checkout is rollback-owned, not a
+		// retained result that a terminal handle may advertise.
+		agentTask.workspace = undefined
 		this.resolveCompletionCallbacks(agentTask.taskId)
 		await this.rollbackSpawnResources(spawnRecord)
 	}
@@ -1015,7 +1116,7 @@ export class AgentManager {
 				}),
 			)
 		}
-		await this.disposeChildWorkspace(spawnRecord)
+		await this.disposeChildWorkspace({ ...spawnRecord, workspaceRetention: undefined })
 		try {
 			// The edge must be removed before its child: stores reject deletion
 			// of a session that still has a subsession reference.
@@ -1135,7 +1236,10 @@ export class AgentManager {
 		taskId: TaskId,
 		agent: { readonly id: string; readonly name: string },
 	): Promise<void> {
-		const lease = await log.claim({ holder: `namzu:agent-manager:${taskId}`, ttlMs: 30_000 })
+		const lease = await log.claim({
+			holder: `namzu:agent-manager:${taskId}`,
+			ttlMs: 30_000,
+		})
 		if (lease === null) {
 			throw new Error(`Child session ${spawnRecord.childSessionId} is already leased`)
 		}
@@ -1459,6 +1563,7 @@ export class AgentManager {
 		// parent but counted against `maxDelegationWidth`.
 		let subSession: Awaited<ReturnType<typeof store.createSubSession>> | undefined
 		let workspaceRef: WorkspaceRef | undefined
+		let workspaceDriver: WorkspaceBackendDriver | undefined
 		try {
 			// Flip to 'active' so the materializer's atomic write + status flip
 			// lands on terminal — §5.3: pending→active→idle.
@@ -1483,10 +1588,30 @@ export class AgentManager {
 			// 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 request = options.workspace
+			const backend =
+				request?.mode === 'shared'
+					? undefined
+					: request?.mode === 'isolated'
+						? request.backend
+						: (options.workspaceBackend ??
+							(this.config.workspaceDefault === 'shared' ? undefined : 'git-worktree'))
+			if (request?.mode === 'isolated' && !this.deps.workspaceRegistry.has(request.backend)) {
+				throw new Error(`Isolated workspace backend ${request.backend} is unavailable`)
+			}
+			if (backend && this.deps.workspaceRegistry.has(backend)) {
 				const driver = this.deps.workspaceRegistry.get(backend)
-				workspaceRef = await driver.create({ label: subSession.id })
+				workspaceDriver = driver
+				workspaceRef = await driver.create({
+					label: subSession.id,
+					...(request?.mode === 'isolated' && request.baseRef ? { baseRef: request.baseRef } : {}),
+				})
+				if (request?.mode === 'isolated')
+					await requireIsolatedWorktreePath(
+						workspaceRef,
+						options.input.workingDirectory,
+						request.subdirectory,
+					)
 
 				// Write the workspace onto the record that outlives this process.
 				//
@@ -1503,16 +1628,23 @@ export class AgentManager {
 				// exist before the record it is named after. Inside the try, so
 				// the compensating rollback below covers it like every other
 				// mutation here.
-				subSession = { ...subSession, workspaceId: workspaceRef.id }
+				subSession = {
+					...subSession,
+					workspaceId: workspaceRef.id,
+					...(request?.mode === 'isolated' && request.retention === 'retain'
+						? { workspaceRetention: 'retain' as const }
+						: {}),
+				}
 				await store.updateSubSession(subSession, context.tenantId)
 			}
 		} catch (err) {
-			if (workspaceRef && subSession) {
-				await this.disposeChildWorkspace({
-					workspaceRef,
-					subSessionId: subSession.id,
-				})
-			}
+			if (workspaceRef && workspaceDriver)
+				await workspaceDriver.dispose(workspaceRef).catch((disposeErr) =>
+					this.log.warn('Unstarted workspace dispose failed', {
+						'namzu.sub_session.id': subSession?.id,
+						'exception.message': toErrorMessage(disposeErr),
+					}),
+				)
 			// 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
@@ -1540,6 +1672,9 @@ export class AgentManager {
 			ancestry: parentAncestry,
 			childDepth,
 			workspaceRef,
+			...(options.workspace?.mode === 'isolated' && options.workspace.retention === 'retain'
+				? { workspaceRetention: 'retain' as const }
+				: {}),
 		}
 	}
 
@@ -1555,6 +1690,15 @@ export class AgentManager {
 		const input = {
 			...options.input,
 			signal: agentTask.childAbortController.signal,
+			// The admitted child session is the authority. A caller-supplied input
+			// cannot redirect its turn to another tenant, project, topic or session.
+			managedScope: {
+				kind: 'managed' as const,
+				sessionId: agentTask.context.sessionId,
+				topicId: agentTask.context.topicId,
+				projectId: agentTask.context.projectId,
+				tenantId: agentTask.context.tenantId,
+			},
 		}
 
 		const spawnRecord = this.spawnRecords.get(agentTask.taskId)
@@ -1760,7 +1904,10 @@ export class AgentManager {
 			status: 'failed',
 			usage: agentTask.context.budget.ownUsage,
 			budget: agentTask.context.budget.summary(),
-			cost: { ...ZERO_COST, unpricedTokens: agentTask.context.budget.ownTokens },
+			cost: {
+				...ZERO_COST,
+				unpricedTokens: agentTask.context.budget.ownTokens,
+			},
 			iterations: 0,
 			durationMs: Date.now() - agentTask.createdAt,
 			messages: [],
@@ -1826,8 +1973,9 @@ export class AgentManager {
 	 * removed is an operator's problem and silence is how it stays one.
 	 */
 	private async disposeChildWorkspace(
-		spawnRecord: Pick<ChildSpawnRecord, 'workspaceRef' | 'subSessionId'>,
+		spawnRecord: Pick<ChildSpawnRecord, 'workspaceRef' | 'workspaceRetention' | 'subSessionId'>,
 	): Promise<void> {
+		if (spawnRecord.workspaceRetention === 'retain') return
 		if (!spawnRecord.workspaceRef) return
 		const backend = spawnRecord.workspaceRef.meta.backend
 		if (!this.deps.workspaceRegistry.has(backend)) return

package/src/manager/connector/environment.ts

@@ -1,6 +1,7 @@
 import type { BaseConnector } from '../../connector/BaseConnector.js'
 import type { BaseExecutionContext } from '../../execution/base.js'
 import { ExecutionContextFactory } from '../../execution/factory.js'
+import { RegistryCollisionError } from '../../registry/collision.js'
 import type { ConnectorRegistry } from '../../registry/connector/definitions.js'
 import type { ScopedConnectorRegistry } from '../../registry/connector/scoped.js'
 import type {
@@ -43,6 +44,21 @@ export interface EnvironmentConnectorManagerConfig {
 	log?: Logger
 }
 
+/** Two environments claiming one id. */
+export class EnvironmentCollisionError extends RegistryCollisionError {
+	readonly environmentId: string
+
+	constructor(environmentId: string) {
+		super(
+			'EnvironmentConnectorManager',
+			environmentId,
+			`Environment "${environmentId}" is already registered. Unregister it first via unregisterEnvironment(), or pick a different id.`,
+		)
+		this.name = 'EnvironmentCollisionError'
+		this.environmentId = environmentId
+	}
+}
+
 interface EnvironmentState {
 	descriptor: EnvironmentDescriptor
 	scopeChain: ScopeChain
@@ -71,10 +87,7 @@ export class EnvironmentConnectorManager {
 	registerEnvironment(setup: EnvironmentConnectorSetup): void {
 		const envId = setup.environment.id
 		if (this.environments.has(envId)) {
-			this.log.warn('Environment already registered, skipping', {
-				'namzu.environment.id': envId,
-			})
-			return
+			throw new EnvironmentCollisionError(envId)
 		}
 
 		const manager = new ConnectorManager({ registry: this.connectorRegistry, log: this.log })

package/src/manager/connector/index.ts

@@ -1,10 +1,10 @@
 export { ConnectorManager } from './lifecycle.js'
 export type { ConnectorManagerConfig } from './lifecycle.js'
 
-export { TenantConnectorManager } from './tenant.js'
+export { TenantCollisionError, TenantConnectorManager } from './tenant.js'
 export type { TenantConnectorManagerConfig } from './tenant.js'
 
-export { EnvironmentConnectorManager } from './environment.js'
+export { EnvironmentCollisionError, EnvironmentConnectorManager } from './environment.js'
 export type {
 	EnvironmentConnectorSetup,
 	EnvironmentConnectorManagerConfig,

package/src/manager/connector/tenant.ts

@@ -1,5 +1,6 @@
 import type { BaseConnector } from '../../connector/BaseConnector.js'
 import { NAMZU } from '../../constants/telemetry/index.js'
+import { RegistryCollisionError } from '../../registry/collision.js'
 import type { ConnectorRegistry } from '../../registry/connector/definitions.js'
 import type {
 	AuthConfig,
@@ -47,6 +48,21 @@ export interface TenantConnectorManagerConfig {
 	log?: Logger
 }
 
+/** Two tenants claiming one id. */
+export class TenantCollisionError extends RegistryCollisionError {
+	readonly tenantId: string
+
+	constructor(tenantId: string) {
+		super(
+			'TenantConnectorManager',
+			tenantId,
+			`Tenant "${tenantId}" is already registered. Unregister it first via unregisterTenant(), or pick a different id.`,
+		)
+		this.name = 'TenantCollisionError'
+		this.tenantId = tenantId
+	}
+}
+
 interface TenantState {
 	descriptor: TenantDescriptor
 	manager: ConnectorManager
@@ -73,10 +89,7 @@ export class TenantConnectorManager {
 
 	registerTenant(descriptor: TenantDescriptor, rateLimit?: TenantRateLimitConfig): void {
 		if (this.tenants.has(descriptor.id)) {
-			this.log.warn('Tenant already registered, skipping', {
-				[NAMZU.TENANT_ID]: descriptor.id,
-			})
-			return
+			throw new TenantCollisionError(descriptor.id)
 		}
 
 		const tenantLog = this.log.child({ [NAMZU.TENANT_ID]: descriptor.id })

package/src/manager/index.ts

@@ -3,10 +3,10 @@ export { TurnRecorder } from './session/turn-recorder.js'
 export { ConnectorManager } from './connector/lifecycle.js'
 export type { ConnectorManagerConfig } from './connector/lifecycle.js'
 
-export { TenantConnectorManager } from './connector/tenant.js'
+export { TenantCollisionError, TenantConnectorManager } from './connector/tenant.js'
 export type { TenantConnectorManagerConfig } from './connector/tenant.js'
 
-export { EnvironmentConnectorManager } from './connector/environment.js'
+export { EnvironmentCollisionError, EnvironmentConnectorManager } from './connector/environment.js'
 export type {
 	EnvironmentConnectorSetup,
 	EnvironmentConnectorManagerConfig,

package/src/manager/session/attribution.ts

@@ -0,0 +1,79 @@
+import type { SessionLog } from '../../store/session-log/index.js'
+import { NamzuError } from '../../types/errors/index.js'
+import type { ProjectId, SessionId, TenantId, TopicId } from '../../types/ids/index.js'
+
+/** The complete owner a caller says a session log has. */
+export interface SessionLogAttribution {
+	readonly sessionId: SessionId
+	readonly projectId: ProjectId
+	readonly tenantId: TenantId
+	readonly topicId: TopicId
+}
+
+/**
+ * Refuse a session owned by another scope before reading its history or
+ * checkpoints. Call again while holding its writer lease before a new turn:
+ * an empty log seen before the claim may have been opened by another writer.
+ *
+ * Older logs can omit tenantId/topicId in their schema. They remain readable,
+ * but cannot be continued or forked under a guessed owner.
+ * Returns false for an unopened log when `requireStarted` is not set.
+ */
+export async function assertSessionLogAttribution(
+	log: SessionLog,
+	scope: SessionLogAttribution,
+	options: { readonly requireStarted?: boolean } = {},
+): Promise<boolean> {
+	const requiredFields = ['sessionId', 'projectId', 'tenantId', 'topicId'] as const
+	const missingFields = requiredFields.filter(
+		(field) => typeof scope[field] !== 'string' || scope[field] === '',
+	)
+	if (missingFields.length > 0) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: `A session owner scope requires ${missingFields.join(', ')}.`,
+			details: { fields: missingFields },
+		})
+	}
+	if (log.sessionId !== scope.sessionId) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: `The session log belongs to session ${log.sessionId}, not ${scope.sessionId}.`,
+			details: { fields: ['sessionId'] },
+		})
+	}
+
+	const opened = (await log.readAll({ throughSeq: 1 })).entries[0]?.record
+	if (!opened && !options.requireStarted) return false
+	if (!opened) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: `Session ${scope.sessionId} has no session_started owner record.`,
+			details: { fields: ['sessionId'] },
+		})
+	}
+	if (opened.type !== 'session_started') {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: `Session ${scope.sessionId} has no session_started owner record.`,
+			details: { fields: ['sessionId'] },
+		})
+	}
+
+	const fields: string[] = []
+	if (opened.sessionId !== scope.sessionId) fields.push('sessionId')
+	if (opened.projectId !== scope.projectId) fields.push('projectId')
+	if (opened.tenantId === undefined || opened.tenantId !== scope.tenantId) {
+		fields.push('tenantId')
+	}
+	if (opened.topicId === undefined || opened.topicId !== scope.topicId) {
+		fields.push('topicId')
+	}
+	if (fields.length === 0) return true
+
+	throw new NamzuError({
+		code: 'invalid_config',
+		message: `Session ${scope.sessionId} is not opened under the supplied ${fields.join(', ')} scope.`,
+		details: { fields },
+	})
+}