@namzu/sdk 43.0.0 → 44.0.0

package/src/runtime/query/file-evidence-seed.ts

@@ -51,7 +51,7 @@ export interface ObservationSeedContext {
 	readonly workingDirectory: string
 	/** See `ToolContext.additionalDirectories`; part of the tools' resolution. */
 	readonly additionalDirectories?: readonly string[]
-	/** True when this run's tools address a sandbox, whose keys are paths as written. */
+	/** True when this turn's tools address a sandbox, whose keys are paths as written. */
 	readonly sandboxed?: boolean
 }
 
@@ -97,7 +97,7 @@ export async function seedObservationLedger(
  * pass should not run at all.
  *
  * `undefined` for a history with nothing to reconstruct and for one past the
- * ceiling. A path the resolver refuses — it escapes the roots this run may
+ * ceiling. A path the resolver refuses — it escapes the roots this turn may
  * reach, or the working directory itself is gone — is simply left unkeyed;
  * the replay then treats the mutation that named it as unattributable, which
  * is the fail-closed answer and the same one it gives a call it cannot parse.

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

@@ -0,0 +1,209 @@
+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 { toErrorMessage } from '../../utils/error.js'
+import type { TurnContext } from './context.js'
+import type { EventTranslator } from './events.js'
+import { runOutputGuardrails } from './guardrails.js'
+import type { QueryParams } from './index.js'
+import { applyLifecycleHookResults } from './plugin-hooks.js'
+import type { ResultAssembler } from './result.js'
+
+/**
+ * What a turn does on its way out, once the loop has stopped.
+ *
+ * The loop returns for any of a dozen reasons — an answer, a budget, a stop
+ * condition, a cancelled signal — and this is the one place all of them pass
+ * through: the `run_end`/`subagent_stop` hooks, the step record, the output
+ * guardrails, consolidation into a memory store, and the terminal events.
+ *
+ * It is a generator because it emits, and it is reached with `yield*` so
+ * every one of those emits suspends the caller at exactly the point it did
+ * when the code lived inline.
+ *
+ * Two positions here are load-bearing, and they are stated where they happen.
+ * `markCancelled` runs before the assembler, because `completeTurn` marks a
+ * `running` turn `completed` — the reverse order would overwrite the
+ * cancellation the abort signal had already declared. And
+ * `memory_consolidated` precedes `turn_completed`, so a host folding the
+ * stream in order has the memory before the turn that produced it.
+ *
+ * `setSteps` keeps its position too, but on the move's terms rather than on
+ * its own. This file used to claim the assembler needed it first "or the
+ * returned `Turn` loses the final turn's steps" — that is not true, and a
+ * mutation proves it: `completeTurn` reads `result`, `stopReason` and the
+ * budget and never `steps`, the returned `Turn` is built by `finalize()`
+ * (which runs after the whole `try`/`catch`/`finally`), and moving
+ * `setSteps` below the assembler leaves the suite green, including the test
+ * that asserts `turn.steps` on a returned turn. What holds `setSteps` where it
+ * is, is the byte-identity of this move: every position was preserved, not
+ * just the consequential ones. Its read is still deferred to the same
+ * moment — after the `run_end` hooks, immediately before the record is
+ * written — which is why the caller passes `takeSteps` rather than an array.
+ */
+export interface TurnFinalization {
+	readonly ctx: TurnContext
+	readonly params: QueryParams
+	readonly eventTranslator: EventTranslator
+	/**
+	 * The steps the loop recorded, read HERE rather than handed over as an
+	 * array: it is read where it always was, after the `run_end` hooks and
+	 * immediately before the record is written.
+	 */
+	readonly takeSteps: () => readonly StepResult[]
+	readonly workingStateManager: WorkingStateManager | undefined
+	readonly resultAssembler: ResultAssembler
+	readonly rootSpan: Span
+}
+
+export async function* finalizeTurn(
+	finalization: TurnFinalization,
+): AsyncGenerator<SessionEvent, void> {
+	const {
+		ctx,
+		params,
+		eventTranslator,
+		takeSteps,
+		workingStateManager,
+		resultAssembler,
+		rootSpan,
+	} = finalization
+
+	if (params.pluginManager) {
+		const hookResults = await params.pluginManager.executeHooks(
+			'turn_end',
+			{ sessionId: ctx.sessionId, turnId: ctx.turnId, signal: ctx.abortController.signal },
+			eventTranslator.emitEvent,
+		)
+		applyLifecycleHookResults('turn_end', hookResults)
+		yield* eventTranslator.drainPending()
+		// A delegated session says so once more, by name, so a hook that
+		// only cares when a subagent finishes need not read parent ids
+		// off every run_end.
+		if (params.parentSessionId !== undefined) {
+			const stopResults = await params.pluginManager.executeHooks(
+				'subagent_stop',
+				{
+					sessionId: ctx.sessionId,
+					turnId: ctx.turnId,
+					parentSessionId: params.parentSessionId,
+					...(params.parentTurnId !== undefined ? { parentTurnId: params.parentTurnId } : {}),
+					signal: ctx.abortController.signal,
+				},
+				eventTranslator.emitEvent,
+			)
+			applyLifecycleHookResults('subagent_stop', stopResults)
+			yield* eventTranslator.drainPending()
+		}
+	}
+
+	// Hand the step record to the turn before it settles, so the
+	// returned `Turn` carries it.
+	ctx.recorder.setSteps(takeSteps())
+
+	// Gates the FINAL result, not the stream — `text_delta` already
+	// reached the host as the model produced it. A rewrite is
+	// therefore a correction, and the event says so; buffering every
+	// token to gate the stream itself would trade the streaming UX
+	// for the guarantee, which is the host's call, not the SDK's.
+	if (params.outputGuardrails && params.outputGuardrails.length > 0) {
+		// Read what the turn produced WITHOUT settling it. This used to
+		// call `markCompleted()` just to materialize the text, which
+		// force-marked a cancelled or paused turn `completed` merely
+		// because a guardrail was configured — the presence of a
+		// safety check silently rewrote the turn's own outcome.
+		const produced = ctx.recorder.materializeResult()
+		const outputVerdict = await runOutputGuardrails(
+			params.outputGuardrails,
+			{
+				sessionId: ctx.sessionId,
+				turnId: ctx.turnId,
+				output: produced,
+				messages: ctx.recorder.messages,
+			},
+			ctx.log,
+		)
+
+		if (outputVerdict.blocked || outputVerdict.rewritten !== undefined) {
+			ctx.recorder.clearStructuredOutput()
+			if (
+				params.structuredOutput &&
+				outputVerdict.rewritten !== undefined &&
+				ctx.recorder.stopReason === 'end_turn'
+			)
+				ctx.recorder.setStopReason('output_guardrail')
+		}
+
+		if (outputVerdict.blocked) {
+			await eventTranslator.emitEvent({
+				type: 'guardrail_triggered',
+				turnId: ctx.turnId,
+				stage: 'output',
+				action: 'block',
+				...(outputVerdict.name ? { guardrail: outputVerdict.name } : {}),
+				...(outputVerdict.reason ? { reason: outputVerdict.reason } : {}),
+			})
+			yield* eventTranslator.drainPending()
+			// Same reasoning as the input-guardrail branch above.
+			await ctx.recorder.recordAudit({
+				what: { action: 'guardrail:output', resource: outputVerdict.name },
+				outcome: 'refused',
+				reason: outputVerdict.reason ?? 'blocked by an output guardrail',
+				...(params.persona?.identity.role ? { persona: params.persona.identity.role } : {}),
+			})
+			ctx.recorder.setStopReason('output_guardrail')
+			ctx.recorder.setLastError(outputVerdict.reason ?? 'blocked by an output guardrail')
+			ctx.recorder.setResult('', 'guardrail_blocked')
+		} else if (outputVerdict.rewritten !== undefined) {
+			await eventTranslator.emitEvent({
+				type: 'guardrail_triggered',
+				turnId: ctx.turnId,
+				stage: 'output',
+				action: 'rewrite',
+				...(outputVerdict.name ? { guardrail: outputVerdict.name } : {}),
+				...(outputVerdict.reason ? { reason: outputVerdict.reason } : {}),
+			})
+			yield* eventTranslator.drainPending()
+			ctx.recorder.setResult(outputVerdict.rewritten, 'guardrail_rewritten')
+		}
+	}
+
+	if (params.consolidateInto && workingStateManager) {
+		const entry = consolidationEntry(workingStateManager.getState(), {
+			sessionId: ctx.sessionId,
+			turnId: ctx.turnId,
+			at: Date.now(),
+		})
+		if (entry) {
+			try {
+				// Same knowledge, same record: a later turn that learned what an
+				// earlier one already wrote down — archived included — adds nothing.
+				if (await isConsolidated(params.consolidateInto, entry)) {
+					ctx.log.info('consolidation skipped: this knowledge is already in the memory store', {
+						[NAMZU.TURN_ID]: ctx.turnId,
+					})
+				} else {
+					const { entry: saved } = await params.consolidateInto.create(entry)
+					await eventTranslator.emitEvent({
+						type: 'memory_consolidated',
+						memoryId: saved.id,
+						title: entry.title,
+						decisions: workingStateManager.getState().decisions.length,
+						discoveries: workingStateManager.getState().discoveries.length,
+						failures: workingStateManager.getState().failures.length,
+					})
+					yield* eventTranslator.drainPending()
+				}
+			} catch (error) {
+				ctx.log.warn('consolidation into the memory store failed', {
+					[NAMZU.TURN_ID]: ctx.turnId,
+					'namzu.memory.error': toErrorMessage(error),
+				})
+			}
+		}
+	}
+	if (ctx.abortController.signal.aborted) ctx.recorder.markCancelled()
+	yield* resultAssembler.completeTurn(rootSpan)
+}

package/src/runtime/query/fork/list.ts

@@ -0,0 +1,20 @@
+import type { CheckpointScope, SessionCheckpointStore } from '../../../store/checkpoint/index.js'
+import type { CheckpointListEntry } from '../../../types/session/fork.js'
+import { toCheckpointListEntry } from '../checkpoint.js'
+
+export interface ListCheckpointsInput {
+	/** The store the turn's checkpoints are in. */
+	readonly checkpointStore: SessionCheckpointStore
+	/** The turn whose checkpoints are listed, across the full attribution. */
+	readonly scope: CheckpointScope
+}
+
+/**
+ * Read-only listing of a turn's checkpoints, to pick a fork point for
+ * {@link import('./prepare.js').prepareForkState}. Returns the public
+ * {@link CheckpointListEntry} projection, oldest first.
+ */
+export async function listCheckpoints(input: ListCheckpointsInput): Promise<CheckpointListEntry[]> {
+	const checkpoints = await input.checkpointStore.list(input.scope)
+	return checkpoints.map(toCheckpointListEntry)
+}

package/src/runtime/query/fork/mutate.ts

@@ -0,0 +1,82 @@
+import type { ToolCallId } from '../../../types/ids/index.js'
+import {
+	type AssistantMessage,
+	type Message,
+	type ToolCall,
+	createToolMessage,
+} from '../../../types/message/index.js'
+import { type Mutation, MutationNotApplicableError } from '../../../types/session/fork.js'
+
+/**
+ * Returns the tool calls on the most recent assistant message that do not
+ * yet have a matching {@link import('../../../types/message/index.js').ToolMessage}
+ * response further down the message list. These are the fork-point "pending"
+ * tool calls that mutations may target.
+ */
+function findPendingToolCalls(messages: readonly Message[]): ToolCall[] {
+	let lastAssistantIdx = -1
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i]
+		if (msg && msg.role === 'assistant' && (msg.toolCalls?.length ?? 0) > 0) {
+			lastAssistantIdx = i
+			break
+		}
+	}
+	if (lastAssistantIdx === -1) return []
+
+	const assistant = messages[lastAssistantIdx] as AssistantMessage
+	const satisfied = new Set<string>()
+	for (let i = lastAssistantIdx + 1; i < messages.length; i++) {
+		const msg = messages[i]
+		if (msg && msg.role === 'tool') {
+			satisfied.add(msg.toolCallId)
+		}
+	}
+	return (assistant.toolCalls ?? []).filter((tc) => !satisfied.has(tc.id))
+}
+
+/**
+ * Apply an ordered list of {@link Mutation} to a checkpoint's message
+ * history at the fork point, producing a new message array that the
+ * resumed iteration loop consumes. Pure function; does not touch the turn
+ * store, does not emit events.
+ *
+ * Throws {@link MutationNotApplicableError} when an `injectToolResponse`
+ * mutation targets a tool call id that is not pending at the fork point —
+ * the error payload carries the list of ids that *are* pending so the
+ * caller can recover without guessing.
+ *
+ * See ses_005-deterministic-replay design §3.3.
+ */
+export function applyMutations(
+	messages: readonly Message[],
+	mutations: readonly Mutation[],
+): Message[] {
+	let current: Message[] = [...messages]
+	for (const m of mutations) {
+		current = applyOne(current, m)
+	}
+	return current
+}
+
+function applyOne(messages: Message[], mutation: Mutation): Message[] {
+	switch (mutation.type) {
+		case 'injectToolResponse': {
+			const pending = findPendingToolCalls(messages)
+			const match = pending.find((tc) => tc.id === mutation.toolCallId)
+			if (!match) {
+				throw new MutationNotApplicableError(
+					`No pending tool call ${mutation.toolCallId} at fork point`,
+					// `ToolCall.id` is a bare `string` — a provider chooses its own
+					// shape, which is what `ToolUseId` exists to say. This assertion
+					// satisfies `MutationNotApplicableError`'s parameter and is only
+					// ever read back as text in that message; it never becomes a
+					// key. Left as a cast because the honest fix is that parameter
+					// type, not this line.
+					pending.map((tc) => tc.id as ToolCallId),
+				)
+			}
+			return [...messages, createToolMessage(mutation.response.output, mutation.toolCallId)]
+		}
+	}
+}

