@namzu/sdk 43.0.0 → 44.0.0

package/src/plugin/lifecycle.ts

@@ -29,7 +29,8 @@ import type {
 	PluginMCPServerConfig,
 	PluginScope,
 } from '../types/plugin/index.js'
-import type { RunEvent } from '../types/run/index.js'
+import { assertPluginHookEvent } from '../types/plugin/index.js'
+import type { SessionEvent } from '../types/session/index.js'
 import type { ToolDefinition, ToolRegistryContract } from '../types/tool/index.js'
 import { toErrorMessage } from '../utils/error.js'
 import { generatePluginId } from '../utils/id.js'
@@ -112,7 +113,7 @@ export interface PluginLifecycleManagerConfig {
 	hookTimeoutMs?: number
 	/**
 	 * Where each MCP server's reconnect policy is registered, so an operator
-	 * can retune it while a run is live.
+	 * can retune it while a turn is live.
 	 *
 	 * Optional, and its absence is not a degraded mode: without one the
 	 * supervisor uses its own defaults, which is what it did before this
@@ -140,7 +141,7 @@ export interface PluginLifecycleManagerConfig {
 	 * was discovered.
 	 *
 	 * Reported rather than blocked, for the reason `MCPToolDiscovery`
-	 * already gives: a development server legitimately changes between runs,
+	 * already gives: a development server legitimately changes between sessions,
 	 * while a production one changing mid-session is the rug pull — advertise
 	 * something benign at approval time, swap it afterwards. Only the host
 	 * knows which it is looking at.
@@ -215,6 +216,10 @@ export class PluginLifecycleManager {
 	 * registration order.
 	 */
 	registerHook(pluginId: PluginId, hook: PluginHookDefinition): void {
+		// Refused here rather than left to never fire: a hook module still
+		// naming `run_start` would otherwise attach to an event nothing emits,
+		// and the operator would learn of the rename only by its silence.
+		assertPluginHookEvent(hook.event)
 		const handlers = this.hookHandlers.get(hook.event) ?? []
 		handlers.push({
 			pluginId,
@@ -701,7 +706,7 @@ export class PluginLifecycleManager {
 	async executeHooks(
 		event: PluginHookEvent,
 		context: Omit<PluginHookContext, 'pluginId' | 'event'>,
-		emitRunEvent?: (event: RunEvent) => Promise<void>,
+		emitSessionEvent?: (event: SessionEvent) => Promise<void>,
 	): Promise<PluginHookResult[]> {
 		const callerSignal = context.signal
 		callerSignal?.throwIfAborted()
@@ -716,7 +721,7 @@ export class PluginLifecycleManager {
 		// follow it, and none of those results can change the cancellation that
 		// already happened. Other hook events retain their existing flow-control
 		// semantics.
-		const observationalFanOut = event === 'run_interrupt'
+		const observationalFanOut = event === 'turn_interrupt'
 
 		// Determine execution order: post_* hooks run backward (for cleanup semantics)
 		const isPost = event.startsWith('post_')
@@ -748,10 +753,11 @@ export class PluginLifecycleManager {
 				event,
 			}
 
-			if (emitRunEvent) {
-				await emitRunEvent({
+			if (emitSessionEvent) {
+				await emitSessionEvent({
 					type: 'plugin_hook_executing',
-					runId: context.runId,
+					sessionId: context.sessionId,
+					...(context.turnId !== undefined ? { turnId: context.turnId } : {}),
 					pluginId,
 					hookEvent: event,
 				})
@@ -764,7 +770,7 @@ export class PluginLifecycleManager {
 			// The deadline timer is captured and cleared in `finally`.
 			// Without that it stayed armed after the hook resolved, and an
 			// armed timer keeps the Node event loop alive: hooks fire on
-			// every tool call and every model call, so a run of twenty tool
+			// every tool call and every model call, so a turn of twenty tool
 			// calls left twenty live timers and the process could not exit
 			// until the last one expired. Nothing failed — it just hung, for
 			// up to the timeout, every time.
@@ -801,7 +807,7 @@ export class PluginLifecycleManager {
 				result = await Promise.race(races)
 				callerSignal?.throwIfAborted()
 			} catch (err) {
-				// Cancellation belongs to the run, not to the plugin. Turning it
+				// Cancellation belongs to the turn, not to the plugin. Turning it
 				// into a hook error would let the query continue after its caller
 				// withdrew authority and would report Stop as a plugin failure.
 				if (callerSignal?.aborted) throw callerSignal.reason
@@ -822,11 +828,12 @@ export class PluginLifecycleManager {
 				durationMs,
 			})
 
-			if (emitRunEvent) {
+			if (emitSessionEvent) {
 				callerSignal?.throwIfAborted()
-				await emitRunEvent({
+				await emitSessionEvent({
 					type: 'plugin_hook_completed',
-					runId: context.runId,
+					sessionId: context.sessionId,
+					...(context.turnId !== undefined ? { turnId: context.turnId } : {}),
 					pluginId,
 					hookEvent: event,
 					result,

package/src/plugin/shell-hook.ts

@@ -2,7 +2,7 @@
  * A shell command as a plugin hook.
  *
  * The lifecycle manager carries a hook system — `pre_tool_use`,
- * `post_tool_use`, `run_start`, `run_end` and the rest — and `registerHook`
+ * `post_tool_use`, `turn_start`, `turn_end` and the rest — and `registerHook`
  * lets a host attach a handler without a plugin on disk. What every host then
  * writes for itself is the same adapter: run a command, hand it the event,
  * read its exit code. This file is that adapter, once, so an operator
@@ -12,16 +12,24 @@
  * ## The contract
  *
  * The command runs with `sh -c` in `cwd`. It receives one JSON object on
- * stdin — `event`, `cwd`, `run_id`, and for tool events `tool_name`,
- * `tool_input` and (after the call) `tool_result` — and the same facts as
- * `NAMZU_HOOK_EVENT`, `NAMZU_RUN_ID`, `NAMZU_TOOL_NAME` and, when the input
- * names a file, `NAMZU_TOOL_PATH`. Its exit code is its answer:
+ * stdin — `event`, `cwd`, `session_id`, `turn_id` inside a turn, and for
+ * tool events `tool_name`, `tool_input` and (after the call) `tool_result`;
+ * `subagent_stop` adds `parent_session_id` and `parent_turn_id` — and the
+ * same facts as `NAMZU_HOOK_EVENT`, `NAMZU_SESSION_ID`, `NAMZU_TURN_ID`,
+ * `NAMZU_TOOL_NAME` and, when the input names a file, `NAMZU_TOOL_PATH`.
+ *
+ * `session_start` and `session_end` run outside any turn, so they carry no
+ * `turn_id` on stdin and no `NAMZU_TURN_ID` in the environment — not even
+ * one inherited from the host's own environment. A hook that needs "which
+ * turn" has it exactly when there is one.
+ *
+ * Its exit code is its answer:
  *
  * - `0` — carry on.
  * - `2` — **block.** Before a tool (`pre_tool_use`) the call is skipped and the
  *   model is told why, with the hook's stderr as the reason. On any other
- *   event a 2 is reported and the run carries on: there is nothing left to
- *   block once the tool has run or the run has started.
+ *   event a 2 is reported and the turn carries on: there is nothing left to
+ *   block once the tool has run or the turn has started.
  * - anything else — the hook's own failure. Reported through the logger,
  *   never blocking. A formatter that crashed must not stop the agent editing,
  *   and a script missing its interpreter (127) must not read as "forbidden".
@@ -38,6 +46,13 @@
  *
  * ## Bounds
  *
+ * ## Renamed events
+ *
+ * `run_start`, `run_end` and `run_interrupt` became `turn_start`, `turn_end`
+ * and `turn_interrupt`. A config that still names an old event is refused by
+ * {@link attachShellHooks}, and the refusal names the new one: a hook that
+ * silently stopped firing is worse than a config that fails to load.
+ *
  * Each hook has a deadline (`timeoutMs`, default 30 s, capped at ten minutes)
  * and its output is captured to a bound. A hook that times out is reported
  * and does not block: one that could not answer in time has not answered no.
@@ -53,6 +68,7 @@ import type {
 	PluginHookEvent,
 	PluginHookResult,
 } from '../types/plugin/index.js'
+import { RENAMED_PLUGIN_HOOK_EVENTS } from '../types/plugin/index.js'
 import { asPluginId } from '../utils/id.js'
 import { NOOP_LOGGER } from '../utils/log/create-logger.js'
 import type { Logger } from '../utils/logger.js'
@@ -73,8 +89,8 @@ export type ShellHookEvent = Extract<
 	| 'pre_compact'
 	| 'post_compact'
 	| 'subagent_stop'
-	| 'run_start'
-	| 'run_end'
+	| 'turn_start'
+	| 'turn_end'
 >
 
 export const SHELL_HOOK_EVENTS: readonly ShellHookEvent[] = [
@@ -86,8 +102,8 @@ export const SHELL_HOOK_EVENTS: readonly ShellHookEvent[] = [
 	'pre_compact',
 	'post_compact',
 	'subagent_stop',
-	'run_start',
-	'run_end',
+	'turn_start',
+	'turn_end',
 ]
 
 /** One shell command at one event. */
@@ -114,7 +130,7 @@ const MAX_CAPTURE_BYTES = 64 * 1024
 /**
  * `matcher` against a tool name: `*`, or a `|`-separated list of names, each
  * of which may end in `*`. Case-sensitive, because tool names are. A matcher
- * on an event with no tool (`run_start`) matches nothing unless it is `*`.
+ * on an event with no tool (`turn_start`) matches nothing unless it is `*`.
  */
 export function shellHookMatches(
 	matcher: string | undefined,
@@ -144,9 +160,14 @@ export interface ShellHookOutcome {
 export interface ShellHookInput {
 	readonly event: ShellHookEvent
 	readonly cwd: string
-	readonly runId: string
-	readonly sessionId?: string
-	readonly parentRunId?: string
+	/** Always present: every hook fires in a session. */
+	readonly sessionId: string
+	/** The turn the hook fired in. Absent on `session_start` and `session_end`. */
+	readonly turnId?: string
+	/** The delegating session, on `subagent_stop`. */
+	readonly parentSessionId?: string
+	/** The parent turn whose tool call spawned the child, on `subagent_stop`. */
+	readonly parentTurnId?: string
 	readonly prompt?: string
 	readonly compaction?: PluginCompactionInfo
 	readonly toolName?: string
@@ -171,9 +192,10 @@ export function runShellHook(
 	const payload = JSON.stringify({
 		event: input.event,
 		cwd: input.cwd,
-		run_id: input.runId,
-		...(input.sessionId !== undefined ? { session_id: input.sessionId } : {}),
-		...(input.parentRunId !== undefined ? { parent_run_id: input.parentRunId } : {}),
+		session_id: input.sessionId,
+		...(input.turnId !== undefined ? { turn_id: input.turnId } : {}),
+		...(input.parentSessionId !== undefined ? { parent_session_id: input.parentSessionId } : {}),
+		...(input.parentTurnId !== undefined ? { parent_turn_id: input.parentTurnId } : {}),
 		...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
 		...(input.compaction !== undefined ? { compaction: input.compaction } : {}),
 		...(input.toolName !== undefined ? { tool_name: input.toolName } : {}),
@@ -181,16 +203,19 @@ export function runShellHook(
 		...(input.toolResult !== undefined ? { tool_result: input.toolResult } : {}),
 	})
 	const toolPath = pathOf(input.toolInput)
+	// A hook outside a turn must not see a turn id, including one the host
+	// inherited from an enclosing hook's environment.
+	const { NAMZU_TURN_ID: _inheritedTurnId, ...inherited } = process.env
 	return new Promise((resolve) => {
 		let child: ReturnType<typeof spawn>
 		try {
 			child = spawn('sh', ['-c', entry.command], {
 				cwd: input.cwd,
 				env: {
-					...process.env,
+					...inherited,
 					NAMZU_HOOK_EVENT: input.event,
-					NAMZU_RUN_ID: input.runId,
-					...(input.sessionId !== undefined ? { NAMZU_SESSION_ID: input.sessionId } : {}),
+					NAMZU_SESSION_ID: input.sessionId,
+					...(input.turnId !== undefined ? { NAMZU_TURN_ID: input.turnId } : {}),
 					...(input.toolName !== undefined ? { NAMZU_TOOL_NAME: input.toolName } : {}),
 					...(toolPath !== undefined ? { NAMZU_TOOL_PATH: toolPath } : {}),
 				},
@@ -352,10 +377,13 @@ export function createShellHook(
 				{
 					event,
 					cwd: options.cwd,
-					runId: String(context.runId),
-					...(context.sessionId !== undefined ? { sessionId: String(context.sessionId) } : {}),
-					...(context.parentRunId !== undefined
-						? { parentRunId: String(context.parentRunId) }
+					sessionId: String(context.sessionId),
+					...(context.turnId !== undefined ? { turnId: String(context.turnId) } : {}),
+					...(context.parentSessionId !== undefined
+						? { parentSessionId: String(context.parentSessionId) }
+						: {}),
+					...(context.parentTurnId !== undefined
+						? { parentTurnId: String(context.parentTurnId) }
 						: {}),
 					...(context.prompt !== undefined ? { prompt: context.prompt } : {}),
 					...(context.compaction !== undefined ? { compaction: context.compaction } : {}),
@@ -385,12 +413,23 @@ export function createShellHook(
  * manager runs `post_*` hooks in reverse, as it does for plugins, so a
  * formatter registered last runs first after a write. Returns how many were
  * attached.
+ *
+ * Throws, before registering anything, when the config names a renamed event
+ * (`run_start` and the rest); the message names the event that replaced it.
  */
 export function attachShellHooks(
 	manager: Pick<PluginLifecycleManager, 'registerHook'>,
 	hooks: ShellHooksConfig,
 	options: ShellHookOptions & { readonly pluginId?: PluginId },
 ): number {
+	for (const key of Object.keys(hooks)) {
+		const renamed = RENAMED_PLUGIN_HOOK_EVENTS[key]
+		if (renamed !== undefined) {
+			throw new Error(
+				`Shell hook event '${key}' was renamed to '${renamed}'. Rename it in the hooks config.`,
+			)
+		}
+	}
 	const pluginId = options.pluginId ?? SHELL_HOOKS_PLUGIN_ID
 	let count = 0
 	for (const event of SHELL_HOOK_EVENTS) {

package/src/pricing/index.ts

@@ -1,14 +1,14 @@
 /**
- * Rate lookup for a run's tokens.
+ * Rate lookup for a turn's tokens.
  *
  * The kernel had a cost calculation and no data to feed it: `costInfo` moved
  * only when a host passed `pricing` to `query()`, no shipped surface passed
- * one, and so every run reported a total of zero. `runConfig.costLimitUsd` is
+ * one, and so every turn reported a total of zero. `turnConfig.costLimitUsd` is
  * enforced against that same total, which made a declared budget a budget that
  * could never trigger.
  *
  * This is the data. It is IN-TREE and versioned at build time rather than
- * fetched, so a cost number is reproducible from a commit and an offline run
+ * fetched, so a cost number is reproducible from a commit and an offline turn
  * still prices correctly — a runtime fetch gives neither. See
  * `scripts/generate-model-prices.mjs` for why the source is reviewed rather
  * than refreshed, and `rates.source.json` for the rates themselves.
@@ -42,7 +42,7 @@ export function normaliseModelId(model: string): string {
  * The rate card for a model, or `undefined` when nobody here has one.
  *
  * `undefined` is a real answer and the caller must keep it distinct from a
- * rate of zero. Zero means this run genuinely costs nothing — the local
+ * rate of zero. Zero means this turn genuinely costs nothing — the local
  * drivers, which bill per token exactly never. `undefined` means the total is
  * unknowable, and a caller that flattens the two reproduces the defect this
  * whole module exists to remove, one level down.
@@ -70,7 +70,7 @@ export function resolveModelPricing(
 	// Checked before the model id, deliberately. An unmetered driver bills
 	// nothing whatever it is asked to run, and its models are whatever the
 	// operator has pulled onto the machine — enumerable by nobody. Requiring a
-	// row for each would make every local run unpriced, which would report
+	// row for each would make every local turn unpriced, which would report
 	// "cost unknown" about the one case where the cost is known exactly.
 	if (vendor.unmetered) return UNMETERED
 	if (model === undefined) return undefined

package/src/pricing/rates.source.json

@@ -11,12 +11,12 @@
 		"costLimitUsd behaviour on an unrelated commit, with no review and no diff.",
 		"",
 		"Absent is a real answer. A model with no row here reports UNKNOWN cost, not",
-		"zero, and a run that sets runConfig.costLimitUsd against it is refused rather",
+		"zero, and a turn that sets turnConfig.costLimitUsd against it is refused rather",
 		"than run without a budget. So the correct move when a rate cannot be",
 		"established is to leave the row out, never to approximate it.",
 		"",
 		"unmetered: true means this driver bills nothing by construction — local",
-		"inference. Its runs are priced at zero, which is KNOWN-free and therefore",
+		"inference. Its turns are priced at zero, which is KNOWN-free and therefore",
 		"distinct from unknown. Such a vendor needs no model rows.",
 		"",
 		"Matching is EXACT on a normalised id (lowercased, one trailing -YYYYMMDD or",
@@ -59,7 +59,7 @@
 			"verified": "2026-08-10",
 			"promptIncludesCacheReads": false,
 			"reportsCacheWrites": true,
-			"note": "The last two rows exist because the driver's own offline catalogue offers those models and this table did not price them — a lookup-key gap that reads as `cost unknown` and is invisible to the generator's own check, which only proves the module matches this file. `providers/anthropic` asserts the two lists agree. Vendor list prices. Cache read is the vendor's published 0.1x of the input rate; cache write is its published 1.25x for the five-minute entry, which is the default TTL and the one the driver's `cacheControl: { type: 'auto' }` asks for. A time-limited introductory rate applied to one model at the time of entry; this table has no time dimension and records the list rate, so a run inside a promotional window is over-reported rather than mis-modelled.",
+			"note": "The last two rows exist because the driver's own offline catalogue offers those models and this table did not price them — a lookup-key gap that reads as `cost unknown` and is invisible to the generator's own check, which only proves the module matches this file. `providers/anthropic` asserts the two lists agree. Vendor list prices. Cache read is the vendor's published 0.1x of the input rate; cache write is its published 1.25x for the five-minute entry, which is the default TTL and the one the driver's `cacheControl: { type: 'auto' }` asks for. A time-limited introductory rate applied to one model at the time of entry; this table has no time dimension and records the list rate, so a turn inside a promotional window is over-reported rather than mis-modelled.",
 			"models": [
 				{
 					"id": "claude-fable-5",
@@ -146,7 +146,7 @@
 			"verified": "2026-08-10",
 			"promptIncludesCacheReads": true,
 			"reportsCacheWrites": false,
-			"note": "Vendor list prices for text models, cached-input rate included. The driver hard-codes cacheWriteTokens to zero, so no write rate is carried. Embedding models are omitted (no output rate, and a chat run never reaches one), as are models whose cached-input rate was not published alongside the others — an unestablished rate is left out rather than approximated, which is the rule this whole file follows.",
+			"note": "Vendor list prices for text models, cached-input rate included. The driver hard-codes cacheWriteTokens to zero, so no write rate is carried. Embedding models are omitted (no output rate, and a chat turn never reaches one), as are models whose cached-input rate was not published alongside the others — an unestablished rate is left out rather than approximated, which is the rule this whole file follows.",
 			"models": [
 				{
 					"id": "gpt-5.6-sol",
@@ -292,7 +292,7 @@
 		}
 	],
 	"absent": [
-		"Drivers deliberately carrying no rows, so that a run through them reports",
+		"Drivers deliberately carrying no rows, so that a turn through them reports",
 		"unknown rather than a number nobody checked:",
 		"",
 		"  bedrock    — partner-operated, on a separate rate card from the vendor whose",

package/src/probe/context.ts

@@ -1,14 +1,16 @@
-import type { RunId } from '../types/ids/index.js'
+import type { SessionId, TurnId } from '../types/ids/index.js'
 import type { ProbeContext } from '../types/probe/index.js'
 
 export interface ProbeContextInput {
-	readonly runId?: RunId
+	readonly sessionId?: SessionId
+	readonly turnId?: TurnId
 	readonly isReplay?: boolean
 }
 
 export function buildProbeContext(input: ProbeContextInput = {}): ProbeContext {
 	return Object.freeze({
-		runId: input.runId,
+		sessionId: input.sessionId,
+		turnId: input.turnId,
 		isReplay: input.isReplay ?? false,
 	})
 }

package/src/probe/registry.ts

@@ -241,7 +241,7 @@ export class ProbeRegistry implements ProbeObservation, ProbeEnforcement {
 				//
 				// An OBSERVER that throws is still skipped, a few lines up.
 				// That asymmetry IS deliberate: an observer was never asked a
-				// question, so it has no answer to withhold, and taking a run
+				// question, so it has no answer to withhold, and taking a turn
 				// down because a metrics handler crashed would be the same
 				// mistake pointing the other way.
 				this.logThrow(entry.name ?? 'unnamed', frozen.type, error)

package/src/prompt/coding-agent-doctrine.ts

@@ -129,7 +129,7 @@ export interface CodingAgentDoctrineOptions {
 
 /**
  * The doctrine as a `static` contribution: it depends on nothing that changes
- * inside a run, so it belongs in the cached prefix. Register it on the
+ * inside a turn, so it belongs in the cached prefix. Register it on the
  * `PromptContributionRegistry` handed to `query`; it renders after
  * `systemPrompt` and the skills section.
  */

package/src/prompt/contributions.ts

@@ -26,7 +26,8 @@ export interface PromptContributionContext {
 	/** The tools this turn may call, if the turn was narrowed. */
 	readonly allowedTools?: readonly string[]
 	/**
-	 * Which iteration this is, 1-based — present only for `turn`.
+	 * Which iteration this is, 1-based — present only for `turn` and
+	 * `context`.
 	 *
 	 * Absent for `static` and `dynamic`, and that absence is the type
 	 * saying what the placement means: a contribution that needs to know
@@ -50,9 +51,9 @@ export interface PromptContributionContext {
  * hits — or, worse, gets served the first turn's text forever.
  *
  * The rule: `static` iff the output depends only on things that cannot
- * change inside one run.
+ * change inside one turn.
  */
-export type PromptPlacement = 'static' | 'dynamic' | 'turn'
+export type PromptPlacement = 'static' | 'dynamic' | 'turn' | 'context'
 
 /**
  * `turn` is a third thing, not a looser `dynamic`.
@@ -62,10 +63,10 @@ export type PromptPlacement = 'static' | 'dynamic' | 'turn'
  * the provider across turns. `turn` is not in the system prompt at all. It
  * rides the ephemeral trailing message that a step's guidance, its skills
  * and the approval-policy notice already use: appended to the request,
- * never pushed onto the run's history, and gone the moment the request is
+ * never pushed onto the turn's history, and gone the moment the request is
  * sent.
  *
- * That is the placement for state that changes DURING a run — a budget
+ * That is the placement for state that changes DURING a turn — a budget
  * running down, a queue draining, a policy that just moved. Putting such a
  * thing in `static` serves the first iteration's value forever; putting it
  * in `dynamic` re-sends it in a position the model reads as part of its
@@ -77,6 +78,27 @@ export type PromptPlacement = 'static' | 'dynamic' | 'turn'
  * when something actually changed, and `null` on every other turn.
  */
 
+/**
+ * `context` is `turn` without the system authority.
+ *
+ * Rendered on every iteration exactly as `turn` is, but delivered through
+ * the request-only context channel rather than as a system message: a
+ * runtime-context user message of kind `step-context`, after the history,
+ * the same channel `PrepareStepResult.context` and the kernel's working
+ * memory use. Never pushed onto the turn's history.
+ *
+ * The difference is where a driver puts it. A driver may hoist every
+ * system message ahead of the conversation — some render tools, then
+ * system, then messages — so a `turn` section whose text changes
+ * invalidates the cached conversation prefix and the whole history is
+ * re-read at full price. Request-only context stays after the history on
+ * every driver, and a caching driver ends its breakpoint before it.
+ *
+ * Use `context` for an observation — a repository snapshot, a status the
+ * model should read and weigh. Use `turn` for text that must carry the
+ * authority of an instruction.
+ */
+
 export interface PromptContribution {
 	/**
 	 * Stable and unique. Registration refuses a duplicate rather than
@@ -155,7 +177,7 @@ export const SKILLS_CONTRIBUTION_ID = 'namzu.skills'
 /**
  * Skills, as a contribution.
  *
- * `static`, because a run's skill set is fixed for the run — a STEP's
+ * `static`, because a turn's skill set is fixed for the turn — a STEP's
  * skills are a different thing entirely and ride the ephemeral trailing
  * system message, which is what keeps them out of the cached prefix.
  *

package/src/prompt/resident-learning.ts

@@ -76,7 +76,7 @@ export function createResidentStepContext(
 		async execute(input, context) {
 			context.abortSignal?.throwIfAborted()
 			try {
-				if (authorize(context) !== true) throw new Error('Run does not own this admission.')
+				if (authorize(context) !== true) throw new Error('Turn does not own this admission.')
 				const projection = project([input.name])
 				if (!projection.includedSkills.includes(input.name))
 					return {
@@ -92,7 +92,7 @@ export function createResidentStepContext(
 				return {
 					success: false,
 					output: '',
-					error: 'Resident skill access is unavailable for this run.',
+					error: 'Resident skill access is unavailable for this turn.',
 				}
 			}
 		},

package/src/provider/collect-chat-completion.ts

@@ -22,7 +22,7 @@ import { StreamTextAccumulator } from './stream-text.js'
  * - reasoning blocks are bucketed by `index` the same way, because the
  *   assembled message is the thing a caller replays and
  *   {@link ReasoningBlock} is documented as replayed verbatim. This was
- *   missing: `delta.reasoning` was dropped on the floor, so a run collected
+ *   missing: `delta.reasoning` was dropped on the floor, so a response collected
  *   through this helper came back with no reasoning even when the driver had
  *   streamed it — and a vendor that requires the blocks back on the next turn
  *   would then be sent a message that had lost them;
@@ -31,7 +31,7 @@ import { StreamTextAccumulator } from './stream-text.js'
  *   where `message_stop` is occasionally dropped on connection close).
  *
  * The orchestrator does NOT call this helper — it consumes the stream
- * directly so it can emit per-delta `RunEvent`s.
+ * directly so it can emit per-delta `SessionEvent`s.
  */
 export async function collectChatCompletion(
 	stream: AsyncIterable<StreamChunk>,
@@ -50,7 +50,7 @@ export async function collectChatCompletion(
 	}
 
 	const toolBuckets = new Map<number, { id: string; name: string; argsBuf: string }>()
-	// Same bucketing rule the run loop uses (`runtime/query/iteration/
+	// Same bucketing rule the turn loop uses (`runtime/query/iteration/
 	// stream-turn.ts`), so a message assembled here and a message assembled
 	// there carry the same blocks in the same order.
 	const reasoningBuckets = new Map<

package/src/provider/conformance.ts

@@ -1,11 +1,14 @@
-import type {
-	ConformanceDescribe,
-	ConformanceExpect,
-	ConformanceIt,
-} from '../store/run/conformance.js'
+import type { SessionLogConformanceOptions } from '../store/session-log/conformance.js'
 import type { LLMProvider } from '../types/provider/interface.js'
 import type { ProviderRetryConfig } from './retry.js'
 
+/** Shape of the `describe` a runner supplies; the same one every SDK conformance suite takes. */
+type ConformanceDescribe = SessionLogConformanceOptions['describe']
+/** Shape of the `it` a runner supplies. */
+type ConformanceIt = SessionLogConformanceOptions['it']
+/** Shape of the `expect` a runner supplies. */
+type ConformanceExpect = SessionLogConformanceOptions['expect']
+
 /**
  * The driver contract, as a suite every driver package runs.
  *

package/src/provider/errors.ts

@@ -25,7 +25,7 @@
  *    Schema draft 2020-12` the entire time. Scrubbing what looks like a
  *    credential keeps the safety and returns the sentence.
  *  - `retryAfterMs` is DATA. Nothing in this module sleeps, backs off or
- *    retries. A retry loop inside a driver burns the run's wall clock and hides
+ *    retries. A retry loop inside a driver burns the turn's wall clock and hides
  *    the failure from the layer that should decide.
  */
 
@@ -243,7 +243,7 @@ function buildProviderErrorMessage(init: ProviderRequestErrorInit): string {
  *
  * A 400 is otherwise `bad_request`: an overflow is the one 400 a caller can act
  * on automatically (compact and retry), and mistaking a genuine schema error for
- * an overflow would send the run into a pointless compaction loop.
+ * an overflow would send the turn into a pointless compaction loop.
  */
 const OVERFLOW_BODY_PATTERNS: readonly RegExp[] = [
 	/prompt is too long/i,

package/src/provider/fallback.ts

@@ -88,7 +88,7 @@ export interface WithProviderFallbackOptions {
 	 * case. The chunk reaches whoever is iterating the stream, at the moment
 	 * of the swap — that is the operator. This reaches a party that has to
 	 * know AFTER the request is over and may never have iterated the stream at
-	 * all — that is the run record. Two things follow that the chunk alone
+	 * all — that is the turn record. Two things follow that the chunk alone
 	 * cannot give it:
 	 *
 	 *  - the cursor outlives the request, so a swap on the turn at step 3
@@ -97,7 +97,7 @@ export interface WithProviderFallbackOptions {
 	 *    compaction verifier and the forced-final summary both do — drops the
 	 *    `fallback` chunk on the floor, so a swap inside one is invisible to
 	 *    every chunk consumer. (The advisory executor calls its OWN advisor's
-	 *    provider, not the run's, so it is not one of these.)
+	 *    provider, not the turn's, so it is not one of these.)
 	 *
 	 * ## Fired when the replacement is ASKED, not when the cursor moves
 	 *
@@ -142,7 +142,7 @@ export interface WithProviderFallbackOptions {
  *
  * The three entries, and what each of them being here means:
  *
- * - `context_length_exceeded` — the run's own remedy is compaction, which sheds
+ * - `context_length_exceeded` — the turn's own remedy is compaction, which sheds
  *   history and asks again. Falling over instead would carry the same oversized
  *   prompt to a provider that has not been given the chance to fit it. Note the
  *   limit of that reasoning: a chain MAY pair a small window with a larger one,
@@ -184,7 +184,7 @@ const REQUEST_FAULT_CODES: ReadonlySet<string> = new Set([
  * only on the unclassified path (`codeFromStatus`). A driver that classified
  * its own 404 into a `ProviderRequestError` gets `kind: 'bad_request'` from
  * `classifyProviderHttpStatus`, which `KIND_TO_CODE` maps to
- * `invalid_request` — a request fault, so the run would ABORT on a model the
+ * `invalid_request` — a request fault, so the turn would ABORT on a model the
  * next member may well have. The status survives on both paths; the code does
  * not, so the status is what this reads.
  */
@@ -332,12 +332,12 @@ function commonReasoningEffortLevels(
  *
  * ## Capabilities are the head's
  *
- * The getters below are transparent, so a run negotiates tools, vision and
+ * The getters below are transparent, so a turn negotiates tools, vision and
  * documents ONCE against `members[0]` and keeps that answer after a swap. This
  * is a real limitation and it is why the host is expected to refuse a chain
  * whose members disagree before ever building one (`@namzu/cli` does, and only
  * runs a mismatched chain when the operator has said so explicitly). Taking the
- * intersection here instead would cost the primary a capability on every run to
+ * intersection here instead would cost the primary a capability on every turn to
  * guard against a failure that happens rarely. Reasoning effort is the deliberate
  * exception: the SAME field is replayed unchanged after a swap, so only a common
  * level can be truthfully offered before the request.
@@ -414,7 +414,7 @@ export function withProviderFallback(
 			} catch (err) {
 				// A Stop is control flow, not a provider failure. Without this the
 				// classifier — which has no concept of cancellation — would file an
-				// abort as some ordinary failure and the run would walk the entire
+				// abort as some ordinary failure and the turn would walk the entire
 				// chain re-issuing an already-cancelled request, one member at a
 				// time, instead of settling as `cancelled`. The retry decorator
 				// guards the same way and for the same reason.
@@ -471,7 +471,7 @@ export function withProviderFallback(
 	}
 
 	// Transparent to capability negotiation and identity, like the retry
-	// decorator. The head's declarations are what a run is configured from; see
+	// decorator. The head's declarations are what a turn is configured from; see
 	// the note on capabilities above for the limitation that carries.
 	return {
 		get id() {