@namzu/sdk 42.0.2 → 44.0.0

package/src/contracts/session/turn.ts

@@ -0,0 +1,67 @@
+import type { ProjectId, SessionId, TurnId } from '../../types/ids/index.js'
+import type { Turn } from '../../types/session/turn.js'
+import type { ApiPermissionMode, ISOTimestamp } from '../api.js'
+import type { WireTurnStatus } from './turn-status.js'
+
+/**
+ * Why a turn stopped, as the wire's `stop_reason` field carries it.
+ *
+ * The domain stop reason under a wire name, so the HTTP field stays decoupled
+ * from the internal type's identifier.
+ */
+export type WireStopReason = NonNullable<Turn['stopReason']>
+
+/** The per-turn configuration a client may set. Every field is optional; the agent's defaults fill the rest. */
+export interface WireTurnConfig {
+	model?: string
+	temperature?: number
+	tokenBudget?: number
+	maxResponseTokens?: number
+	timeoutMs?: number
+	streamIdleTimeoutMs?: number
+	maxRequestRichContentBytes?: number
+	permissionMode?: ApiPermissionMode
+	systemPrompt?: string
+}
+
+/** What one turn spent. Usage of this turn only; child sessions report their own. */
+export interface WireUsage {
+	input_tokens: number
+	output_tokens: number
+	total_tokens: number
+	total_cost_usd?: number
+}
+
+/**
+ * One turn of a session, as HTTP, SSE and A2A payloads carry it.
+ *
+ * A turn always belongs to a session: `session_id` is required. A child
+ * session's turn names the parent session and the parent turn whose tool call
+ * spawned it; `child_session_ids` lists the child sessions this turn spawned.
+ */
+export interface WireTurn {
+	turn_id: TurnId
+	session_id: SessionId
+	project_id: ProjectId | null
+	agent_id: string
+	agent_name?: string
+	status: WireTurnStatus
+	stop_reason?: WireStopReason
+	created_at: ISOTimestamp
+	started_at?: ISOTimestamp
+	completed_at?: ISOTimestamp
+	duration_ms?: number
+	model?: string
+	config: WireTurnConfig
+	usage?: WireUsage
+	iterations?: number
+	/** The authoritative answer, after guardrail, review and structured-output overrides. */
+	result?: string
+	last_error?: string
+	/** Present on a child session's turn: the session that delegated it. */
+	parent_session_id?: SessionId
+	/** Present on a child session's turn: the parent turn whose tool call spawned the child. */
+	parent_turn_id?: TurnId
+	depth?: number
+	child_session_ids?: SessionId[]
+}

package/src/directory/derive-supervisor.ts

@@ -71,7 +71,7 @@ function delegatePlan(entry: SubAgentEntry, fallbackModel: string): DelegatePlan
 /**
  * Turn a project that declares delegates into a supervisor configuration.
  *
- * The counterpart to `deriveRunOptions` for the multi-agent shape, and the
+ * The counterpart to `deriveTurnOptions` for the multi-agent shape, and the
  * same contract: it converts, it does not run. `SupervisorAgent` needs an
  * `agentIds` roster and a manager that can spawn them; this supplies the
  * roster from the directory and leaves the manager to the host.
@@ -95,7 +95,7 @@ export function deriveSupervisorOptions(
 		// result would be a coordinator that cannot coordinate — and the
 		// caller asked for a supervisor, which means they expected delegates.
 		throw new Error(
-			`${manifest.root} declares no delegates, so there is nothing for a supervisor to coordinate. Add directories under agents/, or use deriveRunOptions for a single agent.`,
+			`${manifest.root} declares no delegates, so there is nothing for a supervisor to coordinate. Add directories under agents/, or use deriveTurnOptions for a single agent.`,
 		)
 	}
 

package/src/directory/derive.ts

@@ -1,7 +1,7 @@
 import type { RunAgentOptions } from '../agents/runAgent.js'
 import { ToolRegistry } from '../registry/tool/execute.js'
 
-import type { DeriveRunOptionsInput, DirectoryManifest } from './types.js'
+import type { DeriveTurnOptionsInput, DirectoryManifest } from './types.js'
 
 /**
  * Turn a loaded project into the options `runAgent` takes.
@@ -11,9 +11,9 @@ import type { DeriveRunOptionsInput, DirectoryManifest } from './types.js'
  * spreads `overrides` or stops using this function — there is no behaviour
  * reachable only through the convention.
  */