package/src/runtime/query/fork/prepare.ts

@@ -0,0 +1,92 @@
+import type { CheckpointScope, SessionCheckpointStore } from '../../../store/checkpoint/index.js'
+import type { SessionLog } from '../../../store/session-log/index.js'
+import type { CheckpointId } from '../../../types/hitl/index.js'
+import type { Message } from '../../../types/message/index.js'
+import type { Checkpoint } from '../../../types/session/checkpoint.js'
+import type { Mutation } from '../../../types/session/fork.js'
+import type { TurnForkOrigin } from '../../../types/session/turn.js'
+import type { Logger } from '../../../utils/logger.js'
+import { restoreCheckpointContext } from '../checkpoint.js'
+import { applyMutations } from './mutate.js'
+
+/** Which checkpoint to fork at: an id, or the turn's newest. */
+export type CheckpointSelector = CheckpointId | 'latest'
+
+export interface PrepareForkInput {
+	/** The source session's log: the checkpoint's context is its fold. */
+	readonly sessionLog: SessionLog
+	/** The store the source turn's checkpoints are in. */
+	readonly checkpointStore: SessionCheckpointStore
+	/** The source turn, across the full attribution. */
+	readonly scope: CheckpointScope
+	/** Which checkpoint to fork at. */
+	readonly fromCheckpoint: CheckpointSelector
+	/** Mutations applied at the fork point before the caller hands the state to `query()`. */
+	readonly mutate?: Mutation[]
+	readonly logger?: Logger
+}
+
+export interface PreparedForkState {
+	/**
+	 * The context at the fork point, with mutations applied: the fold of the
+	 * source session's log through the checkpoint. Seed a NEW session with it
+	 * (`query({ sessionId: <new>, messages, forkedFrom })`).
+	 */
+	readonly messages: Message[]
+	/** The checkpoint the fork starts from. */
+	readonly sourceCheckpoint: Checkpoint
+	/**
+	 * Where the fork comes from. Pass it as `query({ forkedFrom })`: the new
+	 * session's `session_started.forkedFrom` names it, and the returned turn
+	 * carries it.
+	 */
+	readonly forkedFrom: TurnForkOrigin
+	/** The mutations that were applied. */
+	readonly mutations: readonly Mutation[]
+}
+
+/**
+ * Produce what a fork needs: the context at a checkpoint of a source turn,
+ * with mutations applied, and the origin the new session records. A fork is
+ * always a NEW session; the source session is only read.
+ *
+ * The checkpoint is restored under the same rules a resume uses: its
+ * document must match its `checkpoint_written` record and the log prefix it
+ * covers must be intact.
+ */
+export async function prepareForkState(input: PrepareForkInput): Promise<PreparedForkState> {
+	const sourceCheckpoint = await resolveCheckpoint(input)
+	const restored = await restoreCheckpointContext(input.sessionLog, sourceCheckpoint)
+	const mutations = input.mutate ?? []
+	const messages = applyMutations(restored.messages, mutations)
+	return {
+		messages,
+		sourceCheckpoint,
+		forkedFrom: {
+			sessionId: sourceCheckpoint.sessionId,
+			turnId: sourceCheckpoint.turnId,
+			checkpointId: sourceCheckpoint.checkpointId,
+		},
+		mutations,
+	}
+}
+
+async function resolveCheckpoint(input: PrepareForkInput): Promise<Checkpoint> {
+	if (input.fromCheckpoint === 'latest') {
+		const all = await input.checkpointStore.list(input.scope)
+		const newest = [...all].sort((a, b) => b.iteration - a.iteration)[0]
+		if (!newest) {
+			throw new Error(
+				`No checkpoints found for turn ${input.scope.turnId} of session ${input.scope.sessionId}`,
+			)
+		}
+		return (await input.checkpointStore.restore(input.scope, newest.checkpointId)) as Checkpoint
+	}
+	const checkpoint = await input.checkpointStore.restore(input.scope, input.fromCheckpoint)
+	if (!checkpoint) {
+		throw new Error(
+			`Checkpoint ${input.fromCheckpoint} not found for turn ${input.scope.turnId} of session ${input.scope.sessionId}`,
+		)
+	}
+	return checkpoint
+}

