@namzu/sdk 54.0.0 → 55.0.0

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(