-export function deriveRunOptions(
+export function deriveTurnOptions(
 	manifest: DirectoryManifest,
-	input: DeriveRunOptionsInput,
+	input: DeriveTurnOptionsInput,
 ): RunAgentOptions {
 	if (manifest.modules === 'skip') {
 		// The manifest is structurally complete and its tools were never
@@ -21,7 +21,7 @@ export function deriveRunOptions(
 		// to do with the project. Running it would produce an agent with no
 		// capabilities and no indication why.
 		throw new Error(
-			'This manifest was loaded with modules: "skip", so no tool was imported and none can be registered. Load with modules: "evaluate" before deriving run options.',
+			'This manifest was loaded with modules: "skip", so no tool was imported and none can be registered. Load with modules: "evaluate" before deriving runAgent options.',
 		)
 	}
 

package/src/directory/index.ts

@@ -1,5 +1,5 @@
 export { loadDirectory } from './load.js'
-export { deriveRunOptions } from './derive.js'
+export { deriveTurnOptions } from './derive.js'
 export { deriveSupervisorOptions } from './derive-supervisor.js'
 export type {
 	DelegatePlan,
@@ -7,7 +7,7 @@ export type {
 	SupervisorPlan,
 } from './derive-supervisor.js'
 export type {
-	DeriveRunOptionsInput,
+	DeriveTurnOptionsInput,
 	DirectoryDiagnosticCode,
 	DirectoryDiagnosticSeverity,
 	LoadDirectoryOptions,

package/src/directory/load.ts

@@ -247,7 +247,7 @@ export async function loadDirectory(
  *
  * A delegate does not get delegates of its own. The cap is a real decision,
  * not a missing feature: unbounded nesting is a topology question — who may
- * spawn whom, and how deep a run may fan out — and answering it by default is
+ * spawn whom, and how deep a turn may fan out — and answering it by default is
  * how a directory layout ends up deciding a system's shape. It also removes
  * the cycle: `agents/a/agents/b/agents/a` cannot be built if the second level
  * is never read.
@@ -516,7 +516,7 @@ async function loadAt(
 			const child = await loadAt(entry.path, options, depth + 1)
 			// The child's diagnostics are the parent's. A delegate that could
 			// not load is a fact about THIS project, and a caller reading one
-			// list should not have to walk the tree to find out the run will be
+			// list should not have to walk the tree to find out the turn will be
 			// short a specialist.
 			for (const d of child.diagnostics) {
 				diagnostics.push({ ...d, message: entry.relativePath + ': ' + d.message })

package/src/directory/types.ts

@@ -185,7 +185,7 @@ export interface DirectoryManifest {
 	 * A DISPLAY LABEL — `config.name`, else the directory's basename, else
 	 * `'agent'`.
 	 *
-	 * Not a trace key, and `deriveRunOptions` forwards it to `runAgent` only
+	 * Not a trace key, and `deriveTurnOptions` forwards it to `runAgent` only
 	 * when `agent.ts` declared one. A name guessed from a directory basename
 	 * would collide across sibling projects and silently merge their traces,
 	 * which is worse than the SDK's own default.
@@ -250,7 +250,7 @@ export interface LoadDirectoryOptions {
 	readonly moduleTimeoutMs?: number
 }
 
-export interface DeriveRunOptionsInput {
+export interface DeriveTurnOptionsInput {
 	readonly provider: LLMProvider
 	readonly prompt: string | Message[]
 	/** Wins over `agent.ts`. Required when `agent.ts` names no model. */

package/src/eval/experiment.ts

@@ -2,7 +2,7 @@ import type {
 	CaseResult,
 	CaseStatus,
 	EvalCase,
-	EvalRun,
+	EvalTurn,
 	ExperimentReport,
 	Score,
 	Scorer,
@@ -18,11 +18,11 @@ export interface ExperimentConfig<TInput = unknown> {
 	/** Applied to every case unless the case overrides them. */
 	scorers: readonly Scorer[]
 	/**
-	 * Execute one case. Returning an `EvalRun` rather than driving `query()`
-	 * here keeps the harness independent of how you construct a run —
+	 * Execute one case. Returning an `EvalTurn` rather than driving `query()`
+	 * here keeps the harness independent of how you construct a turn —
 	 * scripted mock, real provider, or a whole agent behind a facade.
 	 */
-	run: (input: TInput, evalCase: EvalCase<TInput>, signal: AbortSignal) => Promise<EvalRun>
+	run: (input: TInput, evalCase: EvalCase<TInput>, signal: AbortSignal) => Promise<EvalTurn>
 	/**
 	 * Wall-clock deadline for one case, including execution and every
 	 * scorer. Unset means no deadline.
@@ -32,7 +32,7 @@ export interface ExperimentConfig<TInput = unknown> {
 	 * both phases; I/O-owning scorers should forward it to their transport,
 	 * as `judgeScorer` does.
 	 *
-	 * A run that exhausts the budget is reported as failed. A scorer that
+	 * A turn that exhausts the budget is reported as failed. A scorer that
 	 * exhausts the remainder is unavailable, making an otherwise unjudged
 	 * case inconclusive. Either way the suite continues: forty cases should
 	 * not be lost to one operation that hung.
@@ -166,7 +166,7 @@ async function evaluateCase<TInput>(
 ): Promise<CaseResult> {
 	const deadline = openCaseDeadline(timeoutMs)
 	try {
-		const run = await executeCase(config, evalCase, deadline)
+		const turn = await executeCase(config, evalCase, deadline)
 		const scorers = evalCase.scorers ?? config.scorers
 		const scores: Record<string, Score> = {}
 
@@ -184,7 +184,7 @@ async function evaluateCase<TInput>(
 				)
 			}
 			seen.add(scorer.name)
-			scores[scorer.name] = await safeScore(scorer, run, evalCase, deadline)
+			scores[scorer.name] = await safeScore(scorer, turn, evalCase, deadline)
 		}
 
 		// Only scores that were actually produced count — an unavailable
@@ -201,7 +201,7 @@ async function evaluateCase<TInput>(
 		// judge 1 averages to 0.75 and reports passed at a threshold of
 		// 0.75 — the exact regression the harness exists to catch,
 		// reported green. An UNAVAILABLE gate does not fail the case;
-		// it did not judge the run at all, which is the inconclusive
+		// it did not judge the turn at all, which is the inconclusive
 		// path, not a failure.
 		const failedGates = scorers
 			.filter((s) => s.severity === 'gate')
@@ -222,7 +222,7 @@ async function evaluateCase<TInput>(
 						: 'failed'
 		return {
 			case: evalCase.name,
-			run,
+			turn,
 			scores,
 			mean,
 			status,
@@ -238,13 +238,13 @@ async function evaluateCase<TInput>(
 
 /**
  * A case that throws is a RESULT, not a crash. An eval suite whose first
- * broken case aborts the run tells you nothing about the other forty.
+ * broken case aborts the suite tells you nothing about the other forty.
  */
 async function executeCase<TInput>(
 	config: ExperimentConfig<TInput>,
 	evalCase: EvalCase<TInput>,
 	deadline: CaseDeadline,
-): Promise<EvalRun> {
+): Promise<EvalTurn> {
 	const startedAt = Date.now()
 	try {
 		const work = config.run(evalCase.input, evalCase, deadline.signal)
@@ -268,29 +268,29 @@ async function executeCase<TInput>(
 /** A throwing scorer scores zero with the throw as its reason. */
 async function safeScore(
 	scorer: Scorer,
-	run: EvalRun,
+	turn: EvalTurn,
 	evalCase: EvalCase,
 	deadline: CaseDeadline,
 ): Promise<Score> {
-	// A run that THREW scores zero, whatever the scorer would have said.
+	// A turn that THREW scores zero, whatever the scorer would have said.
 	// `executeCase` catches the failure and returns an empty run, and an
 	// empty run walks straight into every scorer's happy path:
 	// `stepBudgetScorer` sees 0 steps against its allowance and returns 1,
 	// `trajectoryScorer` sees no tools expected and none called and returns
-	// 1. So a suite whose runs were all dying reported green. The failure is
-	// recorded on `run.error` and nothing consulted it.
-	if (run.error !== undefined) {
-		return { score: 0, reason: `run failed: ${run.error}`, details: { error: run.error } }
+	// 1. So a suite whose turns were all dying reported green. The failure is
+	// recorded on `turn.error` and nothing consulted it.
+	if (turn.error !== undefined) {
+		return { score: 0, reason: `turn failed: ${turn.error}`, details: { error: turn.error } }
 	}
 
 	try {
 		deadline.signal.throwIfAborted()
 		// Defer invocation into the promise so a synchronous scorer throw is
 		// raced and observed by the same path as an asynchronous rejection.
-		const work = Promise.resolve().then(() => scorer.score(run, evalCase, deadline.signal))
+		const work = Promise.resolve().then(() => scorer.score(turn, evalCase, deadline.signal))
 		return await deadline.race(work)
 	} catch (err) {
-		// UNAVAILABLE, not zero. A scorer that threw did not judge the run
+		// UNAVAILABLE, not zero. A scorer that threw did not judge the turn
 		// badly — it failed to judge it at all, and the two call for
 		// opposite responses. Scoring the throw zero was survivable while
 		// every scorer was a pure function; a scorer that reaches a provider
@@ -299,7 +299,7 @@ async function safeScore(
 		return {
 			score: 0,
 			unavailable: true,
-			reason: `scorer "${scorer.name}" could not judge this run: ${
+			reason: `scorer "${scorer.name}" could not judge this turn: ${
 				err instanceof Error ? err.message : String(err)
 			}`,
 		}
@@ -355,8 +355,8 @@ export function formatReport(report: ExperimentReport): string {
 		`${report.name}: ${report.passed}/${report.cases.length} passed (mean ${report.mean.toFixed(2)}) in ${report.durationMs}ms`,
 		// On its own line and always printed, including when the interval is
 		// undefined. A mean printed alone is the thing that has been
-		// over-read: two runs three points apart look like a difference, and
-		// at the n a hand-built suite has they are usually the same run
+		// over-read: two experiments three points apart look like a difference, and
+		// at the n a hand-built suite has they are usually the same experiment
 		// twice. Computing the interval and not showing it would leave the
 		// reader exactly where they started.
 		`  ${describeUncertainty(report.mean, report.uncertainty ?? derivedUncertainty(report))}`,
@@ -395,7 +395,7 @@ export function formatReport(report: ExperimentReport): string {
 					lines.push(`      ${name}: ${score.reason}`)
 				}
 			}
-			if (failure.run.error) lines.push(`      error: ${failure.run.error}`)
+			if (failure.turn.error) lines.push(`      error: ${failure.turn.error}`)
 		}
 	}
 

package/src/eval/from-turn.ts

@@ -0,0 +1,50 @@
+import type { Turn } from '../types/session/turn.js'
+import type { EvalTurn } from './types.js'
+
+/**
+ * Project a finished `Turn` into the shape scorers consume.
+ *
+ * This is the whole bridge between the harness and the runtime, and it is
+ * three lines of mapping because `Turn.steps` exists. Before that, a
+ * trajectory scorer would have had to correlate raw `SessionEvent`s by
+ * iteration number and diff cumulative counters — which is why the step
+ * record had to land before the harness could.
+ */
+export function evalTurnFromTurn(turn: Turn, opts: { durationMs?: number } = {}): EvalTurn {
+	const steps = turn.steps ?? []
+	return {
+		output: turn.result ?? null,
+		...(turn.structuredOutput !== undefined ? { structuredOutput: turn.structuredOutput } : {}),
+		steps,
+		// Flattened in call order across steps — the trajectory.
+		toolCalls: steps.flatMap((s) => s.toolCalls.map((c) => c.function.name)),
+		...(turn.stopReason ? { stopReason: turn.stopReason } : {}),
+		totalTokens: turn.tokenUsage.totalTokens,
+		totalCostUsd: turn.costInfo.totalCost,
+		durationMs: opts.durationMs ?? (turn.endedAt ?? Date.now()) - turn.startedAt,
+		...(turn.lastError ? { error: turn.lastError } : {}),
+	}
+}
+
+/**
+ * Drain a `query()` generator to its returned `Turn`, then project it.
+ *
+ * The common case, so it does not need writing per suite:
+ *
+ * ```ts
+ * runExperiment({
+ *   name: 'file-editing',
+ *   cases,
+ *   scorers: [trajectoryScorer(), completionScorer()],
+ *   run: (input) => evalTurnFromQuery(query({ provider, tools, messages: input, … })),
+ * })
+ * ```
+ */
+export async function evalTurnFromQuery(
+	generator: AsyncGenerator<unknown, Turn>,
+): Promise<EvalTurn> {
+	const startedAt = Date.now()
+	let next = await generator.next()
+	while (!next.done) next = await generator.next()
+	return evalTurnFromTurn(next.value, { durationMs: Date.now() - startedAt })
+}

package/src/eval/harness-verification.ts

@@ -94,7 +94,7 @@ function measured(trial: HarnessTrial): boolean {
 	const { result } = trial
 	const scores = Object.values(result.scores)
 	return (
-		!result.run.error &&
+		!result.turn.error &&
 		(result.status === 'passed' || result.status === 'failed') &&
 		scores.length > 0 &&
 		scores.every((s) => !s.unavailable && Number.isFinite(s.score) && s.score >= 0 && s.score <= 1)
@@ -176,15 +176,15 @@ export function compareHarnessTrials(batch: HarnessVerificationBatch): HarnessCo
 	const usage = { rollouts: baseline.size * 2, tokens: 0, costUsd: 0, durationMs: 0 }
 	for (const trial of [...batch.baseline, ...batch.candidate]) {
 		const values = [
-			trial.result.run.totalTokens,
-			trial.result.run.totalCostUsd,
-			trial.result.run.durationMs,
+			trial.result.turn.totalTokens,
+			trial.result.turn.totalCostUsd,
+			trial.result.turn.durationMs,
 		]
 		if (values.some((n) => !Number.isFinite(n) || n < 0))
 			throw new Error('Invalid recorded harness usage.')
-		usage.tokens += trial.result.run.totalTokens
-		usage.costUsd += trial.result.run.totalCostUsd
-		usage.durationMs += trial.result.run.durationMs
+		usage.tokens += trial.result.turn.totalTokens
+		usage.costUsd += trial.result.turn.totalCostUsd
+		usage.durationMs += trial.result.turn.durationMs
 	}
 	return {
 		tasks,

package/src/eval/index.ts

@@ -1,4 +1,4 @@
-export { evalRunFromQuery, evalRunFromRun } from './from-run.js'
+export { evalTurnFromQuery, evalTurnFromTurn } from './from-turn.js'
 export { compareHarnessTrials, reviewHarnessCandidate } from './harness-verification.js'
 export type { HarnessProtectionPlan, HarnessProtectionCheck } from './harness-protection.js'
 export type {
@@ -27,7 +27,7 @@ export type {
 	CaseResult,
 	CaseStatus,
 	EvalCase,
-	EvalRun,
+	EvalTurn,
 	ExperimentReport,
 	Score,
 	Scorer,

package/src/eval/judge.ts

@@ -1,12 +1,12 @@
 import { collectChatCompletion } from '../provider/collect-chat-completion.js'
 import { resolveStreamIdleTimeoutMs, withStreamIdleTimeout } from '../provider/idle-timeout.js'
 import type { LLMProvider } from '../types/provider/interface.js'
-import type { EvalCase, EvalRun, Score, Scorer } from './types.js'
+import type { EvalCase, EvalTurn, Score, Scorer } from './types.js'
 
 /**
  * Grade an open-ended answer with a model.
  *
- * Every other scorer here is a pure function over the run, which is what
+ * Every other scorer here is a pure function over the turn, which is what
  * makes them cheap and reproducible — and also what makes them unable to
  * say anything about whether an answer is *good*. `containsScorer` can
  * check that a required phrase appears; it cannot tell a correct
@@ -46,7 +46,7 @@ export interface JudgeScorerConfig {
 	 */
 	scale?: number
 	/**
-	 * Show the judge which tools the run called. Default false.
+	 * Show the judge which tools the turn called. Default false.
 	 *
 	 * Useful when the rubric is about method rather than answer, and a
 	 * needless cost otherwise — the trajectory is usually longer than the
@@ -58,7 +58,7 @@ export interface JudgeScorerConfig {
 	 *
 	 * Truncation is disclosed IN the prompt. A judge shown a silently cut
 	 * answer marks it down for stopping mid-sentence, which scores our
-	 * truncation rather than the run.
+	 * truncation rather than the turn.
 	 */
 	maxOutputChars?: number
 	/**
@@ -150,12 +150,12 @@ function parseVerdict(reply: string, scale: number): Verdict {
 
 function buildPrompt(
 	config: JudgeScorerConfig,
-	run: EvalRun,
+	turn: EvalTurn,
 	evalCase: EvalCase,
 	scale: number,
 ): string {
 	const limit = config.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS
-	const answer = run.output ?? ''
+	const answer = turn.output ?? ''
 	const truncated = answer.length > limit
 
 	const sections: string[] = [
@@ -180,7 +180,7 @@ function buildPrompt(
 	if (config.includeTrajectory === true) {
 		sections.push(
 			'',
-			`TOOLS CALLED, in order:\n${run.toolCalls.length > 0 ? run.toolCalls.join(' -> ') : '(none)'}`,
+			`TOOLS CALLED, in order:\n${turn.toolCalls.length > 0 ? turn.toolCalls.join(' -> ') : '(none)'}`,
 		)
 	}
 
@@ -219,12 +219,12 @@ export function judgeScorer(config: JudgeScorerConfig): Scorer {
 
 	return {
 		name: config.name ?? 'judge',
-		async score(run: EvalRun, evalCase: EvalCase, signal?: AbortSignal): Promise<Score> {
+		async score(turn: EvalTurn, evalCase: EvalCase, signal?: AbortSignal): Promise<Score> {
 			const response = await collectChatCompletion(
 				provider.chatStream({
 					model: config.model,
-					messages: [{ role: 'user', content: buildPrompt(config, run, evalCase, scale) }],
-					// The same run must grade the same way twice, or a
+					messages: [{ role: 'user', content: buildPrompt(config, turn, evalCase, scale) }],
+					// The same turn must grade the same way twice, or a
 					// regression cannot be told from sampling noise.
 					temperature: 0,
 					maxTokens: 512,

package/src/eval/scorers.ts

@@ -1,10 +1,10 @@
-import type { EvalCase, EvalRun, Score, Scorer } from './types.js'
+import type { EvalCase, EvalTurn, Score, Scorer } from './types.js'
 
 /**
  * Longest common subsequence length between two tool sequences.
  *
  * Subsequence, not set intersection: order carries meaning in a
- * trajectory. Reading a file before editing it is not the same run as
+ * trajectory. Reading a file before editing it is not the same turn as
  * editing then reading, and a set-based score cannot tell them apart.
  */
 function lcsLength(a: readonly string[], b: readonly string[]): number {
@@ -24,7 +24,7 @@ function lcsLength(a: readonly string[], b: readonly string[]): number {
 }
 
 /**
- * How closely the run's tool sequence matched the expected one, as F1 over
+ * How closely the turn's tool sequence matched the expected one, as F1 over
  * the longest common subsequence.
  *
  * Trajectory, not final answer. Namzu's most load-bearing behavior is
@@ -35,16 +35,16 @@ function lcsLength(a: readonly string[], b: readonly string[]): number {
  * tool calls where it took one. Final-answer scoring cannot see that;
  * this can.
  *
- * Extra calls cut precision, missing calls cut recall, so a run that does
- * the right thing wastefully and a run that skips a step score
+ * Extra calls cut precision, missing calls cut recall, so a turn that does
+ * the right thing wastefully and a turn that skips a step score
  * differently — which is the distinction a final-answer score collapses.
  */
 export function trajectoryScorer(): Scorer {
 	return {
 		name: 'trajectory',
-		score(run: EvalRun, evalCase: EvalCase): Score {
+		score(turn: EvalTurn, evalCase: EvalCase): Score {
 			const expected = evalCase.expectedTools ?? []
-			const actual = run.toolCalls
+			const actual = turn.toolCalls
 
 			if (expected.length === 0 && actual.length === 0) {
 				return { score: 1, reason: 'no tools expected and none called' }
@@ -81,34 +81,34 @@ export function trajectoryScorer(): Scorer {
 	}
 }
 
-/** The run settled cleanly rather than erroring or being cut off. */
+/** The turn settled cleanly rather than erroring or being cut off. */
 export function completionScorer(
 	acceptable: readonly string[] = ['end_turn', 'stop_condition'],
 ): Scorer {
 	return {
 		name: 'completion',
-		// Binary by construction: the run either settled cleanly or it did
+		// Binary by construction: the turn either settled cleanly or it did
 		// not, so there is no score between 0 and 1 for a mean to soften.
 		// Averaged in, a hard 0 here is carried by three good fuzzy scores.
 		severity: 'gate',
-		score(run: EvalRun): Score {
-			if (run.error) {
-				return { score: 0, reason: `run failed: ${run.error}` }
+		score(turn: EvalTurn): Score {
+			if (turn.error) {
+				return { score: 0, reason: `turn failed: ${turn.error}` }
 			}
-			const ok = run.stopReason !== undefined && acceptable.includes(run.stopReason)
+			const ok = turn.stopReason !== undefined && acceptable.includes(turn.stopReason)
 			return {
 				score: ok ? 1 : 0,
 				reason: ok
-					? `settled as ${run.stopReason}`
-					: `settled as ${run.stopReason ?? 'unknown'}, expected one of ${acceptable.join(', ')}`,
-				details: { stopReason: run.stopReason },
+					? `settled as ${turn.stopReason}`
+					: `settled as ${turn.stopReason ?? 'unknown'}, expected one of ${acceptable.join(', ')}`,
+				details: { stopReason: turn.stopReason },
 			}
 		},
 	}
 }
 
 /**
- * The run stayed within a step budget.
+ * The turn stayed within a step budget.
  *
  * A regression that makes the agent take four turns where it took one is
  * invisible to correctness scoring and very visible on the bill.
@@ -116,8 +116,8 @@ export function completionScorer(
 export function stepBudgetScorer(maxSteps: number): Scorer {
 	return {
 		name: 'step-budget',
-		score(run: EvalRun): Score {
-			const used = run.steps.length
+		score(turn: EvalTurn): Score {
+			const used = turn.steps.length
 			return {
 				score: used <= maxSteps ? 1 : Math.max(0, maxSteps / used),
 				reason:
@@ -137,8 +137,8 @@ export function containsScorer(...required: string[]): Scorer {
 		// A required fragment is required. Partial credit here reads as
 		// "most of the answer was there", which is not what was asked.
 		severity: 'gate',
-		score(run: EvalRun): Score {
-			const text = run.output ?? ''
+		score(turn: EvalTurn): Score {
+			const text = turn.output ?? ''
 			const missing = required.filter((r) => !text.includes(r))
 			return {
 				score: required.length === 0 ? 1 : (required.length - missing.length) / required.length,
@@ -153,7 +153,7 @@ export function containsScorer(...required: string[]): Scorer {
 }
 
 /**
- * Judge the run with a caller-supplied predicate.
+ * Judge the turn with a caller-supplied predicate.
  *
  * The escape hatch for anything the built-in scorers do not cover. For
  * a model-graded judge, reach for `judgeScorer` first: it handles the
@@ -163,7 +163,7 @@ export function containsScorer(...required: string[]): Scorer {
  */
 export function customScorer(
 	name: string,
-	fn: (run: EvalRun, evalCase: EvalCase) => Score | Promise<Score>,
+	fn: (turn: EvalTurn, evalCase: EvalCase) => Score | Promise<Score>,
 ): Scorer {
 	return { name, score: fn }
 }