package/src/runtime/query/guard.ts

@@ -1,6 +1,6 @@
-import type { RunPersistence } from '../../manager/run/persistence.js'
-import { buildLimitConfig, checkLimitsDetailed } from '../../run/LimitChecker.js'
-import type { LimitCheckerConfig, StopReason } from '../../types/run/index.js'
+import type { TurnRecorder } from '../../manager/session/turn-recorder.js'
+import { buildLimitConfig, checkLimitsDetailed } from '../../turn/LimitChecker.js'
+import type { LimitCheckerConfig, StopReason } from '../../types/session/index.js'
 
 export interface GuardConfig {
 	tokenBudget: number
@@ -8,11 +8,11 @@ export interface GuardConfig {
 	costLimitUsd?: number
 	maxIterations?: number
 	/**
-	 * Wall-clock already consumed by this run before the current process
-	 * picked it up, from `IterationCheckpoint.guardState.elapsedMs`.
+	 * Wall-clock already consumed by this turn before the current process
+	 * picked it up, from the checkpoint's `guards.elapsedMs`.
 	 *
-	 * The timeout budget is a property of the RUN, not of the process
-	 * hosting it. Without the offset a run resumed from a checkpoint got a
+	 * The timeout budget is a property of the TURN, not of the process
+	 * hosting it. Without the offset a turn resumed from a checkpoint got a
 	 * fresh clock every time, so N resumes bought N x `timeoutMs`.
 	 */
 	elapsedMsOffset?: number
@@ -47,7 +47,7 @@ export class GuardCoordinator {
 	 * Adopt a checkpoint's elapsed time after construction.
 	 *
 	 * The guard is built before the checkpoint is read (restore is async and
-	 * happens inside the run generator), so the resume path cannot pass
+	 * happens inside the turn generator), so the resume path cannot pass
 	 * `elapsedMsOffset` to the constructor. Rather than reorder setup around
 	 * one field, let the resume branch hand it over.
 	 */
@@ -56,18 +56,18 @@ export class GuardCoordinator {
 	}
 
 	/**
-	 * Wall-clock left before this run is asked to start finishing.
+	 * Wall-clock left before this turn is asked to start finishing.
 	 *
 	 * NOT the time left before the deadline, and the difference is the whole
 	 * point. The checks above run BETWEEN iterations, so anything that waits
 	 * inside one cannot be stopped by them, and a caller sizing such a wait
-	 * needs a number the run actually owns: a fixed two-minute hold measured
-	 * against a run configured for twenty seconds kept it open for 120,267 ms.
+	 * needs a number the turn actually owns: a fixed two-minute hold measured
+	 * against a turn configured for twenty seconds kept it open for 120,267 ms.
 	 *
 	 * Measuring to the DEADLINE was the first attempt and it was wrong. The
 	 * binding constraint is `budgetWarningThreshold`, the point at which this
 	 * guard stops asking for more work and asks for a closing summary — that
-	 * last slice exists so the run can produce an answer, and a wait sized
+	 * last slice exists so the turn can produce an answer, and a wait sized
 	 * against the deadline eats into it. Half of the time-to-deadline, started
 	 * just under the threshold, ends at 95% of the budget: half the closing
 	 * reserve spent waiting for a result the closing answer was supposed to
@@ -78,9 +78,9 @@ export class GuardCoordinator {
 	 * iteration and this is read when the wait is about to start, so a long
 	 * iteration that crossed the line in between is told to wait for nothing.
 	 *
-	 * Reads through the same `startTime` the limit checks use, so a run
+	 * Reads through the same `startTime` the limit checks use, so a turn
 	 * resumed from a checkpoint (see `restoreElapsed`) reports the time left
-	 * on the RUN rather than on the process now hosting it.
+	 * on the TURN rather than on the process now hosting it.
 	 */
 	remainingBeforeFinalizeMs(): number {
 		if (this.limitConfig.timeoutMs === 0) return Number.POSITIVE_INFINITY
@@ -89,11 +89,11 @@ export class GuardCoordinator {
 	}
 
 	/**
-	 * Wall-clock left before the run's hard timeout.
+	 * Wall-clock left before the turn's hard timeout.
 	 *
 	 * Setup work that happens before the first iteration cannot rely on
 	 * {@link beforeIteration}: there is no iteration boundary to sample while
-	 * that work is pending. Callers use this value to put the same run-owned
+	 * that work is pending. Callers use this value to put the same turn-owned
 	 * deadline around such work instead of inventing a second clock.
 	 */
 	remainingUntilTimeoutMs(): number {
@@ -101,18 +101,18 @@ export class GuardCoordinator {
 		return Math.max(0, this.limitConfig.timeoutMs - (Date.now() - this.startTime))
 	}
 
-	beforeIteration(runMgr: RunPersistence, abortSignal: AbortSignal): GuardCheckResult {
+	beforeIteration(recorder: TurnRecorder, abortSignal: AbortSignal): GuardCheckResult {
 		const limitState = {
 			aborted: abortSignal.aborted,
-			totalTokens: runMgr.tokenUsage.totalTokens,
-			totalCost: runMgr.costInfo.totalCost,
-			unpricedTokens: runMgr.costInfo.unpricedTokens,
-			currentIteration: runMgr.currentIteration,
+			totalTokens: recorder.tokenUsage.totalTokens,
+			totalCost: recorder.costInfo.totalCost,
+			unpricedTokens: recorder.costInfo.unpricedTokens,
+			currentIteration: recorder.currentIteration,
 			startTime: this.startTime,
 		}
 
 		const limitResult = checkLimitsDetailed(this.limitConfig, limitState)
-		if (!abortSignal.aborted && runMgr.budget && runMgr.budget.remaining <= 0) {
+		if (!abortSignal.aborted && recorder.budget && recorder.budget.remaining <= 0) {
 			return {
 				shouldStop: true,
 				forceFinalize: false,

package/src/runtime/query/guardrail-presets.ts

@@ -11,7 +11,7 @@ import type {
 } from '../../types/guardrail/index.js'
 
 /**
- * Patterns for credentials that must never leave a run.
+ * Patterns for credentials that must never leave a turn.
  *
  * Deliberately narrow and prefix-anchored, unchanged by the move to
  * `constants/secret-patterns.ts`: a loose "looks like a secret" regex over
@@ -61,7 +61,7 @@ export function secretRedactionGuardrail(
 
 			for (const [label, pattern] of patterns) {
 				// Fresh lastIndex: these are module-level /g regexes and are
-				// reused across runs.
+				// reused across turns.
 				pattern.lastIndex = 0
 				if (!pattern.test(output)) continue
 				found.push(label)
@@ -97,7 +97,7 @@ const INJECTION_PATTERNS: readonly RegExp[] = [
 ]
 
 /**
- * Flag likely instruction-override attempts in the run's input.
+ * Flag likely instruction-override attempts in the turn's input.
  *
  * Input-side because it is cheapest there — nothing has been spent — and
  * because the same text reaching the model is the thing you are trying to
@@ -105,7 +105,7 @@ const INJECTION_PATTERNS: readonly RegExp[] = [
  *
  * It cannot see an INDIRECT injection, and that is not a limitation of the
  * patterns: an injection carried in a web page or a connected server's
- * answer never appears in the run's input at all. See
+ * answer never appears in the turn's input at all. See
  * {@link toolResultInjectionGuardrail}, which is the same list at the other
  * boundary.
  */
@@ -136,13 +136,13 @@ export function promptInjectionGuardrail(): NamedGuardrail<
  *
  * The case the input-side screen structurally cannot reach. An indirect
  * injection arrives in a fetched page or a connected server's answer, so it
- * is never in the run's input — by the time it matters the run is
+ * is never in the turn's input — by the time it matters the turn is
  * legitimate and the payload is riding on a result the model asked for.
  *
  * `refuse`, not `halt`: a hostile result is a reason to abandon that call,
- * not the run. The model is told the answer was refused and can choose
+ * not the turn. The model is told the answer was refused and can choose
  * something else, which is the behaviour that keeps the control switched on
- * — a screen that ends a run on a false positive gets removed, and then it
+ * — a screen that ends a turn on a false positive gets removed, and then it
  * protects nothing.
  *
  * **Detection is partial and this says so rather than implying coverage.**
@@ -494,13 +494,13 @@ export function toolResultCorrespondenceGuardrail(
 }
 
 /**
- * The screens a run installs on itself when its host configured none.
+ * The screens a turn installs on itself when its host configured none.
  *
  * A DEFAULT, and the reason it is here rather than on
  * {@link ToolRegistryConfig.resultGuardrails}: a host assembles a registry
  * and hands it to `runAgent`, so a registry-constructor default would be the
- * host's to write and this repository's default would reach nobody. The run
- * is the thing that has to carry it, and a run that wants none says so with
+ * host's to write and this repository's default would reach nobody. The turn
+ * is the thing that has to carry it, and a turn that wants none says so with
  * an empty array — which is the escape hatch, and it exists precisely because
  * the screen below can refuse a result.
  *
@@ -513,14 +513,14 @@ export function toolResultCorrespondenceGuardrail(
  * **A default that refuses a legitimate result is a default that gets turned
  * off, so the exemption has to be reachable from wherever the screen is
  * installed.** `toolResultCorrespondenceGuardrail({ passthroughTools })` is
- * how a host writing SDK code says so; a run's `toolResultGuardrails` array
+ * how a host writing SDK code says so; a turn's `toolResultGuardrails` array
  * is where it substitutes its own configured instance. An application that
  * ships the default without also shipping a way to name an exception has
  * shipped a switch with one position.
  *
  * Frozen, because it is handed to callers who may want to extend it:
  * `[...DEFAULT_TOOL_RESULT_GUARDRAILS, myScreen()]`. A caller that could
- * mutate it would be mutating the default for every other run in the process.
+ * mutate it would be mutating the default for every other turn in the process.
  */
 export const DEFAULT_TOOL_RESULT_GUARDRAILS: readonly ToolResultGuardrailSpec[] = Object.freeze([
 	toolResultCorrespondenceGuardrail(),