@namzu/sdk 62.6.0 → 62.7.0

package/src/runtime/query/checkpoint.ts

@@ -3,6 +3,7 @@ import { type TurnRecorder, readFoldedHistory } from '../../manager/session/turn
 import type { CheckpointScope, SessionCheckpointStore } from '../../store/checkpoint/index.js'
 import type { SessionLog } from '../../store/session-log/index.js'
 import { restoreSpilledRequestInputs } from '../../store/session-log/spilled-input.js'
+import { readOutcomeProgress } from '../../store/session-log/turn-outcome.js'
 import type { SerializedSpanContext } from '../../telemetry/attributes.js'
 import { NamzuError } from '../../types/errors/index.js'
 import type {
@@ -84,7 +85,14 @@ type CheckpointState = Pick<
 	| 'review'
 	| 'latestUserMessageId'
 	| 'workingState'
->
+> & {
+	/**
+	 * What the turn's outcome record had gathered. Not a field of the document:
+	 * it is written as its own `outcome_progress_written` record beside the
+	 * checkpoint, so a release that validates the document strictly reads it.
+	 */
+	readonly outcome?: Readonly<Record<string, unknown>>
+}
 
 /**
  * A checkpoint read back for a resume: the document, the context it
@@ -276,6 +284,11 @@ export class CheckpointManager {
 	private restoredNativeAttempts = 0
 	private toolStructuredAttemptsSource?: () => number
 	private restoredToolAttempts = 0
+	private outcomeSource?: () => Readonly<Record<string, unknown>> | undefined
+	private restoredOutcomeState: { resumed: boolean; snapshot?: Readonly<Record<string, unknown>> } =
+		{
+			resumed: false,
+		}
 	private lastCreatedId?: CheckpointId
 	private traceSource?: () => SerializedSpanContext | undefined
 	private parkTtlMs?: number
@@ -329,6 +342,23 @@ export class CheckpointManager {
 		return this.restoredToolAttempts
 	}
 
+	/** Wire the turn's outcome record in, so every checkpoint carries what it had gathered. */
+	setOutcomeSource(source: () => Readonly<Record<string, unknown>> | undefined): void {
+		this.outcomeSource = source
+	}
+
+	/**
+	 * What a resumed turn's checkpoint kept of the outcome record. `resumed` is
+	 * false for a turn that began here; true with no `snapshot` for one resumed
+	 * from a checkpoint that predates the record.
+	 */
+	get restoredOutcome(): {
+		readonly resumed: boolean
+		readonly snapshot?: Readonly<Record<string, unknown>>
+	} {
+		return this.restoredOutcomeState
+	}
+
 	setStructuredReviewAttemptsSource(source: () => number): void {
 		this.structuredReviewAttemptsSource = source
 	}
@@ -417,6 +447,7 @@ export class CheckpointManager {
 			},
 			...(latestUserMessageId ? { latestUserMessageId } : {}),
 			...withDefined('workingState', this.workingStateSource?.()),
+			...withDefined('outcome', this.outcomeSource?.() ?? this.restoredOutcomeState.snapshot),
 		}
 	}
 
@@ -449,6 +480,19 @@ export class CheckpointManager {
 			turnCreatedAt: this.turnCreatedAt ?? new Date(recorder.getTurn().startedAt).toISOString(),
 			createdAt: new Date().toISOString(),
 		}
