@namzu/sdk 42.0.2 → 44.0.0

package/src/registry/tool/screen.ts

@@ -37,11 +37,11 @@ function normalize<T>(spec: T | { name: string; check: T }): { name?: string; ch
 }
 
 /**
- * A guardrail that throws FAILS CLOSED, as the run-level ones do.
+ * A guardrail that throws FAILS CLOSED, as the turn-level ones do.
  *
  * `refuse` rather than `halt` for the same reason the tool boundary has a
  * recoverable refusal at all: a broken screen means this result's safety is
- * unknown, not that the run is unsalvageable. The model is told and can
+ * unknown, not that the turn is unsalvageable. The model is told and can
  * choose differently.
  */
 async function safely(
@@ -96,7 +96,7 @@ export async function screenToolResult(
 		)
 
 		if (verdict.action === 'halt') {
-			log.error('Tool-result guardrail halted the run', {
+			log.error('Tool-result guardrail halted the turn', {
 				[GENAI.TOOL_NAME]: ctx.toolName,
 				'namzu.guardrail.name': label,
 				'namzu.registry.reason': verdict.reason,

package/src/runtime/bidi/index.ts

@@ -1,4 +1,4 @@
 export { createMockBidiProvider } from './mock.js'
 export type { MockBidiScript, MockBidiSession } from './mock.js'
-export { BidiSessionCloseTimeoutError, startBidiRun } from './session.js'
-export type { BidiRun, BidiRunParams } from './session.js'
+export { BidiSessionCloseTimeoutError, startBidiTurn } from './session.js'
+export type { BidiTurn, BidiTurnParams } from './session.js'

package/src/runtime/bidi/session.ts

@@ -2,14 +2,14 @@ import { NAMZU } from '../../constants/telemetry/index.js'
 import type {
 	BidiConnectParams,
 	BidiProvider,
-	BidiRunEvent,
 	BidiSession,
+	BidiTurnEvent,
 } from '../../types/bidi/index.js'
 import type { ToolResultGuardrailSpec } from '../../types/guardrail/index.js'
-import type { RunId } from '../../types/ids/index.js'
+import type { SessionId, TurnId } from '../../types/ids/index.js'
 import type { ToolContext, ToolRegistryContract } from '../../types/tool/index.js'
 import { toErrorMessage } from '../../utils/error.js'
-import { generateRunId } from '../../utils/id.js'
+import { generateSessionId, generateTurnId } from '../../utils/id.js'
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { DEFAULT_TOOL_RESULT_GUARDRAILS } from '../query/guardrail-presets.js'
@@ -20,7 +20,7 @@ const MAX_TIMER_DELAY_MS = 2_147_483_647
 export class BidiSessionCloseTimeoutError extends Error {
 	constructor(readonly timeoutMs: number) {
 		super(
-			`Duplex provider session close did not settle within ${timeoutMs}ms. The local run is fenced and its tool authority was revoked, but provider cleanup is still unconfirmed.`,
+			`Duplex provider session close did not settle within ${timeoutMs}ms. The local turn is fenced and its tool authority was revoked, but provider cleanup is still unconfirmed.`,
 		)
 		this.name = 'BidiSessionCloseTimeoutError'
 	}
@@ -60,7 +60,7 @@ async function waitForProviderClose(pending: Promise<void>, timeoutMs: number):
  * the interruption arrived is abandoned rather than delivered.
  */
 
-export interface BidiRunParams {
+export interface BidiTurnParams {
 	readonly provider: BidiProvider
 	readonly tools: ToolRegistryContract
 	readonly connect: BidiConnectParams
@@ -78,8 +78,10 @@ export interface BidiRunParams {
 	 */
 	readonly closeTimeoutMs?: number
 	readonly log?: Logger
-	/** Overrides the generated id, so a host can correlate its own. */
-	readonly runId?: RunId
+	/** The session this duplex turn belongs to. Absent: a new session id is generated. */
+	readonly sessionId?: SessionId
+	/** Overrides the generated turn id, so a host can correlate its own. */
+	readonly turnId?: TurnId
 	/**
 	 * Screens for the results this session's tools produce. Absent installs
 	 * {@link DEFAULT_TOOL_RESULT_GUARDRAILS}; an empty array installs none.
@@ -92,21 +94,22 @@ export interface BidiRunParams {
 	readonly toolResultGuardrails?: readonly ToolResultGuardrailSpec[]
 }
 
-export interface BidiRun {
-	readonly runId: RunId
+export interface BidiTurn {
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
 	/** What the loop reports, in order. Ends when the session closes. */
-	events(): AsyncIterable<BidiRunEvent>
+	events(): AsyncIterable<BidiTurnEvent>
 	/** Push input from the human. */
 	send(input: Parameters<BidiSession['send']>[0]): Promise<void>
 	/**
-	 * Fence the local run immediately, abort tool contexts and close the
+	 * Fence the local turn immediately, abort tool contexts and close the
 	 * provider once. It does not wait for tool code that ignores cancellation;
-	 * provider cleanup is observed for `BidiRunParams.closeTimeoutMs`.
+	 * provider cleanup is observed for `BidiTurnParams.closeTimeoutMs`.
 	 */
 	close(): Promise<void>
 }
 
-export async function startBidiRun(params: BidiRunParams): Promise<BidiRun> {
+export async function startBidiTurn(params: BidiTurnParams): Promise<BidiTurn> {
 	params.signal?.throwIfAborted()
 	const closeTimeoutMs = params.closeTimeoutMs ?? DEFAULT_CLOSE_TIMEOUT_MS
 	if (
@@ -115,16 +118,18 @@ export async function startBidiRun(params: BidiRunParams): Promise<BidiRun> {
 		closeTimeoutMs > MAX_TIMER_DELAY_MS
 	) {
 		throw new RangeError(
-			`BidiRunParams.closeTimeoutMs must be an integer from 0 through ${MAX_TIMER_DELAY_MS}`,
+			`BidiTurnParams.closeTimeoutMs must be an integer from 0 through ${MAX_TIMER_DELAY_MS}`,
 		)
 	}
-	const runId = params.runId ?? generateRunId()
+	const sessionId = params.sessionId ?? generateSessionId()
+	const turnId = params.turnId ?? generateTurnId()
 	const log = resolveLogger(params.log).child({
 		[SCOPE_ATTRIBUTE]: 'runtime/bidi/session',
-		[NAMZU.RUN_ID]: runId,
+		[NAMZU.SESSION_ID]: sessionId,
+		[NAMZU.TURN_ID]: turnId,
 	})
 	const lifetime = new AbortController()
-	const queue: BidiRunEvent[] = []
+	const queue: BidiTurnEvent[] = []
 	let wake: (() => void) | undefined
 	let closed = false
 	let session: BidiSession | undefined
@@ -213,7 +218,7 @@ export async function startBidiRun(params: BidiRunParams): Promise<BidiRun> {
 	let generation = 0
 	const executionIds = new Set<string>()
 
-	const emit = (event: BidiRunEvent): boolean => {
+	const emit = (event: BidiTurnEvent): boolean => {
 		if (closed) return false
 		queue.push(event)
 		wake?.()
@@ -222,7 +227,9 @@ export async function startBidiRun(params: BidiRunParams): Promise<BidiRun> {
 
 	const executeCall = async (call: { id: string; name: string; arguments: string }) => {
 		const startedUnder = generation
-		if (!emit({ type: 'tool_started', runId, toolUseId: call.id, toolName: call.name })) {
+		if (
+			!emit({ type: 'tool_started', sessionId, turnId, toolUseId: call.id, toolName: call.name })
+		) {
 			return
 		}
 
@@ -236,7 +243,8 @@ export async function startBidiRun(params: BidiRunParams): Promise<BidiRun> {
 				input = {}
 			}
 			const context: ToolContext = {
-				runId,
+				sessionId,
+				turnId,
 				workingDirectory: params.workingDirectory,
 				abortSignal: lifetime.signal,
 				env: params.env ?? {},
@@ -256,19 +264,20 @@ export async function startBidiRun(params: BidiRunParams): Promise<BidiRun> {
 		if (startedUnder !== generation) {
 			// The human spoke over the model while this ran. Delivering the
 			// answer now would put it in a conversation that has moved on.
-			emit({ type: 'tool_abandoned', runId, toolUseId: call.id, toolName: call.name })
+			emit({ type: 'tool_abandoned', sessionId, turnId, toolUseId: call.id, toolName: call.name })
 			return
 		}
 
 		// Entering the provider send is the publication commit point. A later
 		// conversational interruption cannot recall a write already handed to
-		// the provider, but closing the run still closes the whole session and
+		// the provider, but closing the turn still closes the whole session and
 		// fences the local terminal event.
 		await activeSession.sendToolResult(call.id, output, isError)
 		if (closed) return
 		emit({
 			type: 'tool_completed',
-			runId,
+			sessionId,
+			turnId,
 			toolUseId: call.id,
 			toolName: call.name,
 			output,
@@ -282,17 +291,17 @@ export async function startBidiRun(params: BidiRunParams): Promise<BidiRun> {
 				if (closed) break
 				switch (event.type) {
 					case 'text':
-						emit({ type: 'text', runId, text: event.text })
+						emit({ type: 'text', sessionId, turnId, text: event.text })
 						break
 					case 'audio':
-						emit({ type: 'audio', runId, data: event.data, mediaType: event.mediaType })
+						emit({ type: 'audio', sessionId, turnId, data: event.data, mediaType: event.mediaType })
 						break
 					case 'tool_call': {
 						if (executionIds.has(event.id)) {
 							const error = new Error(
 								`Duplex provider repeated tool-call id "${event.id}". Re-executing it could repeat a side effect, so the session was closed.`,
 							)
-							emit({ type: 'error', runId, message: error.message })
+							emit({ type: 'error', sessionId, turnId, message: error.message })
 							beginClose(error, true)
 							break
 						}
@@ -300,24 +309,25 @@ export async function startBidiRun(params: BidiRunParams): Promise<BidiRun> {
 						// Started, not awaited: awaiting here would stall the very
 						// stream an interruption arrives on.
 						void executeCall(event).catch((err: unknown) => {
-							emit({ type: 'error', runId, message: toErrorMessage(err) })
+							emit({ type: 'error', sessionId, turnId, message: toErrorMessage(err) })
 						})
 						break
 					}
 					case 'turn_complete':
-						emit({ type: 'turn_complete', runId })
+						emit({ type: 'turn_complete', sessionId, turnId })
 						break
 					case 'interrupted':
 						generation++
-						emit({ type: 'interrupted', runId })
+						emit({ type: 'interrupted', sessionId, turnId })
 						break
 					case 'error':
-						emit({ type: 'error', runId, message: event.message })
+						emit({ type: 'error', sessionId, turnId, message: event.message })
 						break
 					case 'closed':
 						emit({
 							type: 'closed',
-							runId,
+							sessionId,
+							turnId,
 							...(event.reason !== undefined ? { reason: event.reason } : {}),
 						})
 						beginClose(new Error(event.reason ?? 'the duplex provider session closed'), false)
@@ -331,7 +341,7 @@ export async function startBidiRun(params: BidiRunParams): Promise<BidiRun> {
 			}
 		} catch (err) {
 			if (!closed) {
-				emit({ type: 'error', runId, message: toErrorMessage(err) })
+				emit({ type: 'error', sessionId, turnId, message: toErrorMessage(err) })
 				beginClose(err, true)
 			}
 		} finally {
@@ -340,7 +350,7 @@ export async function startBidiRun(params: BidiRunParams): Promise<BidiRun> {
 	})()
 	void pump.catch(() => undefined)
 
-	async function* events(): AsyncIterable<BidiRunEvent> {
+	async function* events(): AsyncIterable<BidiTurnEvent> {
 		while (true) {
 			while (queue.length > 0) {
 				const next = queue.shift()
@@ -355,7 +365,8 @@ export async function startBidiRun(params: BidiRunParams): Promise<BidiRun> {
 	}
 
 	return {
-		runId,
+		sessionId,
+		turnId,
 		events,
 		send: async (input) => {
 			lifetime.signal.throwIfAborted()

package/src/runtime/jobs/awaited-jobs.ts

@@ -20,12 +20,12 @@ export interface DeliverableJobExits {
 /**
  * Background jobs the model SAID it is waiting on.
  *
- * `CompletionInbox` gives a run a bounded, zero-token wait for a delegated
+ * `CompletionInbox` gives a turn a bounded, zero-token wait for a delegated
  * task nobody is blocked on, and `holdForOutstandingWork` spends it: the
  * model stops calling tools, the loop races the inbox against operator input,
- * and the run only settles once the result is in the transcript or the grace
+ * and the turn only settles once the result is in the transcript or the grace
  * is gone. Background shell jobs had none of it — so a model that started a
- * job and then had nothing left to do improvised, and the recorded run
+ * job and then had nothing left to do improvised, and the recorded turn
  * (research/resident/results/2026-09-14-exploration-policy-terra-tui.json)
  * shows what that costs: six `job read` polls, three `job list` polls and a
  * `sleep 30`, each one a full context resend.
@@ -38,11 +38,11 @@ export interface DeliverableJobExits {
  * `wait_for_job` named it (see {@link expect}); job existence means nothing.
  * That is the same distinction `CompletionInbox.expect` draws for a
  * background task, and it is what keeps a dev server or a file watcher —
- * started precisely so it would keep running — from holding every run of the
+ * started precisely so it would keep running — from holding every turn of the
  * session open for its grace period. The model that wants to wait says so.
  */
 export class AwaitedJobs {
-	/** Awaited and still running. Nothing else can hold a run open. */
+	/** Awaited and still running. Nothing else can hold a turn open. */
 	private readonly outstanding = new Set<string>()
 	/** Exits since the last {@link drain}. */
 	private exits: BackgroundJob[] = []
@@ -51,10 +51,10 @@ export class AwaitedJobs {
 
 	constructor(
 		private readonly source: AwaitedJobSource,
-		/** Whose jobs these are — the run or the session the jobs are bound to. */
+		/** Whose jobs these are — the turn or the session the jobs are bound to. */
 		private readonly owner: string,
 		/**
-		 * Whether the exit notice this run queues for the model is still
+		 * Whether the exit notice this turn queues for the model is still
 		 * unread. A second opinion on {@link noticesDelivered}, and it can
 		 * only ever narrow what counts as pending.
 		 *
@@ -113,7 +113,7 @@ export class AwaitedJobs {
 	 * Called by `wait_for_job`, and by nothing else: the wait is the whole
 	 * signal. A job that has ALREADY stopped is not recorded, because the
 	 * call that marks it is the same call that returns its output — holding
-	 * the run open afterwards would buy a turn to read a result the model has
+	 * the turn open afterwards would buy a turn to read a result the model has
 	 * just read. `CompletionInbox.expect` skips an already-claimed task for
 	 * the same reason.
 	 *
@@ -158,7 +158,7 @@ export class AwaitedJobs {
 	 *
 	 * Bounded by the caller, exactly as `CompletionInbox.waitForArrival` is: a
 	 * job that never exits — a dev server someone did await — must not keep a
-	 * run open, and only the run's own budget knows how long is long enough.
+	 * turn open, and only the turn's own budget knows how long is long enough.
 	 */
 	waitForArrival(timeoutMs: number, signal?: AbortSignal): Promise<void> {
 		if (signal?.aborted) return Promise.resolve()
@@ -212,7 +212,7 @@ export class AwaitedJobs {
 	 *
 	 * The pairing is the whole method. Draining the exits first and then
 	 * asking for the notice loses them on the branch that finds none: the
-	 * records are gone, no text was written, and the exit the run held itself
+	 * records are gone, no text was written, and the exit the turn held itself
 	 * open for is delivered by nobody. So {@link drain} is not called until
 	 * the delivery is certain, and an exit this could not deliver stays in
 	 * hand for the next one.
@@ -243,7 +243,7 @@ export class AwaitedJobs {
 	/**
 	 * Awaited jobs still running.
 	 *
-	 * Read when a run ends, so it can say which wait it walked away from.
+	 * Read when a turn ends, so it can say which wait it walked away from.
 	 * Nothing here is stopped by being read — the ids are a statement, and a
 	 * job's lifetime belongs to whoever owns it.
 	 */
@@ -254,8 +254,8 @@ export class AwaitedJobs {
 	/**
 	 * Stop listening. Safe to call more than once.
 	 *
-	 * A run that ends without this leaves its listener on a registry the host
-	 * reuses across runs — the leak `CompletionInbox.close` exists to prevent,
+	 * A turn that ends without this leaves its listener on a registry the host
+	 * reuses across turns — the leak `CompletionInbox.close` exists to prevent,
 	 * on the other subsystem.
 	 */
 	close(): void {

package/src/runtime/jobs/registry.ts

@@ -31,7 +31,7 @@ export type BackgroundJobStatus = 'running' | 'exited' | 'killed'
 
 export interface BackgroundJob {
 	readonly id: string
-	/** Whoever the job dies with — a run id, in practice. */
+	/** Whoever the job dies with — a turn id, or the session id for a job bound to the session. */
 	readonly owner: string
 	readonly command: string
 	readonly status: BackgroundJobStatus
@@ -83,8 +83,8 @@ export interface BackgroundJobRegistryConfig {
 	/**
 	 * Refused past this many LIVE jobs for one owner.
 	 *
-	 * Per owner rather than global: one run spawning a hundred watchers must
-	 * not be able to refuse a different run its first.
+	 * Per owner rather than global: one turn spawning a hundred watchers must
+	 * not be able to refuse a different turn its first.
 	 */
 	readonly maxJobsPerOwner?: number
 	/** Retained output per job. Oldest bytes go first, and are counted. */
@@ -151,7 +151,7 @@ export class BackgroundJobRegistry {
 	/**
 	 * Be told when a job ends, whoever owns it. A job outlives the call that
 	 * started it, so the one thing the model could not do was learn that it
-	 * had finished without polling; a run subscribes here and turns the exit
+	 * had finished without polling; a turn subscribes here and turns the exit
 	 * into a notice on its next tool result. Returns the unsubscribe.
 	 */
 	onExit(listener: (job: BackgroundJob) => void): () => void {
@@ -192,7 +192,7 @@ export class BackgroundJobRegistry {
 		const running = this.list(params.owner).filter((job) => job.status === 'running')
 		if (running.length >= this.maxJobs) {
 			// Refused, not queued. A queue would accept the call and start the
-			// work minutes later against a run that has since ended — the model
+			// work minutes later against a turn that has since ended — the model
 			// would be told its job is running and poll an id that does nothing.
 			throw new BackgroundJobLimitError({ owner: params.owner, limit: this.maxJobs })
 		}
@@ -393,7 +393,7 @@ export class BackgroundJobRegistry {
 	/**
 	 * Kill everything one owner started.
 	 *
-	 * The teardown call. Without it a run that ends leaves its jobs running
+	 * The teardown call. Without it a turn that ends leaves its jobs running
 	 * with nothing left that knows their ids — the orphan this whole module
 	 * exists to make impossible.
 	 */
@@ -420,8 +420,8 @@ export class BackgroundJobRegistry {
  *
  * The owner is bound here rather than passed by the caller, which is the
  * whole point: a tool holding this cannot start a job billed to somebody
- * else's run, nor read or kill one. `list` and the lookups are filtered to
- * the same owner, so an id from another run reads as unknown — the same
+ * else's turn, nor read or kill one. `list` and the lookups are filtered to
+ * the same owner, so an id from another turn reads as unknown — the same
  * answer the tenant checks give elsewhere in this tree, and for the same
  * reason.
  */
@@ -440,9 +440,9 @@ export function bindOwner(
 		/**
 		 * Be told that the model said it is waiting on a job's exit.
 		 *
-		 * The registry does not keep this: wait-intent belongs to the RUN that
-		 * expressed it, not to a registry a host may share across runs and
-		 * sessions. The run passes its own recorder here — `AwaitedJobs`, which
+		 * The registry does not keep this: wait-intent belongs to the TURN that
+		 * expressed it, not to a registry a host may share across turns and
+		 * sessions. The turn passes its own recorder here — `AwaitedJobs`, which
 		 * is what the iteration loop holds open for. Absent means nobody is
 		 * listening, and `markAwaited` is then absent from the bound ref rather
 		 * than present and silently doing nothing.

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

@@ -0,0 +1,110 @@
+import { resolveNamzuHome } from '../../session/home.js'
+import { type SessionIndex, openSessionIndex } from '../../store/session-index/index.js'
+import {
+	DiskSessionLog,
+	type SessionLease,
+	type SessionLog,
+} from '../../store/session-log/index.js'
+import { NamzuError } from '../../types/errors/index.js'
+import type { SessionId, TurnId } from '../../types/ids/index.js'
+
+/** How a session-level operation finds the session's log. */
+export interface SessionLocatorOptions {
+	/** Use this log directly. */
+	readonly log?: SessionLog
+	/** Otherwise resolve the log through this index. */
+	readonly index?: SessionIndex
+	/** Otherwise open the index under this home. Defaults to `resolveNamzuHome()`. */
+	readonly home?: string
+	/** A lease the caller already holds. Absent: the lease is claimed and released around the append. */
+	readonly lease?: SessionLease
+}
+
+/** Lease time-to-live for a lease a session-level operation claims for one append. */
+const OPERATION_LEASE_TTL_MS = 30_000
+
+/**
+ * The log a session-level operation acts on: the one given, or the one the
+ * index files the session under.
+ */
+export async function locateSessionLog(
+	sessionId: SessionId,
+	options: Omit<SessionLocatorOptions, 'lease'> = {},
+): Promise<SessionLog> {
+	if (options.log) {
+		if (options.log.sessionId !== sessionId) {
+			throw new NamzuError({
+				code: 'invalid_config',
+				message: `The log given belongs to session ${options.log.sessionId}, not ${sessionId}.`,
+				details: { sessionId, logSessionId: options.log.sessionId },
+			})
+		}
+		return options.log
+	}
+	const index =
+		options.index ?? (await openSessionIndex({ home: options.home ?? resolveNamzuHome() }))
+	try {
+		const session = await index.getSession(sessionId)
+		if (!session) {
+			throw new NamzuError({
+				code: 'not_found',
+				message: `Session ${sessionId} is not in the session index.`,
+				details: { sessionId },
+			})
+		}
+		return new DiskSessionLog({
+			sessionId,
+			file: session.logPath,
+			sessionDir: session.logPath.replace(/\.jsonl$/, ''),
+		})
+	} finally {
+		if (!options.index) index.close()
+	}
+}
+
+/**
+ * Run `operation` under the session's writer lease: the caller's, or one
+ * claimed for the operation and released after it. A session leased by a
+ * live writer is refused rather than waited for.
+ */
+export async function withSessionLease<T>(
+	log: SessionLog,
+	lease: SessionLease | undefined,
+	operation: (lease: SessionLease) => Promise<T>,
+): Promise<T> {
+	if (lease) return operation(lease)
+	const claimed = await log.claim({
+		holder: `namzu:${process.pid}:${log.sessionId}`,
+		ttlMs: OPERATION_LEASE_TTL_MS,
+	})
+	if (!claimed) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: `Session ${log.sessionId} is leased by a live writer; pass its lease, or wait for it to finish.`,
+			details: { sessionId: log.sessionId },
+		})
+	}
+	try {
+		return await operation(claimed)
+	} finally {
+		await log.release(claimed).catch(() => undefined)
+	}
+}
+
+/**
+ * Close a session's active turn without resuming it: appends
+ * `turn_failed{ error.code: 'abandoned', reason }` and frees the session for
+ * its next turn. The only other way out of a paused turn is `resumeSession`.
+ *
+ * A running turn is refused with `TurnInProgressError`: it is cancelled by
+ * its own process, not abandoned from outside.
+ */
+export async function abandonTurn(
+	sessionId: SessionId,
+	turnId: TurnId,
+	reason: string,
+	options: SessionLocatorOptions = {},
+): Promise<void> {
+	const log = await locateSessionLog(sessionId, options)
+	await withSessionLease(log, options.lease, (lease) => log.abandonTurn(lease, turnId, reason))
+}

package/src/runtime/query/approval-policy.ts

@@ -1,18 +1,18 @@
 import type {
 	ApprovalPolicy,
 	ApprovalPolicyChange,
-	RunApprovalPolicy,
+	SessionApprovalPolicy,
 } from '../../types/hitl/policy.js'
-import type { RunId } from '../../types/ids/index.js'
-import type { RunEvent } from '../../types/run/index.js'
+import type { TurnId } from '../../types/ids/index.js'
+import type { SessionEventDraft } from './events.js'
 
 /**
- * The run's approval policy, as a box the run reads through.
+ * The turn's approval policy, as a box the turn reads through.
  *
  * Every call site that used to close over `params.resumeHandler` reads
  * `.current.handler` instead, which is the entire mechanism: a closure
- * captured at `query()` start cannot be changed without ending the run, and
- * ending the run to change one setting discards the in-flight step and the
+ * captured at `query()` start cannot be changed without ending the turn, and
+ * ending the turn to change one setting discards the in-flight step and the
  * context it was built from. `permissionMode` learned this first and is the
  * shape this follows.
  */
@@ -20,15 +20,15 @@ import type { RunEvent } from '../../types/run/index.js'
 /** A policy that says yes to everything, named so a log can say so. */
 export const AUTO_APPROVE_POLICY_NAME = 'auto-approve'
 
-export interface CreateRunApprovalPolicyOptions {
-	readonly runId: RunId
+export interface CreateSessionApprovalPolicyOptions {
+	readonly turnId: TurnId
 	readonly initial: ApprovalPolicy
-	readonly emit: (event: RunEvent) => Promise<void>
+	readonly emit: (event: SessionEventDraft) => Promise<void>
 }
 
-export function createRunApprovalPolicy(
-	options: CreateRunApprovalPolicyOptions,
-): RunApprovalPolicy {
+export function createSessionApprovalPolicy(
+	options: CreateSessionApprovalPolicyOptions,
+): SessionApprovalPolicy {
 	let current = options.initial
 	let unannounced: ApprovalPolicyChange | undefined
 	return {
@@ -54,7 +54,7 @@ export function createRunApprovalPolicy(
 			// answer.
 			await options.emit({
 				type: 'approval_policy_changed',
-				runId: options.runId,
+				turnId: options.turnId,
 				from,
 				to: policy.name,
 				reason,

package/src/runtime/query/callback-inference.ts

@@ -2,7 +2,10 @@ import { z } from 'zod'
 import { StreamTextAccumulator } from '../../provider/stream-text.js'
 import { type TokenUsage, mergeTokenUsage } from '../../types/common/index.js'
 import { createSystemMessage, createUserMessage } from '../../types/message/index.js'
-import type { PreparationTextRequest, PreparationTextResult } from '../../types/run/prepare-step.js'
+import type {
+	PreparationTextRequest,
+	PreparationTextResult,
+} from '../../types/session/prepare-step.js'
 import type { IterationContext } from './iteration/phases/context.js'
 
 const requestSchema = z
@@ -39,15 +42,19 @@ export function createCallbackInference(
 					`${phase === 'preparation' ? 'A' : 'An'} ${owner} may make only one inference call.`,
 				)
 			used = true
-			const deadline = new AbortController()
-			const timer = setTimeout(
-				() => deadline.abort(new Error(`${label} inference timed out.`)),
-				input.timeoutMs,
-			)
+			// No deadline of our own on the request — see the note on
+			// `PreparationTextRequest.timeoutMs`. The two bounds that remain are
+			// the ones every other model request in the turn has: the turn's own
+			// cancellation, and the provider's request timeout. An expired local
+			// deadline here would abort a CONTACTED request, and a request that
+			// ends without its usage receipt leaves the shared ledger unresolved,
+			// which stops the whole turn — so a stage that gave up on its own
+			// optional inference would take the operator's turn with it. That is
+			// not hypothetical: it is what a 10s deadline did to every turn
+			// against a reasoning model slower than 10s per auxiliary answer.
 			const signal = AbortSignal.any([
 				ctx.abortController.signal,
 				lifetime.signal,
-				deadline.signal,
 				...(requestedSignal ? [requestedSignal] : []),
 			])
 			const requested = ctx.servingMember?.() ?? { index: 0, providerId: ctx.provider.id }
@@ -68,7 +75,7 @@ export function createCallbackInference(
 					providerRoute: route(),
 					messages: [createSystemMessage(input.system), createUserMessage(input.prompt)],
 					maxTokens: input.maxTokens,
-					...(ctx.runConfig.effort ? { effort: ctx.runConfig.effort } : {}),
+					...(ctx.turnConfig.effort ? { effort: ctx.turnConfig.effort } : {}),
 					signal,
 				})) {
 					if (chunk.usage) usage = usage ? mergeTokenUsage(usage, chunk.usage) : { ...chunk.usage }
@@ -86,8 +93,7 @@ export function createCallbackInference(
 				if (invalidOutput) throw new Error(invalidOutput)
 				return { text: text.text, usage, servedBy: route() }
 			} finally {
-				clearTimeout(timer)
-				if (usage) ctx.runMgr.accumulateUsage(usage, route())
+				if (usage) ctx.recorder.accumulateUsage(usage, route())
 			}
 		},
 	}