@namzu/sdk 51.1.0 → 52.0.0

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

@@ -1,4 +1,7 @@
-import { resolveContextWindow } from '../../../../compaction/context-window.js'
+import {
+	resolveContextWindow,
+	resolveTriggerThreshold,
+} from '../../../../compaction/context-window.js'
 import { findDanglingMessages } from '../../../../compaction/dangling.js'
 import {
 	type CompactionPlan,
@@ -19,6 +22,11 @@ import { invariants } from '../../../../invariants/index.js'
 import { resolveTaskModel } from '../../../../model-router/task-router.js'
 import type { Message } from '../../../../types/message/index.js'
 import { applyLifecycleHookResults } from '../../plugin-hooks.js'
+import {
+	COMPACTION_FAILURE_MESSAGE,
+	COMPACTION_REFILL_MESSAGE,
+	compactionBreaker,
+} from './compaction-breaker.js'
 import type { IterationContext } from './context.js'
 import { isWorkingMemoryMessage } from './working-memory.js'
 
@@ -169,6 +177,7 @@ async function commitToolResultClear(
 	ctx.recorder.clearLastPromptTokens?.()
 	await emitToolResultClear(ctx, plan)
 	await emitContextUsageSnapshot(ctx, estimateTokens(ctx), contextWindowTokens, windowSource)
+	compactionBreaker(ctx)?.recordRelief()
 }
 
 /**
@@ -312,6 +321,7 @@ async function declined(
 	messages: number,
 	error?: string,
 ): Promise<void> {
+	compactionBreaker(ctx)?.recordFailure()
 	await ctx.emitEvent?.({
 		type: 'compaction_failed',
 		turnId: ctx.recorder.turnId,
@@ -322,6 +332,32 @@ async function declined(
 	})
 }
 
+/**
+ * The third refill in a row: stop the turn instead of compacting again.
+ * Returns true when this pass must not run. Only with `circuitBreaker`.
+ */
+async function stopOnRefill(ctx: IterationContext): Promise<boolean> {
+	const breaker = compactionBreaker(ctx)
+	if (!breaker) return false
+	// Already announced: the turn is on its way out; do not say it twice.
+	if (breaker.stop !== undefined) return true
+	if (!breaker.wouldTrip(ctx.recorder.currentIteration)) return false
+	ctx.log.warn('Compaction keeps refilling — stopping the turn', {
+		[NAMZU.TURN_ID]: ctx.recorder.turnId,
+		[NAMZU.ITERATION]: ctx.recorder.currentIteration,
+	})
+	breaker.stopTurn(COMPACTION_REFILL_MESSAGE)
+	await ctx.emitEvent?.({
+		type: 'compaction_failed',
+		turnId: ctx.recorder.turnId,
+		iteration: ctx.recorder.currentIteration,
+		cause: 'refilling',
+		messages: ctx.recorder.messages.length,
+		error: COMPACTION_REFILL_MESSAGE,
+	})
+	return true
+}
+
 /**
  * Ctx for `compaction:no-split-tool-pair`, registered just below: the
  * candidate history a reducer just returned, not yet installed. Passed on
@@ -456,6 +492,7 @@ async function applyReducer(
 		reduction.contextWindowTokens,
 		measurement.windowSource,
 	)
+	compactionBreaker(ctx)?.recordCompaction(ctx.recorder.currentIteration)
 }
 
 /**
@@ -498,9 +535,10 @@ async function recordShed(
 
 /**
  * A pass, once the check decided to run one, is bracketed by the
- * `pre_compact` and `post_compact` hooks. Observational: a hook sees the
- * numbers and cannot stop the pass, because a context the provider will
- * reject is not a thing a hook may insist on.
+ * `pre_compact` and `post_compact` hooks. A hook sees the numbers and may
+ * cancel a pass the threshold asked for (`skip`), and cannot stop one the
+ * provider forced, because a context the provider will reject is not a thing
+ * a hook may insist on.
  */
 interface CompactionPass {
 	attempted: boolean
@@ -573,11 +611,31 @@ async function runCompactionCheckInner(
 	// The salience strategy starts holding the context at `softTarget`,
 	// well before the summary trigger; every other strategy waits for it.
 	const salience = config.strategy === 'salience'
-	const startAt = salience
-		? Math.min(config.softTarget ?? DEFAULT_SOFT_TARGET, config.triggerThreshold)
-		: config.triggerThreshold
+	const maxOutputTokens = ctx.providerCapabilities?.maxOutputTokens
+	const trigger = resolveTriggerThreshold(config.triggerThreshold, budget, maxOutputTokens)
+	const startAt = salience ? Math.min(config.softTarget ?? DEFAULT_SOFT_TARGET, trigger) : trigger
 	if (!options?.force && usage < startAt) return
 
+	// Three failed passes in a row: stop trying for the rest of the turn, and
+	// say so once. A pass the provider forced is never gated.
+	const breaker = compactionBreaker(ctx)
+	if (breaker?.failuresOpen && !options?.force) {
+		if (breaker.takeFailureNotice()) {
+			ctx.log.warn('Compaction failed three times in a row — switched off for this turn', {
+				[NAMZU.TURN_ID]: ctx.recorder.turnId,
+			})
+			await ctx.emitEvent?.({
+				type: 'compaction_failed',
+				turnId: ctx.recorder.turnId,
+				iteration: ctx.recorder.currentIteration,
+				cause: 'breaker_open',
+				messages: ctx.recorder.messages.length,
+				error: COMPACTION_FAILURE_MESSAGE,
+			})
+		}
+		return
+	}
+
 	pass.attempted = true
 	pass.tokensBefore = estimatedTokens
 	pass.contextWindowTokens = budget
@@ -598,6 +656,25 @@ async function runCompactionCheckInner(
 			ctx.emitEvent,
 		)
 		applyLifecycleHookResults('pre_compact', results)
+		const refusal = results.find((result) => result.action === 'skip')
+		if (refusal?.action === 'skip') {
+			// A threshold pass is the context's own housekeeping and a hook may
+			// postpone it. A forced pass runs because the provider rejected the
+			// prompt: a context it will reject is not something a hook may insist
+			// on, so the refusal is reported and the pass runs.
+			if (!options?.force) {
+				pass.attempted = false
+				ctx.log.info('A pre_compact hook cancelled the compaction pass', {
+					[NAMZU.TURN_ID]: ctx.recorder.turnId,
+					'namzu.hook.reason': refusal.reason,
+				})
+				return
+			}
+			ctx.log.warn('A pre_compact hook asked to cancel a compaction the provider forced; it ran', {
+				[NAMZU.TURN_ID]: ctx.recorder.turnId,
+				'namzu.hook.reason': refusal.reason,
+			})
+		}
 	}
 
 	// A reducer, when the turn has one, OWNS reduction — the structured pass
@@ -609,6 +686,7 @@ async function runCompactionCheckInner(
 		ctx.contextReducer ??
 		(config.strategy === 'sliding-window' ? createSlidingWindowReducer() : undefined)
 	if (reducer) {
+		if (!options?.force && (await stopOnRefill(ctx))) return
 		await applyReducer(
 			ctx,
 			reducer,
@@ -635,7 +713,7 @@ async function runCompactionCheckInner(
 		'namzu.runtime.window': budget,
 		'namzu.runtime.window_source': window.source,
 		'namzu.runtime.usage': Math.round(usage * 100),
-		'namzu.runtime.trigger_threshold': config.triggerThreshold,
+		'namzu.runtime.trigger_threshold': trigger,
 		'namzu.runtime.slot_count': manager.slotCount(),
 	})
 
@@ -668,6 +746,7 @@ async function runCompactionCheckInner(
 			messages: ctx.recorder.messages,
 			config,
 			contextWindowTokens: budget,
+			...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
 			estimatedTokens,
 			...(openTasks ? { openTasks } : {}),
 		})
@@ -676,10 +755,7 @@ async function runCompactionCheckInner(
 		}
 		// Under the trigger, the working set was the whole pass: the summary
 		// path is for the trigger, not for the soft target.
-		if (
-			!options?.force &&
-			(estimatedTokens - working.reclaimedTokens) / budget < config.triggerThreshold
-		) {
+		if (!options?.force && (estimatedTokens - working.reclaimedTokens) / budget < trigger) {
 			return
 		}
 	}
@@ -687,6 +763,7 @@ async function runCompactionCheckInner(
 		messages: ctx.recorder.messages,
 		config,
 		contextWindowTokens: budget,
+		...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
 		estimatedTokens,
 		...(options?.force ? { force: true } : {}),
 	})
@@ -712,6 +789,7 @@ async function runCompactionCheckInner(
 		messages,
 		config,
 		contextWindowTokens: budget,
+		...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
 		estimatedTokens,
 		skipToolResultClear: true,
 		...(options?.force ? { force: true } : {}),
@@ -754,6 +832,14 @@ async function runCompactionCheckInner(
 		return
 	}
 
+	if (!options?.force && (await stopOnRefill(ctx))) {
+		// A clear staged for this pass is still a useful edit.
+		if (stagedClear) {
+			await commitToolResultClear(ctx, stagedClear, budget, window.source, pass.reason)
+		}
+		return
+	}
+
 	const { systemMessages, olderMessages, recentMessages, keepStart } = plan
 
 	let compactedContent: string
@@ -910,4 +996,5 @@ async function runCompactionCheckInner(
 		reachedResetThreshold: reachedReset,
 	})
 	await emitContextUsageSnapshot(ctx, newEstimate, budget, window.source)
+	compactionBreaker(ctx)?.recordCompaction(ctx.recorder.currentIteration)
 }

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

@@ -199,6 +199,8 @@ export interface IterationContext {
 	readonly taskRouter?: TaskRouterConfig
 
 	readonly compactionConfig?: CompactionConfig
+	/** See `QueryParams.maxOutputContinuations`. */
+	readonly maxOutputContinuations?: number
 
 	/**
 	 * What the driver said this model's context window is, resolved once.
@@ -225,6 +227,11 @@ export interface IterationContext {
 	 * after tool results and before the next turn.
 	 */
 	readonly inboundMessages?: () => readonly import('../../../../types/message/index.js').Message[]
+	/**
+	 * Hidden reminders for each model request; see `ReminderSource`. Absent:
+	 * the turn gets none, as before.
+	 */
+	readonly reminders?: import('../../reminders.js').ReminderSource
 	/** Known topic-queue arrivals appended after the restored checkpoint history. */
 	readonly resumedInput?: readonly import('../../../../types/message/index.js').Message[]
 	/** Observes pending input without draining it; abort releases the waiter. */
@@ -252,6 +259,10 @@ export interface IterationContext {
 
 	readonly pluginManager?: import('../../../../plugin/lifecycle.js').PluginLifecycleManager
 
+	/** The delegating session, when this turn is a child's: `subagent_stop` names it. */
+	readonly parentSessionId?: import('../../../../types/ids/index.js').SessionId
+	readonly parentTurnId?: import('../../../../types/ids/index.js').TurnId
+
 	/**
 	 * Override for {@link PARK_RECORD_DELAY_MS}. Internal; tests set `0` to
 	 * observe a recorded park without waiting out the real threshold.

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -12,6 +12,7 @@ import {
 	replaceProjectInstructionSnapshot,
 } from '../../project-instructions.js'
 import { attachRepeatNotice } from '../../repeat-call.js'
+import { isReviewExempt } from '../../review-policy.js'
 import { attachNotice, attachSteering, formatJobNote } from '../../steering.js'
 import { type IterationContext, awaitDecisionDurably } from './context.js'
 
@@ -25,11 +26,23 @@ function escalationReason(escalation: ToolCallSummary['escalation']): string {
 		return `this call's program cannot be verified ahead of time (${escalation.unknownProgram})`
 	}
 	if (escalation?.sandboxEscape) return "this call asks to run outside the turn's sandbox"
+	if (escalation?.dangerousRemoval !== undefined) {
+		return `this call removes something catastrophic (${escalation.dangerousRemoval})`
+	}
+	if (escalation?.protectedPaths?.length) {
+		return `this call writes a protected ${escalation.protectedPaths.length === 1 ? 'path' : 'paths'} (${escalation.protectedPaths.join(', ')})`
+	}
 	if (escalation?.outsidePaths?.length)
 		return `this call reaches ${escalation.outsidePaths.length === 1 ? 'a path' : 'paths'} outside the turn's boundary`
 	return "this call reaches past the turn's boundary, which a rule cannot approve on its own"
 }
 
+function hookAskedReason(reason: string | undefined): string {
+	return reason
+		? `a hook asked that a person approve this call: ${reason}`
+		: 'a hook asked that a person approve this call'
+}
+
 export type ToolReviewDecision = 'executed' | 'rejected' | 'stop'
 
 /**
@@ -124,15 +137,27 @@ export async function* runToolReview(
 			const isDestructive = tool?.isDestructive ? tool.isDestructive(tc.input) : false
 			const requiresApproval = tool?.requiresApproval ? tool.requiresApproval(tc.input) : false
 			const escalation = 'escalation' in tc ? tc.escalation : undefined
+			const hookPermission = 'hookPermission' in tc ? tc.hookPermission : undefined
 
 			return {
 				id: tc.id,
 				name: tc.name,
 				input: tc.input,
 				isDestructive,
-				authorization: { decision: 'review' },
+				// A hook that asked for a person is an explicit review: a call the
+				// tool declares read-only, or one a rule would allow, is still put
+				// to one.
+				authorization:
+					hookPermission?.decision === 'ask'
+						? {
+								decision: 'review' as const,
+								reason: hookAskedReason(hookPermission.reason),
+								explicitReview: true as const,
+							}
+						: { decision: 'review' as const },
 				...(requiresApproval ? { requiresApproval: true as const } : {}),
 				...(escalation ? { escalation } : {}),
+				...(hookPermission ? { hookPermission } : {}),
 			}
 		})
 	}
@@ -355,6 +380,24 @@ export async function* runToolReview(
 				reason,
 			})
 		}
+		for (const path of tc.escalation?.protectedPaths ?? []) {
+			await ctx.recorder.recordAudit({
+				what: { action: 'protected_path_write', tool: tc.name, resource: path },
+				outcome: 'refused',
+				reason,
+			})
+		}
+		if (tc.escalation?.dangerousRemoval !== undefined) {
+			await ctx.recorder.recordAudit({
+				what: {
+					action: 'dangerous_removal',
+					tool: tc.name,
+					resource: tc.escalation.dangerousRemoval,
+				},
+				outcome: 'refused',
+				reason,
+			})
+		}
 	}
 
 	// Gate-denied ids survive the whole function: a later human approval
@@ -419,11 +462,21 @@ export async function* runToolReview(
 					reason: `${gr.gateResult.reason}; but the tool itself declares this call always needs a person's approval, which a rule cannot waive`,
 				}
 			}
+			// A hook that asked for a person can only ADD a review, like the two
+			// overrides above: a `deny` stays a denial.
+			const hookAsked = gr.toolCall.hookPermission?.decision === 'ask'
+			if (hookAsked && gr.gateResult.decision === 'allow') {
+				gr.gateResult = {
+					decision: 'review',
+					matchedRule: gr.gateResult.matchedRule,
+					reason: `${gr.gateResult.reason}; but ${hookAskedReason(gr.toolCall.hookPermission?.reason)}`,
+				}
+			}
 			const { toolCall, gateResult } = gr
 			toolCall.authorization = {
 				decision: gateResult.decision,
 				...(gateResult.reason ? { reason: gateResult.reason } : {}),
-				...(gateResult.decision === 'review' && gateResult.matchedRule
+				...(gateResult.decision === 'review' && (gateResult.matchedRule || hookAsked)
 					? { explicitReview: true as const }
 					: {}),
 			}
@@ -498,6 +551,27 @@ export async function* runToolReview(
 		}
 	}
 
+	// A `pre_tool_use` hook's `allow`, marked on the calls it covers on the
+	// same terms as a skill's grant above and honoured by the review policy,
+	// never decided here. A deny, an explicit review (a rule's, or a hook's own
+	// `ask`), a destructive call, a path outside the roots, a sandbox escape and
+	// a tool's own `requiresApproval` all leave the call unmarked, so it is
+	// reviewed as though no hook had spoken.
+	/** Whether a hook's `allow` may stand in for a person on this call. */
+	const hookMayAllow = (tc: ToolCallSummary): boolean =>
+		!gateDenied.has(tc.id) &&
+		tc.authorization?.decision !== 'deny' &&
+		!tc.authorization?.explicitReview &&
+		!tc.isDestructive &&
+		tc.escalation === undefined &&
+		!tc.requiresApproval
+	for (const tc of toolCallSummaries) {
+		if (tc.hookPermission?.decision !== 'allow' || !hookMayAllow(tc)) continue
+		tc.hookGrant = {
+			...(tc.hookPermission.reason ? { reason: tc.hookPermission.reason } : {}),
+		}
+	}
+
 	// Already approved, at a scope the approver chose — and nothing the
 	// operator's policy denied, because `gateDenied` is checked first.
 	// Re-asking about a call somebody has already said yes to is how an
@@ -525,6 +599,76 @@ export async function* runToolReview(
 		return finish('executed')
 	}
 
+	// A person is about to be asked. `permission_request` hooks may answer
+	// first, per call: `skip` refuses it (and always wins), `allow` approves it
+	// on the same terms as a `pre_tool_use` allow. A read the review policy
+	// would not have asked about is not a question and is not offered.
+	if (ctx.pluginManager) {
+		const questions = toolCallSummaries.filter(
+			(tc) =>
+				!gateDenied.has(tc.id) &&
+				tc.authorization?.decision !== 'deny' &&
+				tc.authorization?.decision !== 'allow' &&
+				(tc.authorization?.explicitReview === true ||
+					tc.escalation !== undefined ||
+					tc.requiresApproval === true ||
+					tc.isDestructive ||
+					!isReviewExempt(ctx.tools, tc.name, tc.input)),
+		)
+		for (const tc of questions) {
+			const answers = await ctx.pluginManager.executeHooks(
+				'permission_request',
+				{
+					sessionId: ctx.recorder.sessionId,
+					turnId: ctx.recorder.turnId,
+					toolName: tc.name,
+					toolInput: tc.input,
+					signal: ctx.abortController.signal,
+				},
+				ctx.emitEvent,
+			)
+			// The hooks answered side by side: a refusal from any of them stands,
+			// whatever the others allowed.
+			const refusal = answers.find((answer) => answer.action === 'skip')
+			for (const answer of answers) {
+				if ((answer.action === 'continue' || answer.action === 'skip') && answer.halt) {
+					ctx.toolExecutor.requestHalt?.(answer.halt.reason)
+				}
+			}
+			if (refusal?.action === 'skip') {
+				const reason = `Blocked by a permission_request hook: ${refusal.reason}`
+				gateDenied.set(tc.id, reason)
+				tc.authorization = { decision: 'deny', reason }
+				await ctx.recorder.recordAudit({
+					what: { action: 'tool_call', tool: tc.name },
+					outcome: 'refused',
+					reason,
+				})
+				continue
+			}
+			for (const answer of answers) {
+				if (
+					answer.action === 'continue' &&
+					answer.permission?.decision === 'allow' &&
+					hookMayAllow(tc)
+				) {
+					tc.hookGrant = {
+						...(answer.permission.reason ? { reason: answer.permission.reason } : {}),
+					}
+				}
+			}
+		}
+		if (toolCallSummaries.every((tc) => gateDenied.has(tc.id))) {
+			for (const tc of escalated()) {
+				const reason = gateDenied.get(tc.id)
+				if (reason !== undefined) await recordRefusedEscalation(tc, reason)
+			}
+			yield* settle(gateDenied)
+			yield* ctx.drainPending()
+			return finish('rejected')
+		}
+	}
+
 	const reviewCheckpoint = await ctx.checkpointMgr.create(ctx.recorder, iterationNum)
 
 	await ctx.emitEvent({
@@ -607,6 +751,24 @@ export async function* runToolReview(
 					reason: "the turn's review approved this call",
 				})
 			}
+			for (const path of tc.escalation?.protectedPaths ?? []) {
+				await ctx.recorder.recordAudit({
+					what: { action: 'protected_path_write', tool: tc.name, resource: path },
+					outcome: 'approved',
+					reason: "the turn's review approved this call",
+				})
+			}
+			if (tc.escalation?.dangerousRemoval !== undefined) {
+				await ctx.recorder.recordAudit({
+					what: {
+						action: 'dangerous_removal',
+						tool: tc.name,
+						resource: tc.escalation.dangerousRemoval,
+					},
+					outcome: 'approved',
+					reason: "the turn's review approved this call",
+				})
+			}
 		}
 	}
 
@@ -762,6 +924,19 @@ export async function* runToolReview(
 				}
 			}
 
+			// The same for a call a hook's `allow` approved.
+			if (reviewDecision.action === 'approve_tools' && reviewDecision.hookGranted) {
+				const listed = new Set(reviewDecision.hookGranted)
+				for (const tc of toolCallSummaries) {
+					if (!listed.has(tc.id) || !tc.hookGrant || gateDenied.has(tc.id)) continue
+					await ctx.recorder.recordAudit({
+						what: { action: 'tool_call', tool: tc.name },
+						outcome: 'approved',
+						reason: `pre-approved by a pre_tool_use hook${tc.hookGrant.reason ? ` (${tc.hookGrant.reason})` : ''}; nobody was asked`,
+					})
+				}
+			}
+
 			await ctx.emitEvent({
 				type: 'tool_review_completed',
 				turnId: ctx.recorder.turnId,