+		// What the outcome record had gathered goes in its own record, ahead of the
+		// one that commits the checkpoint, and is read back by the checkpoint's id.
+		// Failing to write it is not failing to checkpoint: a resume without it
+		// reports no outcome, never a false `unchanged`.
+		if (state.outcome !== undefined) {
+			await recorder.appendIgnorableRecord({
+				type: 'outcome_progress_written',
+				turnId: this.scope.turnId,
+				ignorable: true,
+				checkpointId: document.checkpointId,
+				progress: state.outcome,
+			})
+		}
 		const receipt = await this.store.write(this.scope, document)
 		await recorder.appendRecord({
 			type: 'checkpoint_written',
@@ -654,6 +698,14 @@ export class CheckpointManager {
 		this.restoredNativeAttempts = document.review.nativeStructuredAttempts
 		this.restoredToolAttempts = document.review.toolStructuredAttempts ?? 0
 		this.restoredReviewAttempts = document.review.structuredAttempts
+		await this.recorder.flush()
+		const progress = await readOutcomeProgress(this.recorder.log, checkpointId).catch(
+			() => undefined,
+		)
+		this.restoredOutcomeState = {
+			resumed: true,
+			...(progress !== undefined ? { snapshot: progress } : {}),
+		}
 		this.restoredUserMessage = restored.latestUserMessage
 		this.restoredUserMessageId = restored.latestUserMessage
 			? document.latestUserMessageId

package/src/runtime/query/executor.ts

@@ -29,7 +29,11 @@ import { resolveRetainedOutput } from '../../tools/retained-output.js'
 import type { ToolManager } from '../../toolsets/manager.js'
 import type { ToolSourceRef } from '../../toolsets/types.js'
 import type { ToolResultGuardrailSpec } from '../../types/guardrail/index.js'
-import type { ToolCallDeclined, ToolCallEscalation } from '../../types/hitl/index.js'
+import type {
+	LaunchedScript,
+	ToolCallDeclined,
+	ToolCallEscalation,
+} from '../../types/hitl/index.js'
 import type { SessionId, ToolUseId, TurnId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import {
@@ -72,6 +76,12 @@ import { compressShellOutput } from '../../utils/shell-compress.js'
 import { parseStructuredResultJson } from '../../utils/structured-result-json.js'
 import { ensureScratchpadDirectory } from '../../utils/temp.js'
 import { type BackgroundJobRegistry, type JobProcess, bindOwner } from '../jobs/registry.js'
+import {
+	type ScriptEvidence,
+	analyzeLaunches,
+	changedSinceRead,
+	readLaunchedScripts,
+} from './auto-review/script-evidence.js'
 import { type BatchDetach, stillRunningResult } from './detached-calls.js'
 import {
 	type ToolAdmissionHost,
@@ -378,6 +388,8 @@ export interface ToolExecutorConfig {
 	outsideRootAccess?: 'refuse' | 'review'
 	/** See `QueryParams.sandboxEscape`. Default `'refuse'`. */
 	sandboxEscape?: 'refuse' | 'review'
+	/** See `QueryParams.outsideRootRefusal`. */
+	outsideRootRefusal?: string
 	/**
 	 * Read LIVE, not frozen at turn start.
 	 *
@@ -577,6 +589,12 @@ export interface ToolCallOutcome {
 	/** Rich form for the model, when the tool supplied one. */
 	content?: ToolResultContent
 	isError?: boolean
+	/**
+	 * What the call was about and what came of it, as typed fields; the same value
+	 * `tool_completed` carries. Absent when a post-tool hook replaced the output,
+	 * so a reader never takes an exit status from a result the hook rewrote.
+	 */
+	facts?: ToolFacts
 	/** Provider argument admission failure, never inferred from receipt text. */
 	inputFailure?: CompletedToolRecord['inputFailure']
 	/** A pre-tool hook deliberately skipped execution; its receipt is not an output candidate. */
@@ -732,6 +750,9 @@ export class ToolExecutor {
 	private readonly toolCallBudget?: ToolCallBudget
 	private readonly preparedBatches = new WeakSet<PreparedToolBatch>()
 	private readonly preparedBashDirectories = new WeakMap<PreparedSafetyCall, string>()
+	/** Script files a classifier read for a call, by call id, to be checked again when it runs. */
+	private readonly reviewedScripts = new Map<string, ScriptEvidence['watch']>()
+	private readonly startedAt = Date.now()
 	/** Ephemeral proof of actual execution; restored messages do not acquire it. */
 	private readonly recordedObservations = new Map<
 		string,
@@ -982,6 +1003,47 @@ export class ToolExecutor {
 		)
 	}
 
+	/**
+	 * The script files a shell line launches that the agent wrote or that
+	 * appeared during the session, read now for the auto-mode classifier.
+	 * Remembers what was read for `callId`, so the file can be checked again
+	 * just before the call runs.
+	 */
+	async launchedScripts(
+		callId: string,
+		line: string,
+		dialect: ShellDialect,
+	): Promise<readonly LaunchedScript[]> {
+		if (this.sandboxed) {
+			// A sandbox's files are not on this host's disk. Say so rather than
+			// letting a launch inside one look like a launch of nothing.
+			const analysis = analyzeLaunches(line, dialect)
+			const named = analysis.launches.map((l) => l.path)
+			return named.length === 0 && analysis.unresolved.length === 0
+				? []
+				: [
+						{
+							path: named[0] ?? '(launch form not resolved)',
+							origin: 'unknown',
+							state: 'unreadable',
+							note: 'the command runs in a sandbox whose files are not read for this review, so what the script does is not known',
+						},
+					]
+		}
+		const evidence = await readLaunchedScripts(line, dialect, {
+			cwd: effectiveBashWorkingDirectory(this.config.sessionId, this.config.workingDirectory, {
+				sandboxed: false,
+			}),
+			startedAt: this.fileReadTracker.startedAt ?? this.startedAt,
+			...(this.fileReadTracker.authoredFingerprint
+				? { authoredFingerprint: (key: string) => this.fileReadTracker.authoredFingerprint?.(key) }
+				: {}),
+		})
+		if (evidence.watch.length > 0) this.reviewedScripts.set(callId, evidence.watch)
+		else this.reviewedScripts.delete(callId)
+		return evidence.scripts
+	}
+
 	/** The whole of the evidence as one text, from the same ledger. No filesystem I/O. */
 	describeFileEvidence(messages: readonly Message[]): string | undefined {
 		return describeVisibleFileEvidence(
@@ -1207,11 +1269,12 @@ export class ToolExecutor {
 				toolCall,
 				!hostModifiedCallIds?.has(toolCall.id),
 			)
-			const call = await this.refusedBeforeReview(prepared, earlierPaths)
+			const beforeReview = await this.refusedBeforeReview(prepared, earlierPaths)
 			const path = inputPathOf(prepared)
 			if (path !== undefined) earlierPaths.push(path)
+			this.admitScratchpad(beforeReview)
+			const call = await this.refusedOutsideRoot(beforeReview)
 			calls.set(toolCall.id, call)
-			this.admitScratchpad(call)
 			const escalation = await this.escalationOrUnfinished(call)
 			if (escalation) escalations.set(toolCall.id, escalation)
 			if (await this.writesScratchpad(call, escalation)) scratchpadWrites.add(toolCall.id)
@@ -1220,6 +1283,49 @@ export class ToolExecutor {
 		return this.publishPreparedBatch(calls, escalations, scratchpadWrites)
 	}
 
+	/**
+	 * A file tool's path outside the roots, refused with the host's own words
+	 * (`QueryParams.outsideRootRefusal`) instead of the tool's generic one.
+	 *
+	 * It takes the place of the call like any refusal found while preparing it,
+	 * so it holds in every permission mode and reaches no reviewer. Only a turn
+	 * that refuses (`outsideRootAccess: 'refuse'`) and has no sandbox is looked
+	 * at, and only a tool that declares `pathArgument`. The exemptions are the
+	 * review's: the scratch folder is a root, and so is this session's retained
+	 * output for `read`.
+	 */
+	private async refusedOutsideRoot(call: PreparedDirectCall): Promise<PreparedDirectCall> {
+		const note = this.config.outsideRootRefusal
+		if (call.kind !== 'ready' || note === undefined) return call
+		if (this.config.outsideRootAccess !== 'refuse' || this.sandboxed) return call
+		const tool = this.config.tools.get(call.toolName)
+		if (tool?.pathArgument === undefined) return call
+		if (call.input === null || typeof call.input !== 'object') return call
+		const value = (call.input as Record<string, unknown>)[tool.pathArgument]
+		if (typeof value !== 'string') return call
+		try {
+			const retained =
+				tool.name === 'read' && (await resolveRetainedOutput(this.outputDirectory(), value))
+			if (retained) return call
+			const outside = await pathOutsideRoots(this.rootsNow(), value)
+			if (outside === undefined) return call
+			return {
+				kind: 'synthetic',
+				toolCall: call.toolCall,
+				toolName: call.toolName,
+				input: call.input,
+				message: formatFailedToolOutput(
+					undefined,
+					`${outside} is outside the working directory. ${note}`,
+				),
+				isError: true,
+			}
+		} catch {
+			this.config.abortSignal.throwIfAborted()
+			return call
+		}
+	}
+
 	/**
 	 * A ready call the tool already knows cannot run, answered now instead of
 	 * after a reviewer has been asked about it (`ToolDefinition.refuseBeforeReview`).
@@ -1461,12 +1567,13 @@ export class ToolExecutor {
 		const earlierPaths: string[] = []
 		for (const toolCall of response.message.toolCalls ?? []) {
 			if (changedCallIds.has(toolCall.id)) {
-				const call = await this.refusedBeforeReview(
+				const beforeReview = await this.refusedBeforeReview(
 					await prepareDirectCall(this.admissionHost(), toolCall, false),
 					earlierPaths,
 				)
+				this.admitScratchpad(beforeReview)
+				const call = await this.refusedOutsideRoot(beforeReview)
 				calls.set(toolCall.id, call)
-				this.admitScratchpad(call)
 				const escalation = await this.escalationOrUnfinished(call)
 				if (escalation) escalations.set(toolCall.id, escalation)
 				else escalations.delete(toolCall.id)
@@ -1730,13 +1837,25 @@ export class ToolExecutor {
 					let outcome: ToolCallOutcome
 					started.add(toolCall.id)
 					try {
-						outcome = await this.executeSingle(
-							toolCall,
-							ctx,
-							recordObservation,
-							() => progress.close(),
-							preparedCall,
-						)
+						const reviewedScripts = this.reviewedScripts.get(toolCall.id)
+						this.reviewedScripts.delete(toolCall.id)
+						const moved =
+							reviewedScripts === undefined ? undefined : await changedSinceRead(reviewedScripts)
+						outcome =
+							moved !== undefined
+								? {
+										toolCallId: toolCall.id,
+										toolName: toolCall.function.name,
+										output: `Error: ${moved} changed after the safety check read it, so the command was not run. Run it again and it will be checked against the new text.`,
+										isError: true,
+									}
+								: await this.executeSingle(
+										toolCall,
+										ctx,
+										recordObservation,
+										() => progress.close(),
+										preparedCall,
+									)
 					} catch (error) {
 						// A call already answered with the placeholder has no batch
 						// left to fail; its failure is its outcome.
@@ -1932,6 +2051,7 @@ export class ToolExecutor {
 					} catch (error) {
 						failure ??= { error }
 					} finally {
+						this.reviewedScripts.delete(unit.toolCall.id)
 						settledUnit()
 						inFlight.delete(unit)
 						pump()
@@ -2269,7 +2389,7 @@ export class ToolExecutor {
 			toolName: name,
 			toolUseId: nestedId,
 			output: rawOutput,
-			maxChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
+			maxChars: this.toolOutputCap(this.config.tools.get(name), false),
 			retainedPreviewChars: this.config.retainedToolPreviewChars,
 			spillDir: this.outputDirectory(),
 			recoveryRoutes: this.recoveryRoutes(),
@@ -2734,11 +2854,7 @@ export class ToolExecutor {
 				]
 			}
 		}
-		// A tool that bounds its own output is exempt from the DEFAULT per-result
-		// cap only; a host that set the cap explicitly still gets it.
-		const maxToolOutputChars =
-			this.config.maxToolOutputChars ??
-			(executedDefinition?.selfLimitingOutput === true ? 0 : DEFAULT_MAX_TOOL_OUTPUT_CHARS)
+		const maxToolOutputChars = this.toolOutputCap(executedDefinition, true)
 		const sourceOutput = output
 		// This owner-bound channel follows the selected receipt after both result
 		// screening and post-tool replacement. ToolResult.data and raw input can
@@ -2967,6 +3083,7 @@ export class ToolExecutor {
 				? { handoff: result.handoff }
 				: {}),
 			...(revealedTools !== undefined ? { revealedTools } : {}),
+			...(result.facts !== undefined && !postOverride ? { facts: result.facts } : {}),
 		}
 	}
 
@@ -3465,6 +3582,8 @@ export class ToolExecutor {
 		preparedCall?: PreparedDirectCall,
 		declined?: ToolCallDeclined,
 	): Promise<ToolCallOutcome> {
+		// A call that does not run has no use for what a review read of its scripts.
+		this.reviewedScripts.delete(toolCall.id)
 		const toolName = preparedCall?.toolName ?? toolCall.function.name
 		let input: unknown = preparedCall?.input ?? {}
 		if (!preparedCall) {
@@ -3623,6 +3742,7 @@ export class ToolExecutor {
 			toolName,
 			output: outcome.output,
 			isError: outcome.kind === 'error',
+			...(outcome.facts ? { facts: outcome.facts } : {}),
 			...(outcome.inputFailure ? { inputFailure: outcome.inputFailure } : {}),
 			...(outcome.skipped ? { skipped: true as const } : {}),
 		}
@@ -3638,6 +3758,26 @@ export class ToolExecutor {
 		})
 	}
 
+	/**
+	 * The per-result character cap for one tool: the turn's cap, tightened by
+	 * the tool's own `maxOutputChars`. A tool that bounds its own output is
+	 * exempt from the DEFAULT cap only (`exemptSelfLimiting`); a host that set
+	 * the cap explicitly still gets it. 0 means no cap.
+	 */
+	private toolOutputCap(
+		definition: ToolDefinition | undefined,
+		exemptSelfLimiting: boolean,
+	): number {
+		const turn =
+			this.config.maxToolOutputChars ??
+			(exemptSelfLimiting && definition?.selfLimitingOutput === true
+				? 0
+				: DEFAULT_MAX_TOOL_OUTPUT_CHARS)
+		const own = definition?.maxOutputChars
+		if (own === undefined || !Number.isFinite(own) || own <= 0) return turn
+		return turn > 0 ? Math.min(turn, Math.floor(own)) : Math.floor(own)
+	}
+
 	/**
 	 * The host preview and model text may differ; each gets its own text
 	 * budget. Rich bytes are measured separately and withheld whole when
@@ -3674,7 +3814,7 @@ export class ToolExecutor {
 						toolName,
 						toolUseId,
 						output: text,
-						maxChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
+						maxChars: this.toolOutputCap(this.config.tools.get(toolName), false),
 						...(notice ? { notice } : {}),
 						// A tool may return different host and model text. They must
 						// never compete for the same exclusive spill filename.

package/src/runtime/query/finalize-turn.ts

@@ -2,7 +2,7 @@ import type { Span } from '@opentelemetry/api'
 import { consolidationEntry, isConsolidated } from '../../compaction/consolidation.js'
 import type { WorkingStateManager } from '../../compaction/manager.js'
 import { NAMZU } from '../../constants/telemetry/index.js'
-import type { SessionEvent, StepResult } from '../../types/session/index.js'
+import type { SessionEvent, StepResult, TurnOutcome } from '../../types/session/index.js'
 import { toErrorMessage } from '../../utils/error.js'
 import type { TurnContext } from './context.js'
 import type { EventTranslator } from './events.js'
@@ -53,6 +53,12 @@ export interface TurnFinalization {
 	 * immediately before the record is written.
 	 */
 	readonly takeSteps: () => readonly StepResult[]
+	/**
+	 * The turn's outcome record, read here for the same reason as the steps: the
+	 * workspace is compared once, as late as it can be and before the record is
+	 * written. Never throws; `undefined` means no record was kept.
+	 */
+	readonly takeOutcome?: () => Promise<TurnOutcome | undefined>
 	/**
 	 * Whether the loop already fired `turn_end` (and `subagent_stop`) when the
 	 * model finished, so a hook could keep the turn going. Fired there, it is
@@ -108,6 +114,7 @@ export async function* finalizeTurn(
 	// Hand the step record to the turn before it settles, so the
 	// returned `Turn` carries it.
 	ctx.recorder.setSteps(takeSteps())
+	if (finalization.takeOutcome) ctx.recorder.setOutcome(await finalization.takeOutcome())
 
 	// Gates the FINAL result, not the stream — `text_delta` already
 	// reached the host as the model produced it. A rewrite is

package/src/runtime/query/index.ts

@@ -619,6 +619,14 @@ export interface QueryParams {
 	 * is never, because the path is not mounted there to be reached.
 	 */
 	outsideRootAccess?: 'refuse' | 'review'
+	/**
+	 * The sentence a host wants the model to read when `outsideRootAccess` is
+	 * `'refuse'` and a file tool names a path outside the roots, for example
+	 * which setting made the wall and how to move it. Without it the tool's own
+	 * generic refusal stands. The refusal is made before any review, so no
+	 * permission mode (bypass included) lifts it.
+	 */
+	outsideRootRefusal?: string
 	/**
 	 * Whether a call may ask to run outside the turn's sandbox (the shipped
 	 * `bash` tool's `dangerously_disable_sandbox`).
@@ -1599,6 +1607,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 					: {}),
 				...(scratchpadDirectory ? { scratchpadDirectory } : {}),
 				...(params.outsideRootAccess ? { outsideRootAccess: params.outsideRootAccess } : {}),
+				...(params.outsideRootRefusal ? { outsideRootRefusal: params.outsideRootRefusal } : {}),
 				...(params.sandboxEscape ? { sandboxEscape: params.sandboxEscape } : {}),
 				permissionMode: () => ctx.permissionMode.current,
 				env: turnConfig.env ?? {},
@@ -2823,6 +2832,9 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 						}
 					}
 
+					// The parked batch runs here, outside the loop's own steps, so
+					// the outcome record is told about it here.
+					await iterationOrchestrator.outcomeBefore(pendingResume.response)
 					const resumedBatch = await applyPendingResume(
 						pendingResume,
 						ctx.recorder,
@@ -2831,6 +2843,11 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 						pendingResumeAssistantId,
 					)
 					iterationOrchestrator.setResumedToolResults(resumedBatch.results)
+					await iterationOrchestrator.outcomeObserve(
+						ctx.recorder.currentIteration,
+						pendingResume.response,
+						resumedBatch.results,
+					)
 					yield* eventTranslator.drainPending()
 				}
 
@@ -2911,6 +2928,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 					params,
 					eventTranslator,
 					takeSteps: () => iterationOrchestrator.getSteps(),
+					takeOutcome: () => iterationOrchestrator.takeOutcome(),
 					turnEndHooksFired: () => iterationOrchestrator.turnEndHooksFired,
 					workingStateManager,
 					resultAssembler,
@@ -2933,6 +2951,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				if (isTurnInProgressError(err) && !ctx.recorder.isActive) throw err
 				// A failed turn still spent its steps; report them.
 				ctx.recorder.setSteps(iterationOrchestrator.getSteps())
+				ctx.recorder.setOutcome(await iterationOrchestrator.takeOutcome())
 				await executeUserInterruptHooks(err)
 				yield* eventTranslator.drainPending()
 				await executeTurnFailureHooks(err)