@namzu/sdk 54.0.0 → 55.1.0

package/src/runtime/query/checkpoint.ts

@@ -19,11 +19,12 @@ import {
 	type UserMessage,
 	createRuntimeContextMessage,
 } from '../../types/message/index.js'
+import { escapeNoticeFrame } from '../../types/message/notice-frame.js'
 import { CHECKPOINT_DOCUMENT_VERSION, type Checkpoint } from '../../types/session/checkpoint.js'
 import type { CheckpointListEntry } from '../../types/session/fork.js'
 import type { SessionRecord } from '../../types/session/records.js'
 import { asGoalId, generateCheckpointId } from '../../utils/id.js'
-import { formatSteeringNote, readSteeringNote } from './steering.js'
+import { readSteeringNote } from './steering.js'
 
 /** Keep intent text/provenance without copying attachment payloads into a second slot. */
 function snapshotUserIntent(value: unknown): UserMessage {
@@ -460,8 +461,8 @@ export class CheckpointManager {
 
 	/**
 	 * The id of the record that carries a message's text: its own record,
-	 * or — for operator guidance delivered attached to a tool result — the
-	 * record of the tool result that carries it.
+	 * or, for the operator's message sent while a tool ran, the record of the
+	 * framed message that carries it.
 	 */
 	private messageIdOf(recorder: TurnRecorder, message: Message): MessageId | undefined {
 		if (message === this.restoredUserMessage) return this.restoredUserMessageId
@@ -483,14 +484,17 @@ export class CheckpointManager {
 		) {
 			return undefined
 		}
-		const note = formatSteeringNote(message.content)
+		// The operator's words were sent as a framed message of their own whose
+		// marker is random, so it is found by what its frame holds.
+		const wanted = escapeNoticeFrame(message.content)
 		const messages = recorder.messages
 		for (let i = messages.length - 1; i >= 0; i--) {
 			const candidate = messages[i] as Message
 			if (
-				candidate.role === 'tool' &&
+				candidate.role === 'user' &&
 				typeof candidate.content === 'string' &&
-				candidate.content.endsWith(note)
+				(candidate as UserMessage).source?.type === 'runtime-context' &&
+				readSteeringNote(candidate.content) === wanted
 			) {
 				const id = recorder.recordedIdOf(candidate)
 				if (id) this.steeringCarriers.set(message, id)
@@ -578,6 +582,42 @@ export class CheckpointManager {
 		return park
 	}
 
+	/**
+	 * End the parks that were the other questions of a batch whose decision has
+	 * just been applied (the per-call review parks one question per call).
+	 *
+	 * The batch is answered now, so a question about one of its calls is moot;
+	 * left open, an approval queue would keep serving it and a host resuming it
+	 * would rewind the turn to a batch that has long since been carried out.
+	 * Recorded as superseded, not as an answer: nobody gave one.
+	 */
+	async supersedeBatchParks(
+		callIds: ReadonlySet<string>,
+		except: CheckpointId,
+		superseding: HITLResumeDecision,
+	): Promise<number> {
+		await this.recorder.flush()
+		const parks = await readParks(this.recorder.log, {
+			turnId: this.scope.turnId,
+		})
+		let ended = 0
+		for (const park of parks) {
+			const request = park.pending.request
+			if (
+				park.checkpointId === except ||
+				park.pending.resolvedAt !== undefined ||
+				request.type !== 'tool_review' ||
+				request.perCall !== true ||
+				!request.toolCalls.every((call) => callIds.has(call.id))
+			) {
+				continue
+			}
+			await this.unpark(park.checkpointId, superseding)
+			ended += 1
+		}
+		return ended
+	}
+
 	private async openPark(checkpointId: CheckpointId): Promise<RecordedPark | null> {
 		await this.recorder.flush()
 		const parks = await readParks(this.recorder.log, { turnId: this.scope.turnId })
@@ -693,9 +733,10 @@ export async function restoreCheckpointContext(
 			`Checkpoint latestUserMessage names message ${intentId}, which its session log does not hold`,
 		)
 	}
-	// Guidance delivered attached to a tool result: the intent is the note.
+	// Guidance the operator sent while a tool ran: the intent is the note, whether
+	// it is a message of its own or, in an older session, the end of a tool result.
 	const guidance =
-		intent?.role === 'tool' && typeof intent.content === 'string'
+		(intent?.role === 'tool' || intent?.role === 'user') && typeof intent.content === 'string'
 			? readSteeringNote(intent.content)
 			: undefined
 	const operatorIntent =

package/src/runtime/query/executor.ts

@@ -567,6 +567,43 @@ export interface ToolCallOutcome {
 	revealedTools?: readonly ToolRevealReceipt[]
 }
 
+/** What the per-call review decided about one call that reached the front of the walk. */
+export type CallAdmission =
+	| { readonly run: true }
+	| {
+			readonly run: false
+			readonly reason: string
+			readonly declined?: ToolCallDeclined
+	  }
+
+/**
+ * The per-call review, as the executor sees it: a batch executed while its
+ * calls are still being asked about.
+ *
+ * The executor walks the calls in the model's order. A call that is safe to run
+ * beside others starts as soon as every call already in flight is also safe;
+ * any other call starts only when nothing is in flight, so it never overlaps an
+ * earlier call, and nothing after it starts before it does. Starting a call
+ * means asking `admit` and, on a yes, running it right away.
+ */
+export interface ReviewedExecution {
+	admit(call: ToolCall, index: number): Promise<CallAdmission>
+	/**
+	 * Aborts when a refusal ends the turn. Calls that are running are cancelled
+	 * through it, and a call that has not started is refused without `admit`
+	 * being consulted for a yes.
+	 */
+	readonly ended: AbortSignal
+}
+
+interface ReviewUnit {
+	readonly index: number
+	readonly toolCall: ToolCall
+	readonly preparedCall?: PreparedDirectCall
+	readonly safe: boolean
+	readonly run: () => Promise<void>
+}
+
 export interface ToolExecutionBatch {
 	messages: Message[]
 	results: ToolCallOutcome[]
@@ -1268,6 +1305,7 @@ export class ToolExecutor {
 		prior?: PriorToolResults,
 		preparedBatch?: PreparedToolBatch,
 		declines?: ToolCallDeclines,
+		review?: ReviewedExecution,
 	): Promise<ToolExecutionBatch> {
 		const toolCalls = response.message.toolCalls
 		if (!toolCalls) {
@@ -1294,9 +1332,9 @@ export class ToolExecutor {
 			if (refusal) {
 				const refused = new Map(denials)
 				for (const call of toolCalls) if (!refused.has(call.id)) refused.set(call.id, refusal)
-				return await this.runBatch(toolCalls, refused, prior, owned, declines)
+				return await this.runBatch(toolCalls, refused, prior, owned, declines, review)
 			}
-			return await this.runBatch(toolCalls, denials, prior, owned, declines)
+			return await this.runBatch(toolCalls, denials, prior, owned, declines, review)
 		} finally {
 			// Cleared so a later single execution outside a batch resolves
 			// live rather than inheriting the last batch's sample.
@@ -1310,6 +1348,7 @@ export class ToolExecutor {
 		prior?: PriorToolResults,
 		preparedBatch?: OwnedPreparedToolBatch,
 		declines?: ToolCallDeclines,
+		review?: ReviewedExecution,
 	): Promise<ToolExecutionBatch> {
 		this.log.debug('Executing tool batch', {
 			[NAMZU.TURN_ID]: this.config.turnId,
@@ -1370,6 +1409,9 @@ export class ToolExecutor {
 		// gate keeps that at a working-set size while preserving completion
 		// order independence.
 		const gate = new Semaphore(this.config.maxToolConcurrency ?? DEFAULT_TOOL_CONCURRENCY)
+		// Under a per-call review the calls to run are collected here and walked
+		// afterwards; refusals that were settled before the review need no walk.
+		const reviewUnits: ReviewUnit[] = []
 		toolCalls.forEach((toolCall, i) => {
 			const preparedCall = preparedBatch?.calls.get(toolCall.id)
 			const tool = this.config.tools.get(preparedCall?.toolName ?? toolCall.function.name)
@@ -1391,7 +1433,7 @@ export class ToolExecutor {
 						? { structuredResultJson: recovered.structuredResultJson }
 						: {}),
 				}
-				if (isBarrier) schedule(async () => {}, true, true)
+				if (isBarrier && !review) schedule(async () => {}, true, true)
 				return
 			}
 
@@ -1400,18 +1442,16 @@ export class ToolExecutor {
 				// Denied calls never touch the tool; they still get a result
 				// message so the assistant turn stays fully answered. They can
 				// overlap other calls within a segment, respecting its barriers.
-				schedule(
-					async () => {
-						results[i] = await this.recordDenial(
-							toolCall,
-							denialReason,
-							preparedCall,
-							declines?.get(toolCall.id),
-						)
-					},
-					true,
-					isBarrier,
-				)
+				const recordDenied = async () => {
+					results[i] = await this.recordDenial(
+						toolCall,
+						denialReason,
+						preparedCall,
+						declines?.get(toolCall.id),
+					)
+				}
+				if (review) parallel.push(recordDenied())
+				else schedule(recordDenied, true, isBarrier)
 				return
 			}
 			// Per-call, because the event has to name which call it is about:
@@ -1436,6 +1476,13 @@ export class ToolExecutor {
 				...(escalation?.outsidePaths ? { approvedPaths: escalation.outsidePaths } : {}),
 				...(escalation?.sandboxEscape ? { sandboxEscapeApproved: true } : {}),
 				source: { kind: 'direct' },
+				// A refusal that ends the turn cancels what is running, through the
+				// same signal a tool already honours for a cancelled turn.
+				...(review
+					? {
+							abortSignal: AbortSignal.any([baseContext.abortSignal, review.ended]),
+						}
+					: {}),
 				// Overridden per call, so a nested dispatch can name the call
 				// that made it. The base context has no `toolUseId`, and a
 				// closure built there would report every nested call as
@@ -1477,8 +1524,19 @@ export class ToolExecutor {
 				// non-JSON args → treat as unsafe (serialize), the conservative path
 			}
 			const safe = tool?.isConcurrencySafe?.(input) === true
+			if (review) {
+				reviewUnits.push({
+					index: i,
+					toolCall,
+					...(preparedCall ? { preparedCall } : {}),
+					safe: safe && !isBarrier,
+					run: safe ? gated : run,
+				})
+				return
+			}
 			schedule(safe ? gated : run, safe, isBarrier)
 		})
+		if (review) await this.walkReviewed(reviewUnits, results, review)
 		await Promise.all([...parallel, serial])
 
 		// Whatever failed above left a hole in `results`; fill every one, so
@@ -1518,6 +1576,98 @@ export class ToolExecutor {
 		return { messages, results, observations }
 	}
 
+	/**
+	 * Walk the calls of a batch in the model's order, asking about each as it
+	 * reaches the front and running it right after a yes.
+	 *
+	 * A call may start when nothing is in flight, or when it and every call in
+	 * flight are safe to run side by side. The walk stops at the first call that
+	 * may not start yet, so an unsafe call is never overtaken by one that came
+	 * after it. Once a refusal has ended the turn, nothing waits: every call that
+	 * has not started is refused at once and the ones in flight are cancelled.
+	 */
+	private async walkReviewed(
+		units: readonly ReviewUnit[],
+		results: ToolCallOutcome[],
+		review: ReviewedExecution,
+	): Promise<void> {
+		const inFlight = new Set<ReviewUnit>()
+		let cursor = 0
+		let failure: { readonly error: unknown } | undefined
+		// Once the turn has ended, a refusal is written only after every call
+		// before it has settled, so the transcript lists the calls in the order the
+		// model wrote them: the declined call before the ones refused unasked.
+		const settledUnits = new Map<number, Promise<void>>()
+		const refusedAfterEnd =
+			'An earlier call in this batch was refused and the turn was stopped, so this call was not run.'
+		await new Promise<void>((resolve) => {
+			const start = (unit: ReviewUnit): void => {
+				inFlight.add(unit)
+				let settledUnit!: () => void
+				settledUnits.set(
+					unit.index,
+					new Promise<void>((done) => {
+						settledUnit = done
+					}),
+				)
+				void (async () => {
+					try {
+						let admission: CallAdmission
+						try {
+							admission = await review.admit(unit.toolCall, unit.index)
+						} catch {
+							// An answer that could not be obtained is not a yes.
+							admission = {
+								run: false,
+								reason: 'The approval for this call could not be completed, so it was not run.',
+							}
+						}
+						if (admission.run && !review.ended.aborted) {
+							await unit.run()
+						} else {
+							const refusal = admission.run
+								? { reason: refusedAfterEnd }
+								: { reason: admission.reason, declined: admission.declined }
+							if (review.ended.aborted) {
+								await Promise.all(
+									[...settledUnits].filter(([index]) => index < unit.index).map(([, done]) => done),
+								)
+							}
+							results[unit.index] = await this.recordDenial(
+								unit.toolCall,
+								refusal.reason,
+								unit.preparedCall,
+								'declined' in refusal ? refusal.declined : undefined,
+							)
+						}
+					} catch (error) {
+						failure ??= { error }
+					} finally {
+						settledUnit()
+						inFlight.delete(unit)
+						pump()
+					}
+				})()
+			}
+			const pump = (): void => {
+				while (cursor < units.length) {
+					const unit = units[cursor] as ReviewUnit
+					if (!review.ended.aborted) {
+						const mayStart =
+							inFlight.size === 0 || (unit.safe && [...inFlight].every((other) => other.safe))
+						if (!mayStart) break
+					}
+					cursor++
+					start(unit)
+				}
+				if (cursor >= units.length && inFlight.size === 0) resolve()
+			}
+			review.ended.addEventListener('abort', pump, { once: true })
+			pump()
+		})
+		if (failure) throw failure.error
+	}
+
 	/**
 	 * Hold the batch's combined result text under the per-message cap.
 	 *

package/src/runtime/query/index.ts

@@ -786,6 +786,15 @@ export interface QueryParams {
 	 * See {@link ReminderSource}.
 	 */
 	reminders?: import('./reminders.js').ReminderSource
+	/**
+	 * Whether the kernel tells the model, once, that the approval policy
+	 * changed ("Approval policy changed from X to Y ..."), as request-only
+	 * context after the history. Default `true`. A host that already tells the
+	 * model about a mode change itself (through `reminders`) sets `false` so
+	 * the model hears it once; the `approval_policy_changed` event is
+	 * recorded either way.
+	 */
+	announceApprovalPolicyChange?: boolean
 
 	/**
 	 * Wake a background-task hold when operator input is available, without draining it.
@@ -840,6 +849,16 @@ export interface QueryParams {
 	 */
 	reviewAllowedCalls?: () => boolean
 
+	/**
+	 * Ask about one call at a time while the batch runs, instead of reviewing the
+	 * whole batch as a unit. Opt-in; absent, nothing about review changes. See
+	 * {@link import('../../types/hitl/index.js').PerCallReviewConfig}.
+	 *
+	 * Only this turn is affected: a delegated child reviews its own batches as
+	 * it did before.
+	 */
+	perCallReview?: import('../../types/hitl/index.js').PerCallReviewConfig
+
 	/**
 	 * A name for the policy `resumeHandler` implements.
 	 *
@@ -1770,7 +1789,11 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			// Read through the box on every call, so a swap lands on the next
 			// question rather than the next turn.
 			resumeHandler: (request, context) => approvalPolicy.current.handler(request, context),
-			takeApprovalPolicyChange: () => approvalPolicy.takeUnannouncedChange(),
+			takeApprovalPolicyChange: () => {
+				// Taken either way, so the change is not left pending for a later turn.
+				const change = approvalPolicy.takeUnannouncedChange()
+				return params.announceApprovalPolicyChange === false ? undefined : change
+			},
 			promptContributions,
 			...(params.steering ? { steering: params.steering } : {}),
 			...(jobNotices ? { jobNotices } : {}),
@@ -1788,6 +1811,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			toolGrants: new ToolGrantSet(),
 			skillGrants,
 			...(params.reviewAllowedCalls ? { reviewAllowedCalls: params.reviewAllowedCalls } : {}),
+			...(params.perCallReview ? { perCallReview: params.perCallReview } : {}),
 			// Turn-scoped for the same reason. A repeat count carried into a later
 			// run is a claim about work nobody repeated, and a module-level map
 			// would leak exactly that way.
@@ -2690,6 +2714,26 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 							})
 							return null
 						})
+					// A decision about one call of a batch answered the batch: the
+					// batch's other open questions are moot.
+					if (pendingResume?.partial && params.pendingDecision) {
+						const batchIds = new Set(
+							pendingResume.response.message.toolCalls?.map((call) => call.id) ?? [],
+						)
+						await checkpointMgr
+							.supersedeBatchParks(
+								batchIds,
+								resolvedCheckpointId,
+								supersededByRecovery(params.pendingDecision),
+							)
+							.catch((err: unknown) => {
+								ctx.log.error('Applied a pending decision but failed to clear its sibling parks', {
+									[NAMZU.TURN_ID]: ctx.turnId,
+									'exception.message': err instanceof Error ? err.message : String(err),
+								})
+								return 0
+							})
+					}
 				}
 
 				yield* iterationOrchestrator.runLoop()

package/src/runtime/query/iteration/index.ts

@@ -102,6 +102,7 @@ import {
 	streamWithProviderRejectedImageRecovery,
 } from './provider-rejected-image.js'
 import { type MediaRemoval, RequestRepair } from './request-repair.js'
+import { placeBeforeLatestOperatorMessage } from './step-context.js'
 import {
 	type StepShaping,
 	appendWorkContext,
@@ -853,8 +854,8 @@ export class IterationOrchestrator {
 					// there is no length check here — a second guard for the same
 					// case is one more thing to keep in agreement with the first.
 					const stepSkills = step.skills ? renderSkillsSection([...step.skills]) : null
-					// A supervision change rides the same ephemeral slot, and for
-					// the same reason: it applies to what happens next, not to the
+					// A supervision change is request-only context, and for the
+					// same reason: it applies to what happens next, not to the
 					// run's history. The model plans around how closely it is being
 					// watched — a turn that silently stops asking a human leaves it
 					// batching destructive calls it expects to be reviewed, and one
@@ -879,7 +880,7 @@ export class IterationOrchestrator {
 
 					// Request-only context: observations that need no system
 					// authority and change from request to request. They ride
-					// runtime-context messages of kind `step-context` after the
+					// runtime-context messages of kind `step-context`, most of them after the
 					// history, which every driver keeps there and a caching driver
 					// ends its breakpoint before — so a changed pin or a new turn
 					// snapshot costs its own tokens, not a re-read of the history.
@@ -887,15 +888,27 @@ export class IterationOrchestrator {
 					// (compaction preserves it there) and leaves the request's
 					// system run here.
 					const workingMemory = splitWorkingMemoryForRequest(baseMessages)
-					const stepPreamble = [step.system, stepSkills, policyNotice, ...turnSections]
+					const stepPreamble = [step.system, stepSkills, ...turnSections]
 						.filter(Boolean)
 						.join('\n\n')
 					const requestHistory = stepPreamble
 						? [...workingMemory.history, createSystemMessage(stepPreamble)]
 						: [...workingMemory.history]
 					if (workingMemory.context) requestHistory.push(workingMemory.context)
-					if (contextText) requestHistory.push(stepContextMessage(contextText))
-					if (step.context) requestHistory.push(stepContextMessage(step.context))
+					// The blocks of data that belong to this turn (recalled memory and
+					// evidence, the context contributions) sit just before the
+					// operator's latest message, so the request is the last thing the
+					// model reads. The short reminders and notices stay after it.
+					placeBeforeLatestOperatorMessage(
+						requestHistory,
+						[contextText, step.context]
+							.filter((text): text is string => Boolean(text))
+							.map(stepContextMessage),
+					)
+					// After the history, never ahead of it: a system message in front
+					// of the conversation moves the prefix every cached request shares,
+					// and a mode change would re-key the whole conversation.
+					if (policyNotice) requestHistory.push(stepContextMessage(policyNotice))
 					const messages = projectRequestRichContent(
 						this.projectObservations(requestHistory),
 						this.ctx.turnConfig.maxRequestRichContentBytes ??

package/src/runtime/query/iteration/phases/context.ts

@@ -201,6 +201,8 @@ export interface IterationContext {
 	readonly skillGrants?: SkillGrantSet
 	/** See `QueryParams.reviewAllowedCalls`. Absent: allowed and granted batches skip review. */
 	readonly reviewAllowedCalls?: () => boolean
+	/** See `QueryParams.perCallReview`. Absent: a batch is reviewed as a unit. */
+	readonly perCallReview?: import('../../../../types/hitl/index.js').PerCallReviewConfig
 	/**
 	 * Absent when the host opted out with `repeatCallAdvisory: false`. The
 	 * opt-out is the ABSENCE, not a flag read at every call site, so a code
@@ -316,9 +318,10 @@ export async function awaitDecisionDurably(
 	ctx: IterationContext,
 	checkpoint: { readonly id: CheckpointId },
 	request: Parameters<ResumeHandler>[0],
+	scope?: AskScope,
 ): Promise<HITLResumeDecision> {
 	const delay = ctx.parkRecordDelayMs ?? PARK_RECORD_DELAY_MS
-	const decisionPromise = awaitDecisionOrAbort(ctx, request)
+	const decisionPromise = awaitDecisionOrAbort(ctx, request, scope)
 
 	let settled = false
 	let recorded = false
@@ -423,9 +426,26 @@ export async function awaitDecisionDurably(
  * turns into `setStopReason('cancelled') + markCancelled + stop`. Fails closed:
  * a resume-handler rejection also resolves to `abort` rather than hanging.
  */
+/**
+ * One question among several that are open at once (the per-call review).
+ *
+ * `signal` closes just this question; when it aborts and the turn itself was not
+ * cancelled, `closedAs` says what the question's answer is, so the park is
+ * recorded as what really ended it rather than as a cancelled turn.
+ */
+export interface AskScope {
+	readonly signal: AbortSignal
+	readonly closedAs: () => HITLResumeDecision
+}
+
 /** What a resume handler may read besides the request; see {@link ResumeContext}. */
-function resumeContextOf(ctx: IterationContext): ResumeContext {
-	const signal = ctx.abortController?.signal
+function resumeContextOf(ctx: IterationContext, scope?: AskScope): ResumeContext {
+	const turnSignal = ctx.abortController?.signal
+	const signal = scope
+		? turnSignal
+			? AbortSignal.any([turnSignal, scope.signal])
+			: scope.signal
+		: turnSignal
 	return {
 		transcript: () => ctx.recorder.messages,
 		...(signal ? { signal } : {}),
@@ -435,24 +455,30 @@ function resumeContextOf(ctx: IterationContext): ResumeContext {
 export async function awaitDecisionOrAbort(
 	ctx: IterationContext,
 	request: Parameters<ResumeHandler>[0],
+	scope?: AskScope,
 ): Promise<HITLResumeDecision> {
-	const signal = ctx.abortController?.signal
+	const turnSignal = ctx.abortController?.signal
+	const signal = scope
+		? turnSignal
+			? AbortSignal.any([turnSignal, scope.signal])
+			: scope.signal
+		: turnSignal
 	// No abort signal wired (e.g. a minimal test harness) → behave exactly as a
 	// direct resumeHandler await, no race. In production TurnContextFactory always
 	// provides the controller, so the race below is live.
-	const resumeContext = resumeContextOf(ctx)
+	const resumeContext = resumeContextOf(ctx, scope)
 	if (!signal) return ctx.resumeHandler(request, resumeContext)
-	const abortDecision: HITLResumeDecision = {
-		action: 'abort',
-		reason: 'run aborted while parked for HITL',
-	}
-	if (signal.aborted) return abortDecision
+	const abortedDecision = (): HITLResumeDecision =>
+		scope && !turnSignal?.aborted
+			? scope.closedAs()
+			: { action: 'abort', reason: 'run aborted while parked for HITL' }
+	if (signal.aborted) return abortedDecision()
 	return new Promise<HITLResumeDecision>((resolve) => {
 		let settled = false
 		const onAbort = (): void => {
 			if (settled) return
 			settled = true
-			resolve(abortDecision)
+			resolve(abortedDecision())
 		}
 		signal.addEventListener('abort', onAbort, { once: true })
 		Promise.resolve(ctx.resumeHandler(request, resumeContext)).then(