@namzu/sdk 48.3.1 → 50.0.0

package/src/manager/agent/lifecycle.ts

@@ -18,6 +18,7 @@ import {
 	type SessionLog,
 } from '../../store/session-log/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from '../../types/agent/base.js'
+import type { AgentDefinition } from '../../types/agent/factory.js'
 import type {
 	AgentLifecycleEvent,
 	AgentLifecycleListener,
@@ -134,10 +135,15 @@ interface ChildSpawnRecord {
 	parentSessionId: SessionId
 	/** The parent turn whose tool call spawned the child. */
 	parentTurnId: TurnId
+	/** A follow-up has a new invoking turn; the conversation's origin stays immutable. */
+	originParentTurnId?: TurnId
+	/** Rollback must never delete a conversation that existed before this invocation. */
+	resumed?: boolean
 	rootSessionId: SessionId
 	/** The parent's ancestors and the parent itself, root first: the child's `SessionLocator.ancestors`. */
 	ancestry: readonly SessionId[]
 	childDepth: number
+	childOwnerVersion: number
 	/**
 	 * Where the child's log and meta document were placed, when this manager
 	 * placed them (a layout was known and the child named no storage).
@@ -164,6 +170,19 @@ interface ChildSpawnRecord {
 	resolvedToolDenies?: readonly string[]
 }
 
+/** In-process admission capability, separate from replayable history and terminal task handles. */
+interface RetainedChildConversation {
+	readonly definition: AgentDefinition
+	readonly origin: ChildSpawnRecord
+	readonly topicId: AgentTaskContext['topicId']
+	readonly projectId: AgentTaskContext['projectId']
+	readonly cwd: string
+	readonly log: SessionLog
+	activeSubSessionId?: SubSessionId
+}
+
+const RETAINED_CHILD_CONVERSATION_CAP = 1_000
+
 /**
  * Combine a child's own environment with what its parent passed down.
  *
@@ -282,6 +301,7 @@ export class AgentManager {
 	private registry: AgentRegistry
 	private instances: Map<TaskId, AgentTask> = new Map()
 	private spawnRecords: Map<TaskId, ChildSpawnRecord> = new Map()
+	private readonly childConversations = new Map<SessionId, RetainedChildConversation>()
 	private completionCallbacks: Map<TaskId, Array<() => void>> = new Map()
 	private listeners: AgentLifecycleListener[] = []
 	private log: Logger
@@ -695,6 +715,7 @@ export class AgentManager {
 				state: 'pending',
 				pendingMessages: queuedTask?.pendingMessages ?? [],
 				createdAt: queuedTask?.createdAt ?? Date.now(),
+				childSessionId: spawnRecord.childSessionId,
 				workspace: options.workspace?.mode === 'isolated' ? spawnRecord.workspaceRef : undefined,
 				sessionEventListener: listener,
 			} satisfies AgentTask)
@@ -761,6 +782,11 @@ export class AgentManager {
 			})
 
 			const definition = this.registry.getOrThrow(options.agentId)
+			if (
+				spawnRecord.resumed &&
+				definition !== this.childConversations.get(spawnRecord.childSessionId)?.definition
+			)
+				throw new Error('Child continuation requires its unchanged agent definition')
 			let childConfig: BaseAgentConfig
 			if (definition.configBuilder) {
 				// Call the configBuilder regardless of whether factoryOptions were
@@ -981,6 +1007,9 @@ export class AgentManager {
 				childConfig.sessionLog = childLog
 				spawnRecord.releaseLog = registerChildSessionLog(childLog)
 			}
+			if (!spawnRecord.resumed && childConfig.sessionLog) {
+				this.retainChildConversation(spawnRecord, context, childOptions, childConfig.sessionLog)
+			}
 
 			// Outside the branch, like the scope above it and for the same reason:
 			// a `configBuilder` cannot forward a field it was never told about.
@@ -999,6 +1028,10 @@ export class AgentManager {
 
 			await childBudget.flush()
 			childAbortController.signal.throwIfAborted()
+			if (spawnRecord.resumed && this.registry.getOrThrow(options.agentId) !== definition)
+				throw new Error('Child continuation agent definition changed during admission')
+			if (spawnRecord.resumed) await this.assertContinuationOwnership(spawnRecord, options.agentId)
+			childAbortController.signal.throwIfAborted()
 			this.executingTasks.add(taskId)
 			const runningTask = agentTask
 			this.runChild(runningTask, childOptions, childConfig, listener)
@@ -1021,9 +1054,13 @@ export class AgentManager {
 					// invocation has only NOW stopped; release the persisted edge here.
 					if (!this.instances.has(taskId) || isTerminalAgentTaskState(runningTask.state)) {
 						await this.failSubSession(spawnRecord)
-					} else this.markFailed(taskId, toErrorMessage(failure))
+					} else {
+						this.releaseChildConversation(spawnRecord)
+						this.markFailed(taskId, toErrorMessage(failure))
+					}
 				})
 				.finally(() => {
+					this.releaseChildConversation(spawnRecord)
 					this.executingTasks.delete(taskId)
 					if (!this.instances.has(taskId)) this.dropSpawnRecord(taskId)
 					this.pumpAdmissions(options.parentSessionId)
@@ -1106,6 +1143,33 @@ export class AgentManager {
 
 	private async rollbackSpawnResources(spawnRecord: ChildSpawnRecord): Promise<void> {
 		spawnRecord.releaseLog?.()
+		if (spawnRecord.resumed) {
+			try {
+				await this.deps.sessionStore.deleteSubSession(
+					spawnRecord.subSessionId,
+					spawnRecord.tenantId,
+				)
+				const session = await this.deps.sessionStore.getSession(
+					spawnRecord.childSessionId,
+					spawnRecord.tenantId,
+				)
+				if (
+					session &&
+					session.status === 'active' &&
+					session.ownerVersion === spawnRecord.childOwnerVersion
+				) {
+					await this.deps.sessionStore.updateSession(
+						{ ...session, status: 'idle' },
+						spawnRecord.tenantId,
+						spawnRecord.childOwnerVersion,
+					)
+				}
+			} finally {
+				this.releaseChildConversation(spawnRecord)
+			}
+			return
+		}
+		this.childConversations.delete(spawnRecord.childSessionId)
 		// A child that never started leaves no meta document naming it: the
 		// session it describes is being deleted below.
 		if (spawnRecord.placement) {
@@ -1116,7 +1180,10 @@ export class AgentManager {
 				}),
 			)
 		}
-		await this.disposeChildWorkspace({ ...spawnRecord, workspaceRetention: undefined })
+		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.
@@ -1153,7 +1220,7 @@ export class AgentManager {
 			kind: 'child-session',
 			sessionId: spawnRecord.childSessionId,
 			parentSessionId: spawnRecord.parentSessionId,
-			parentTurnId: spawnRecord.parentTurnId,
+			parentTurnId: spawnRecord.originParentTurnId ?? spawnRecord.parentTurnId,
 			rootSessionId: spawnRecord.rootSessionId,
 			depth: spawnRecord.childDepth,
 			toolCallId: placement.toolCallId,
@@ -1186,6 +1253,17 @@ export class AgentManager {
 		options: SendMessageOptions,
 		taskId: TaskId,
 	): Promise<SessionLog | undefined> {
+		if (spawnRecord.resumed) {
+			const conversation = this.childConversations.get(spawnRecord.childSessionId)
+			if (!conversation) throw new Error('Child conversation continuation authority is unavailable')
+			if (childConfig.sessionLog && childConfig.sessionLog !== conversation.log)
+				throw new Error('Child continuation cannot replace its conversation log')
+			if (conversation.origin.placement) {
+				childConfig.paths = conversation.origin.placement.paths
+				spawnRecord.placement = conversation.origin.placement
+			}
+			return conversation.log
+		}
 		if (childConfig.sessionLog !== undefined) return undefined
 		const inherited = context.childStorage
 		if (inherited?.kind === 'memory' && childConfig.paths === undefined) {
@@ -1407,6 +1485,7 @@ export class AgentManager {
 			this.cancel(taskId)
 		}
 		this.instances.clear()
+		this.childConversations.clear()
 		for (const taskId of this.spawnRecords.keys())
 			if (!this.executingTasks.has(taskId)) this.dropSpawnRecord(taskId)
 		this.listeners.length = 0
@@ -1527,6 +1606,7 @@ export class AgentManager {
 		await this.validateSpawn(options, context)
 		context.parentAbortController.signal.throwIfAborted()
 		const store = this.deps.sessionStore
+		if (options.resumeSessionId) return this.provisionContinuation(options, context)
 
 		// Ancestry walk gives both the child depth and the root session id
 		// attached to every sub-session event from here down.
@@ -1671,6 +1751,7 @@ export class AgentManager {
 			rootSessionId,
 			ancestry: parentAncestry,
 			childDepth,
+			childOwnerVersion: childSession.ownerVersion,
 			workspaceRef,
 			...(options.workspace?.mode === 'isolated' && options.workspace.retention === 'retain'
 				? { workspaceRetention: 'retain' as const }
@@ -1678,6 +1759,146 @@ export class AgentManager {
 		}
 	}
 
+	private retainChildConversation(
+		origin: ChildSpawnRecord,
+		context: AgentTaskContext,
+		options: SendMessageOptions,
+		log: SessionLog,
+	): void {
+		// Existing builders may supply an application-managed log addressed to
+		// another session. Preserve that first invocation, but never turn its
+		// history into authority for this admitted child's conversation.
+		if (log.sessionId !== origin.childSessionId) return
+		// Conversation authority is bounded independently of the heavy task
+		// eviction. Losing a retained entry makes continuation unavailable; it
+		// never reconstructs execution authority from a history file.
+		if (this.childConversations.size >= RETAINED_CHILD_CONVERSATION_CAP) {
+			const oldest = [...this.childConversations].find(([, value]) => !value.activeSubSessionId)
+			if (oldest) this.childConversations.delete(oldest[0])
+			else return
+		}
+		this.childConversations.set(origin.childSessionId, {
+			definition: this.registry.getOrThrow(options.agentId),
+			origin,
+			topicId: context.topicId,
+			projectId: context.projectId,
+			cwd: resolve(options.input.workingDirectory ?? process.cwd()),
+			log,
+			activeSubSessionId: origin.subSessionId,
+		})
+	}
+
+	private releaseChildConversation(record: ChildSpawnRecord): void {
+		const conversation = this.childConversations.get(record.childSessionId)
+		if (conversation?.activeSubSessionId !== record.subSessionId) return
+		conversation.activeSubSessionId = undefined
+		// An old task's eviction must not unregister the next invocation's log.
+		record.releaseLog?.()
+		record.releaseLog = undefined
+	}
+
+	/** Called under the same parent provisioning lock as ordinary admission. */
+	private async provisionContinuation(
+		options: SendMessageOptions,
+		context: AgentTaskContext,
+	): Promise<ChildSpawnRecord> {
+		const id = options.resumeSessionId
+		const conversation = id ? this.childConversations.get(id) : undefined
+		if (!id || !conversation)
+			throw new Error('Child conversation continuation authority is unavailable')
+		const origin = conversation.origin
+		if (
+			origin.parentSessionId !== options.parentSessionId ||
+			options.parentSessionId !== context.sessionId ||
+			origin.tenantId !== context.tenantId ||
+			conversation.projectId !== context.projectId ||
+			options.projectId !== context.projectId ||
+			conversation.topicId !== context.topicId
+		)
+			throw new Error('Child continuation scope does not match its owning parent')
+		if (conversation.definition !== this.registry.getOrThrow(options.agentId))
+			throw new Error('Child continuation requires its unchanged agent definition')
+		if (conversation.activeSubSessionId)
+			throw new Error('Child conversation is still running or settling')
+		if (origin.workspaceRef || options.workspace?.mode === 'isolated' || options.workspaceBackend)
+			throw new Error(
+				'Child continuation requires a shared workspace; isolated leases cannot be resumed',
+			)
+		if (resolve(options.input.workingDirectory ?? process.cwd()) !== conversation.cwd)
+			throw new Error('Child continuation cannot change its working directory')
+		const store = this.deps.sessionStore
+		if (store.supportsInvocationSummaries !== true || store.supportsOwnerVersionCas !== true)
+			throw new Error('Session store does not support child conversation continuation')
+		const child = await store.getSession(id, context.tenantId)
+		if (
+			!child ||
+			child.status === 'archived' ||
+			child.status === 'locked' ||
+			child.ownerVersion !== origin.childOwnerVersion ||
+			child.projectId !== context.projectId ||
+			child.topicId !== context.topicId ||
+			child.currentActor?.kind !== 'agent' ||
+			child.currentActor.agentId !== options.agentId
+		)
+			throw new Error('Child conversation ownership is no longer valid')
+		const edges = await store.getChildren(options.parentSessionId, context.tenantId)
+		if (!edges.some((edge) => edge.id === origin.subSessionId && edge.childSessionId === id))
+			throw new Error('Child conversation origin is no longer attached to this parent')
+		const edge = await store.createSubSession(
+			{
+				parentSessionId: options.parentSessionId,
+				childSessionId: id,
+				kind: 'agent_spawn',
+				spawnedBy: context.parentActor,
+				failureMode: 'delegate',
+				completionMode: 'summary_ref',
+			},
+			context.tenantId,
+		)
+		try {
+			context.parentAbortController.signal.throwIfAborted()
+			await store.updateSession(
+				{ ...child, status: 'active' },
+				context.tenantId,
+				origin.childOwnerVersion,
+			)
+		} catch (error) {
+			await store.deleteSubSession(edge.id, context.tenantId)
+			throw error
+		}
+		conversation.activeSubSessionId = edge.id
+		return {
+			subSessionId: edge.id,
+			childSessionId: id,
+			tenantId: context.tenantId,
+			parentSessionId: origin.parentSessionId,
+			parentTurnId: context.parentTurnId,
+			originParentTurnId: origin.parentTurnId,
+			rootSessionId: origin.rootSessionId,
+			ancestry: origin.ancestry,
+			childDepth: origin.childDepth,
+			childOwnerVersion: origin.childOwnerVersion,
+			...(origin.placement ? { placement: origin.placement } : {}),
+			resumed: true,
+		}
+	}
+
+	private async assertContinuationOwnership(
+		record: ChildSpawnRecord,
+		agentId: string,
+	): Promise<void> {
+		const child = await this.deps.sessionStore.getSession(record.childSessionId, record.tenantId)
+		if (
+			!child ||
+			child.ownerVersion !== record.childOwnerVersion ||
+			child.status === 'archived' ||
+			child.status === 'locked' ||
+			child.currentActor?.kind !== 'agent' ||
+			child.currentActor.agentId !== agentId
+		)
+			throw new Error('Child conversation ownership changed during admission')
+	}
+
 	private async runChild(
 		agentTask: AgentTask,
 		options: SendMessageOptions,
@@ -1753,6 +1974,8 @@ export class AgentManager {
 					const agentSummary = deriveAgentSummary(result)
 					const summary = await this.deps.summaryMaterializer.materialize({
 						sessionId: spawnRecord.childSessionId,
+						...(spawnRecord.resumed ? { expectedOwnerVersion: spawnRecord.childOwnerVersion } : {}),
+						...(spawnRecord.resumed ? { turnId: result.turnId } : {}),
 						tenantId: spawnRecord.tenantId,
 						finalOutcome: outcome,
 						agentSummary,
@@ -1805,10 +2028,14 @@ export class AgentManager {
 					'namzu.task.id': agentTask.taskId,
 					'exception.message': toErrorMessage(err),
 				})
+				// A follow-up must never advertise its original conversation's
+				// stale summary as the completion of this new invocation.
+				if (spawnRecord.resumed) throw err
 			}
 		}
 
 		if (spawnRecord) await this.settleChildSession(agentTask, spawnRecord, result.status)
+		if (spawnRecord) this.releaseChildConversation(spawnRecord)
 
 		this.markCompleted(agentTask.taskId, result)
 	}

package/src/manager/plan/lifecycle.ts

@@ -34,28 +34,30 @@ export type PlanApprovalHandler = (request: PlanApprovalRequest) => Promise<Plan
  * (`iteration/phases/context.ts` calls `approve` and `startExecution`),
  * translates its events onto the session event stream (`EventTranslator.wirePlanManager`),
  * and settles it on failure (`runtime/query/result.ts` calls `failPlan`). It
- * never reports a step outcome and never settles a plan that succeeded.
+ * does not infer step outcomes from a turn's final text. The coordinator can
+ * report explicitly bound delegated steps; hosts can also report outcomes.
  *
  * That is a split, not an omission — `drainQuery` hands the manager to the host
  * through `onContextCreated({ planManager })` BEFORE the iteration loop starts,
  * precisely so a host can drive the half the kernel does not. So a grep for
- * callers of `updateStepStatus` or `completePlan` inside this package finds
- * none, and that is not evidence the methods are dead: the callers are hosts,
- * and they are outside the repository. `PlanManager` is exported from
+ * callers of `updateStepStatus` or `completePlan` must account for both the
+ * coordinator and application hosts. `PlanManager` is exported from
  * `public-runtime.ts` for this reason.
  *
  * Recorded here because the absence has already been read once as a dead layer
  * and proposed for deletion. What it would have deleted is a working
  * human-in-the-loop approval gate.
  *
- * The one genuine gap in the split is tracked separately: nothing settles a
- * plan that SUCCEEDED, so its status can reach `failed` or stay `executing`
- * but never `completed`. Fixing that needs a decision about what a
- * kernel-built plan's steps mean, not a guessed status — see `completePlan`.
+ * `completePlan` requires reported outcomes for every step. A plan without
+ * those outcomes stays executing until its owner reports them or abandons it;
+ * an ended turn is not evidence that its steps succeeded.
  */
 export class PlanManager {
 	private currentPlan: Plan | null = null
-	private readonly scope: { readonly sessionId: SessionId; readonly turnId: TurnId }
+	private readonly scope: {
+		readonly sessionId: SessionId
+		readonly turnId: TurnId
+	}
 	private listeners: PlanEventListener[] = []
 	private approvalHandler?: PlanApprovalHandler
 

package/src/manager/session/attribution.ts

@@ -22,7 +22,7 @@ export interface SessionLogAttribution {
 export async function assertSessionLogAttribution(
 	log: SessionLog,
 	scope: SessionLogAttribution,
-	options: { readonly requireStarted?: boolean } = {},
+	options: { readonly requireStarted?: boolean; readonly execution?: 'kernel' } = {},
 ): Promise<boolean> {
 	const requiredFields = ['sessionId', 'projectId', 'tenantId', 'topicId'] as const
 	const missingFields = requiredFields.filter(
@@ -69,7 +69,17 @@ export async function assertSessionLogAttribution(
 	if (opened.topicId === undefined || opened.topicId !== scope.topicId) {
 		fields.push('topicId')
 	}
-	if (fields.length === 0) return true
+	if (fields.length === 0) {
+		if (options.execution === 'kernel' && opened.harness !== undefined) {
+			throw new NamzuError({
+				code: 'invalid_config',
+				message:
+					'This session is bound to an external execution engine. Continue it through its harness adapter or start a new Namzu session.',
+				details: { fields: ['harness'] },
+			})
+		}
+		return true
+	}
 
 	throw new NamzuError({
 		code: 'invalid_config',

package/src/manager/session/streamed-message-identity.ts

@@ -0,0 +1,21 @@
+import type { MessageId } from '../../types/ids/index.js'
+import type { AssistantMessage, Message } from '../../types/message/index.js'
+
+// Only the runtime that minted a stream's identity associates a freshly built
+// assistant object here. Caller-authored BaseMessage.id is never an authority.
+const identities = new WeakMap<Message, MessageId>()
+
+export function withStreamedMessageIdentity(
+	message: AssistantMessage,
+	messageId: MessageId,
+): AssistantMessage {
+	identities.set(message, messageId)
+	return message
+}
+
+/** Consume the trusted stream identity once, when this object is first recorded. */
+export function takeStreamedMessageIdentity(message: Message): MessageId | undefined {
+	const identity = identities.get(message)
+	identities.delete(message)
+	return identity
+}

package/src/manager/session/turn-recorder.ts

@@ -54,6 +54,7 @@ import {
 import { asCheckpointId, generateAuditEventId, generateMessageId } from '../../utils/id.js'
 import { childSessionEnded } from '../agent/child-session.js'
 import { assertSessionLogAttribution } from './attribution.js'
+import { takeStreamedMessageIdentity } from './streamed-message-identity.js'
 
 /** Which provider and model a cost is priced against. */
 export interface PricingSubject {
@@ -609,7 +610,7 @@ export class TurnRecorder {
 			}
 			// Claiming a log may repair a torn tail. Refuse a foreign owner
 			// before that mutation, then recheck under the lease below.
-			await assertSessionLogAttribution(this.log, this.#config)
+			await assertSessionLogAttribution(this.log, this.#config, { execution: 'kernel' })
 			if (!options.lease) {
 				const lease = await this.log.claim({
 					holder: this.#leaseHolder,
@@ -657,7 +658,7 @@ export class TurnRecorder {
 					...(options.session.forkedFrom ? { forkedFrom: options.session.forkedFrom } : {}),
 				})
 			} else {
-				await assertSessionLogAttribution(this.log, this.#config)
+				await assertSessionLogAttribution(this.log, this.#config, { execution: 'kernel' })
 			}
 			if (options.session.forkedFrom) {
 				this.#turn.forkedFrom = options.session.forkedFrom
@@ -1057,7 +1058,7 @@ export class TurnRecorder {
 	#idFor(message: Message): MessageId {
 		let id = this.#ids.get(message)
 		if (!id) {
-			id = generateMessageId()
+			id = takeStreamedMessageIdentity(message) ?? generateMessageId()
 			this.#ids.set(message, id)
 		}
 		this.#recorded.set(message, id)