@namzu/sdk 42.0.2 → 44.0.0

package/src/types/agent/supervisor.ts

@@ -21,16 +21,16 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	agentIds: string[]
 
 	/**
-	 * May this run invoke subagents at all? Defaults to `true`.
+	 * May this turn invoke subagents at all? Defaults to `true`.
 	 *
 	 * `agentIds` answers WHO may be called; this answers WHETHER, and they are
-	 * different questions. A run whose own persona is the single agent on the
+	 * different questions. A turn whose own persona is the single agent on the
 	 * list has a non-empty list and still must not call anyone.
 	 *
 	 * It cannot be derived. Comparing the list against the executing agent
 	 * fails where a host substitutes a specialist's persona into the
 	 * supervisor shell — the two ids differ, so the predicate says "can
-	 * delegate" about a run that cannot. And no predicate over `agentIds`
+	 * delegate" about a turn that cannot. And no predicate over `agentIds`
 	 * could work, because a supervisor whose list holds one specialist and a
 	 * run that IS that specialist are indistinguishable in it. The fact lives
 	 * with the caller, so the caller states it.
@@ -53,8 +53,8 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	/**
 	 * Called when the operator approves a plan.
 	 *
-	 * The hook a host uses to leave plan mode without ending the run — which
-	 * is what the mode's per-run lifetime used to force, discarding the
+	 * The hook a host uses to leave plan mode without ending the turn — which
+	 * is what the mode's per-turn lifetime used to force, discarding the
 	 * in-flight step and the tool-schema context to change one enum.
 	 */
 	onPlanApproved?: () => Promise<void> | void
@@ -131,11 +131,11 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 * Optional human-in-the-loop hook for tool review and run-pause
 	 * decisions. When omitted, the supervisor delegates to drainQuery's
 	 * built-in `autoApproveHandler`, which approves every tool call
-	 * without prompting — the unattended mode, where the run is expected
+	 * without prompting — the unattended mode, where the turn is expected
 	 * to finish without a human at the keyboard.
 	 *
 	 * Hosts that want "Ask before acting" behaviour pass a custom
-	 * handler that surfaces the `tool_review_requested` RunEvent to
+	 * handler that surfaces the `tool_review_requested` SessionEvent to
 	 * the user and resolves the returned promise once the user
 	 * approves, rejects, or modifies the call.
 	 *
@@ -182,9 +182,9 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 
 	/**
 	 * Optional structured-compaction config. When omitted, `query()` never
-	 * builds a `WorkingStateManager` and compaction early-returns — the run
+	 * builds a `WorkingStateManager` and compaction early-returns — the turn
 	 * path is byte-identical to a non-compacting run. Hosts opt in (e.g. with
-	 * a `contextWindowTokens`) to keep a long single run alive instead of
+	 * a `contextWindowTokens`) to keep a long single turn alive instead of
 	 * silently truncating.
 	 */
 	compactionConfig?: CompactionConfig
@@ -202,8 +202,8 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 * capability was always there and only the hop was missing.
 	 *
 	 * **What it buys, exactly.** Structured output is terminal and
-	 * exclusive by policy: `setStructuredOutput` overwrites `Run.result`
-	 * behind a sticky flag and the run ends on the turn that produces it.
+	 * exclusive by policy: `setStructuredOutput` overwrites `Turn.result`
+	 * behind a sticky flag and the turn ends on the turn that produces it.
 	 * So this gives a supervisor a schema-constrained FINAL ANSWER and
 	 * nothing more. It does not shape a delegated child's answer — a child
 	 * carries its own config — it does not run alongside prose, and it is
@@ -211,8 +211,8 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 * the workers sets the schema on the workers.
 	 *
 	 * One consequence a supervisor host in particular should know: the
-	 * answer decides the run, so delegated work still running when it lands
-	 * is walked away from rather than waited for. It is recorded — the run
+	 * answer decides the turn, so delegated work still running when it lands
+	 * is walked away from rather than waited for. It is recorded — the turn
 	 * names it on `abandonedTaskIds` — but it is not delivered. That is the
 	 * same precedence a terminal tool has, stated in the iteration loop.
 	 */

package/src/types/agent/task.ts

@@ -1,10 +1,10 @@
-import type { TokenBudget } from '../../run/token-budget.js'
+import type { SessionTokenBudget } from '../../store/budget/index.js'
 import type { ActorRef } from '../../types/session/actor.js'
 import type { WorkspaceBackendKind } from '../../types/workspace/ref.js'
 import type { ResumeHandler } from '../hitl/index.js'
-import type { RunId, SessionId, TaskId, TenantId } from '../ids/index.js'
+import type { SessionId, TaskId, TenantId, TurnId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
-import type { RunEventListener } from '../run/events.js'
+import type { SessionEventListener } from '../session/events.js'
 import type { ProjectId, TopicId } from '../session/ids.js'
 import type { AgentInput, BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { Agent } from './core.js'
@@ -23,6 +23,33 @@ export function isTerminalAgentTaskState(state: AgentTaskState): boolean {
 	return state === 'completed' || state === 'failed' || state === 'canceled' || state === 'rejected'
 }
 
+/**
+ * Where a child session keeps its state, as its parent chose it.
+ *
+ * `memory`: the parent's session log is in memory and it named no
+ * `SessionPaths`, so the child session runs in memory too.
+ * {@link AgentManager.sendMessage} gives the child a fresh
+ * `InMemorySessionLog` and, when the parent named one, the parent's
+ * `checkpointStore`, so the child writes nothing under `NAMZU_HOME`.
+ *
+ * `disk`: the parent's session is on disk in the layout `paths` (the one it
+ * named, or the default for its working directory under `NAMZU_HOME`). The
+ * child's log goes at `<parent-session-dir>/subagents/<child-id>.jsonl`
+ * beside its `<child-id>.meta.json`, nested under every ancestor.
+ *
+ * A child config that already names a `sessionLog` or `paths` keeps what it
+ * names.
+ */
+export type ChildSessionStorage =
+	| {
+			readonly kind: 'memory'
+			readonly checkpointStore?: import('../../store/checkpoint/index.js').SessionCheckpointStore
+	  }
+	| {
+			readonly kind: 'disk'
+			readonly paths: import('../../session/paths.js').SessionPaths
+	  }
+
 /**
  * Context carried into {@link AgentManager.sendMessage}. `tenantId`,
  * `topicId`, `sessionId`, `projectId`, and `parentActor` are required —
@@ -30,7 +57,11 @@ export function isTerminalAgentTaskState(state: AgentTaskState): boolean {
  * must provide the full scoping set.
  */
 export interface AgentTaskContext {
-	parentRunId: RunId
+	/** The session that is delegating. */
+	parentSessionId: SessionId
+
+	/** The parent turn whose tool call is spawning the child. */
+	parentTurnId: TurnId
 
 	parentAgentId: string
 
@@ -39,7 +70,7 @@ export interface AgentTaskContext {
 	depth: number
 
 	/** Shared authority for this parent and every delegated descendant. */
-	budget: TokenBudget
+	budget: SessionTokenBudget
 
 	factoryOptions?: AgentFactoryOptions
 
@@ -65,10 +96,10 @@ export interface AgentTaskContext {
 	resumeHandler?: ResumeHandler
 
 	/**
-	 * The tool-result screens in force for the parent run, handed down so a
+	 * The tool-result screens in force for the parent session, handed down so a
 	 * delegated child screens its results the same way.
 	 *
-	 * A child is a fresh run with its own executor, so without this it
+	 * A child is a fresh turn with its own executor, so without this it
 	 * installs `DEFAULT_TOOL_RESULT_GUARDRAILS` whatever the parent decided —
 	 * and a host that turned the screens off with `[]` (or substituted a
 	 * `passthroughTools` exemption for a tool it knows) would find the
@@ -79,7 +110,7 @@ export interface AgentTaskContext {
 	 * stamps this onto the child config after the builder runs.
 	 *
 	 * Absent means the parent stated no policy of its own, and the child
-	 * installs the shipped default — which is what every run does when its
+	 * installs the shipped default — which is what every turn does when its
 	 * host configured nothing.
 	 */
 	toolResultGuardrails?: readonly import('../guardrail/index.js').ToolResultGuardrailSpec[]
@@ -101,6 +132,16 @@ export interface AgentTaskContext {
 	 */
 	readonly toolDenies?: readonly string[]
 
+	/**
+	 * Where the parent keeps its turn state, handed to every child it
+	 * delegates to. See {@link ChildSessionStorage}. `SupervisorAgent` sets it
+	 * from its own `sessionLog` and `paths`; a host that builds its own
+	 * context for a `LocalTaskScheduler` beside an in-memory `query()` sets it
+	 * the same way. Absent: children resolve their storage from their own
+	 * config, as before.
+	 */
+	readonly childStorage?: ChildSessionStorage
+
 	/** Isolation boundary. Required per session-hierarchy.md §12.1. */
 	tenantId: TenantId
 
@@ -135,7 +176,7 @@ export interface AgentTaskContext {
 }
 
 /** Budget authority shared by an agent task and its descendants. */
-export type AgentTaskBudget = TokenBudget
+export type AgentTaskBudget = SessionTokenBudget
 
 export interface AgentTask {
 	taskId: TaskId
@@ -153,7 +194,7 @@ export interface AgentTask {
 
 	evictAfter?: number
 
-	runEventListener?: RunEventListener
+	sessionEventListener?: SessionEventListener
 }
 
 /**
@@ -182,9 +223,9 @@ export interface SendMessageOptions {
 	 * Display grouping for the delegated child, carried onto its
 	 * `agent_pending` event so a consumer watching from outside this process
 	 * can group the child the way this caller meant. Reach, not durability:
-	 * that event goes straight to a host's listener and enters no run's log,
+	 * that event goes straight to a host's listener and enters no session log,
 	 * so nothing here is persisted by the kernel. See the `agent_pending`
-	 * variant in `types/run/events.ts` for the full contract.
+	 * variant in `types/session/events.ts` for the full contract.
 	 *
 	 * These fields are display annotations only; they do not create
 	 * dependencies, barriers, or serial execution. The kernel reads none of

package/src/types/agent/working-memory.ts

@@ -1,3 +1,5 @@
+import type { TurnId } from '../ids/index.js'
+
 /**
  * Per-turn context the SDK is allowed to hand a working-memory provider.
  *
@@ -9,9 +11,9 @@
  * the primacy edge; the host OWNS the content and its authority framing.
  */
 export interface WorkingMemoryTurnContext {
-	/** The active run id (opaque). */
-	readonly runId: string
-	/** 1-based iteration counter for this run. */
+	/** The active turn. */
+	readonly turnId: TurnId
+	/** 1-based iteration counter for this turn. */
 	readonly iteration: number
 }
 
@@ -24,6 +26,6 @@ export interface WorkingMemoryTurnContext {
  * is injected (the byte-identical-when-empty property). Async so the host can
  * `stat` the output dir / read the registry each turn. Failure-isolated by the
  * SDK: a throwing/slow provider degrades to "no refresh this turn", never
- * breaks the run.
+ * breaks the turn.
  */
 export type WorkingMemoryProvider = (ctx: WorkingMemoryTurnContext) => string | Promise<string>

package/src/types/bidi/index.ts

@@ -1,10 +1,10 @@
-import type { RunId } from '../ids/index.js'
+import type { SessionId, TurnId } from '../ids/index.js'
 import type { LLMToolSchema } from '../tool/index.js'
 
 /**
  * A conversation with no turn boundary.
  *
- * Every other seam in this kernel is turn-based by construction: a run
+ * Every other seam in this kernel is turn-based by construction: a turn
  * has iterations, an iteration sends a complete message list and reads a
  * stream back, and a checkpoint is taken between two of them. That shape
  * is load-bearing everywhere it appears and it cannot describe a duplex
@@ -98,23 +98,31 @@ export interface BidiProvider {
 }
 
 /** What the loop reports back to whoever is driving it. */
-export type BidiRunEvent =
-	| { readonly type: 'text'; readonly runId: RunId; readonly text: string }
+export type BidiTurnEvent =
+	| {
+			readonly type: 'text'
+			readonly sessionId: SessionId
+			readonly turnId: TurnId
+			readonly text: string
+	  }
 	| {
 			readonly type: 'audio'
-			readonly runId: RunId
+			readonly sessionId: SessionId
+			readonly turnId: TurnId
 			readonly data: string
 			readonly mediaType: string
 	  }
 	| {
 			readonly type: 'tool_started'
-			readonly runId: RunId
+			readonly sessionId: SessionId
+			readonly turnId: TurnId
 			readonly toolUseId: string
 			readonly toolName: string
 	  }
 	| {
 			readonly type: 'tool_completed'
-			readonly runId: RunId
+			readonly sessionId: SessionId
+			readonly turnId: TurnId
 			readonly toolUseId: string
 			readonly toolName: string
 			readonly output: string
@@ -126,11 +134,22 @@ export type BidiRunEvent =
 	 */
 	| {
 			readonly type: 'tool_abandoned'
-			readonly runId: RunId
+			readonly sessionId: SessionId
+			readonly turnId: TurnId
 			readonly toolUseId: string
 			readonly toolName: string
 	  }
-	| { readonly type: 'turn_complete'; readonly runId: RunId }
-	| { readonly type: 'interrupted'; readonly runId: RunId }
-	| { readonly type: 'error'; readonly runId: RunId; readonly message: string }
-	| { readonly type: 'closed'; readonly runId: RunId; readonly reason?: string }
+	| { readonly type: 'turn_complete'; readonly sessionId: SessionId; readonly turnId: TurnId }
+	| { readonly type: 'interrupted'; readonly sessionId: SessionId; readonly turnId: TurnId }
+	| {
+			readonly type: 'error'
+			readonly sessionId: SessionId
+			readonly turnId: TurnId
+			readonly message: string
+	  }
+	| {
+			readonly type: 'closed'
+			readonly sessionId: SessionId
+			readonly turnId: TurnId
+			readonly reason?: string
+	  }

package/src/types/bus/index.ts

@@ -1,4 +1,4 @@
-import type { CredentialId, LockId, RunId, SandboxId, TenantId } from '../ids/index.js'
+import type { CredentialId, LockId, SandboxId, SessionId, TenantId, TurnId } from '../ids/index.js'
 
 export type { LockId } from '../ids/index.js'
 
@@ -8,7 +8,7 @@ export type CircuitBreakerState = 'closed' | 'open' | 'half_open'
 
 export interface CircuitBreakerSnapshot {
 	readonly state: CircuitBreakerState
-	readonly agentRunId: RunId
+	readonly agentSessionId: SessionId
 	readonly consecutiveFailures: number
 	readonly lastFailureAt?: number
 	readonly lastSuccessAt?: number
@@ -18,7 +18,7 @@ export interface CircuitBreakerSnapshot {
 export interface FileLock {
 	readonly lockId: LockId
 	readonly filePath: string
-	readonly owner: RunId
+	readonly owner: SessionId
 	readonly acquiredAt: number
 	readonly expiresAt?: number
 }
@@ -27,21 +27,21 @@ export type LockAcquireResult =
 	| { acquired: true; lock: FileLock }
 	// `holder` is OPTIONAL, and its absence is the honest answer to "who holds
 	// it". The failure branch is also reached when the lock was released
-	// between the attempt and the read, and this used to report `'' as RunId`
+	// between the attempt and the read, and this used to report `'' as SessionId`
 	// for that — an empty string wearing an id type, which the nominal ids of
 	// NZ-SURF-11 will not express and which no caller could have distinguished
 	// from a real holder anyway.
-	| { acquired: false; holder?: RunId; filePath: string }
+	| { acquired: false; holder?: SessionId; filePath: string }
 
 export interface FileOwnership {
 	readonly filePath: string
-	readonly owner: RunId
+	readonly owner: SessionId
 	readonly claimedAt: number
 }
 
 export type OwnershipClaimResult =
 	| { claimed: true; ownership: FileOwnership }
-	| { claimed: false; currentOwner: RunId; filePath: string }
+	| { claimed: false; currentOwner: SessionId; filePath: string }
 
 export interface ProviderCallUsage {
 	readonly inputTokens?: number
@@ -53,32 +53,34 @@ export interface ProviderCallUsage {
 export type SandboxDecisionAction = 'allow' | 'deny'
 
 export type AgentBusEvent =
-	| { type: 'lock_acquired'; lockId: LockId; filePath: string; owner: RunId }
-	| { type: 'lock_released'; lockId: LockId; filePath: string; owner: RunId }
-	| { type: 'lock_denied'; filePath: string; requester: RunId; holder: RunId }
-	| { type: 'lock_expired'; lockId: LockId; filePath: string; owner: RunId }
-	| { type: 'ownership_claimed'; filePath: string; owner: RunId }
-	| { type: 'ownership_released'; filePath: string; previousOwner: RunId }
-	| { type: 'ownership_transferred'; filePath: string; from: RunId; to: RunId }
-	| { type: 'ownership_denied'; filePath: string; requester: RunId; currentOwner: RunId }
-	| { type: 'breaker_tripped'; agentRunId: RunId; consecutiveFailures: number }
-	| { type: 'breaker_reset'; agentRunId: RunId }
-	| { type: 'breaker_half_open'; agentRunId: RunId }
-	| { type: 'breaker_probe_success'; agentRunId: RunId }
-	| { type: 'breaker_probe_failure'; agentRunId: RunId }
+	| { type: 'lock_acquired'; lockId: LockId; filePath: string; owner: SessionId }
+	| { type: 'lock_released'; lockId: LockId; filePath: string; owner: SessionId }
+	| { type: 'lock_denied'; filePath: string; requester: SessionId; holder: SessionId }
+	| { type: 'lock_expired'; lockId: LockId; filePath: string; owner: SessionId }
+	| { type: 'ownership_claimed'; filePath: string; owner: SessionId }
+	| { type: 'ownership_released'; filePath: string; previousOwner: SessionId }
+	| { type: 'ownership_transferred'; filePath: string; from: SessionId; to: SessionId }
+	| { type: 'ownership_denied'; filePath: string; requester: SessionId; currentOwner: SessionId }
+	| { type: 'breaker_tripped'; agentSessionId: SessionId; consecutiveFailures: number }
+	| { type: 'breaker_reset'; agentSessionId: SessionId }
+	| { type: 'breaker_half_open'; agentSessionId: SessionId }
+	| { type: 'breaker_probe_success'; agentSessionId: SessionId }
+	| { type: 'breaker_probe_failure'; agentSessionId: SessionId }
 	| {
 			type: 'provider_call_start'
 			providerId: string
 			model: string
 			callId: ProviderCallId
-			runId?: RunId
+			sessionId?: SessionId
+			turnId?: TurnId
 	  }
 	| {
 			type: 'provider_call_completed'
 			providerId: string
 			model: string
 			callId: ProviderCallId
-			runId?: RunId
+			sessionId?: SessionId
+			turnId?: TurnId
 			durationMs: number
 			usage?: ProviderCallUsage
 	  }
@@ -87,7 +89,8 @@ export type AgentBusEvent =
 			providerId: string
 			model: string
 			callId: ProviderCallId
-			runId?: RunId
+			sessionId?: SessionId
+			turnId?: TurnId
 			durationMs: number
 			error: string
 	  }
@@ -112,7 +115,8 @@ export type AgentBusEvent =
 			source: string
 			ref: string
 			tenantId?: TenantId
-			runId?: RunId
+			sessionId?: SessionId
+			turnId?: TurnId
 	  }
 	| {
 			type: 'vault_lookup'
@@ -120,7 +124,8 @@ export type AgentBusEvent =
 			credentialId?: CredentialId
 			tenantId?: TenantId
 			found: boolean
-			runId?: RunId
+			sessionId?: SessionId
+			turnId?: TurnId
 	  }
 	| {
 			type: 'sandbox_decision'
@@ -128,7 +133,8 @@ export type AgentBusEvent =
 			action: SandboxDecisionAction
 			resource: string
 			ruleId?: string
-			runId?: RunId
+			sessionId?: SessionId
+			turnId?: TurnId
 	  }
 
 export type AgentBusEventListener = (event: AgentBusEvent) => void

package/src/types/code-navigation/index.ts

@@ -93,7 +93,7 @@ export interface CodeNavigationProvider {
 	 * Stop whatever backs it.
 	 *
 	 * Not optional. An implementation spawns a process, and a provider that
-	 * could not be told to stop leaves one behind per run.
+	 * could not be told to stop leaves one behind per turn.
 	 */
 	dispose(): Promise<void>
 }

package/src/types/common/index.ts

@@ -1,21 +1,7 @@
-/**
- * The lifecycle of one RUN.
- *
- * Named for what it types. Every one of its uses in this package is a
- * run's status, a run's audit outcome, or the status field of a run's
- * result -- none of them describe an `AbstractAgent` or a
- * `ReactiveAgent`, which have no status of their own. The old name sent a
- * reader looking for an agent's lifecycle to the type that governs a run.
- */
-export type RunExecutionStatus =
-	| 'idle'
-	| 'pending'
-	| 'running'
-	| 'completed'
-	| 'failed'
-	| 'cancelled'
+import type { TurnExecutionStatus } from '../session/turn.js'
 
-export function isTerminalStatus(status: RunExecutionStatus): boolean {
+/** Whether a turn's execution status is settled: `completed`, `failed` or `cancelled`. */
+export function isTerminalStatus(status: TurnExecutionStatus): boolean {
 	return status === 'completed' || status === 'failed' || status === 'cancelled'
 }
 
@@ -49,7 +35,7 @@ export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage):
 		cacheWriteTokens: current.cacheWriteTokens + addition.cacheWriteTokens,
 		// Summed only when at least one side reported it. Coercing absent to
 		// zero would turn 'this driver does not tell us' into 'it spent none',
-		// and a run mixing a reporting driver with a silent one would read as
+		// and a turn mixing a reporting driver with a silent one would read as
 		// though the silent turns did no thinking.
 		...(current.reasoningTokens !== undefined || addition.reasoningTokens !== undefined
 			? { reasoningTokens: (current.reasoningTokens ?? 0) + (addition.reasoningTokens ?? 0) }
@@ -79,7 +65,7 @@ export function mergeTokenUsage(current: TokenUsage, next: TokenUsage): TokenUsa
 		// frame's own total covers only the component that frame carried.
 		// Maxing those two totals returns the larger COMPONENT, not the sum —
 		// 1200 and 350 merge to 1200 instead of 1550, and every completion
-		// token vanishes from the run's budget. Take the max of what was
+		// token vanishes from the turn's budget. Take the max of what was
 		// reported and what the merged components imply, so the result is
 		// monotone and can never under-report.
 		totalTokens: Math.max(current.totalTokens, next.totalTokens, promptTokens + completionTokens),
@@ -97,13 +83,13 @@ export interface CostInfo {
 	 * card describes the whole total.
 	 *
 	 * Absent means "no single rate describes this", not "zero". Three ways to
-	 * get there: nothing has been accumulated yet, the run spanned two
+	 * get there: nothing has been accumulated yet, the turn spanned two
 	 * differently-priced models, or part of it was accumulated at no known rate
 	 * at all. This is the same contract {@link TokenUsage.reasoningTokens} uses
 	 * one field up, for the same reason — a number invented to fill the slot
 	 * would be indistinguishable from a measured one.
 	 *
-	 * The field used to be required, and a run that swapped models reported
+	 * The field used to be required, and a turn that swapped models reported
 	 * whichever card was applied last, which is a claim about the whole total
 	 * that was true of only part of it.
 	 */
@@ -116,19 +102,19 @@ export interface CostInfo {
 	 * Tokens accumulated at no known rate, so `totalCost` does not include what
 	 * they cost.
 	 *
-	 * This exists so a consumer can tell "this run cost nothing" from "nobody
-	 * knows what this run cost". Reporting the second as zero is the defect the
+	 * This exists so a consumer can tell "this turn cost nothing" from "nobody
+	 * knows what this turn cost". Reporting the second as zero is the defect the
 	 * price catalogue was added to fix, one level down: a total that is always
 	 * zero and a total that is zero because it is unknown look identical, and
-	 * `runConfig.costLimitUsd` is enforced against both.
+	 * `turnConfig.costLimitUsd` is enforced against both.
 	 *
-	 * - `totalCost: 0, unpricedTokens: 0` — the run genuinely cost nothing
+	 * - `totalCost: 0, unpricedTokens: 0` — the turn genuinely cost nothing
 	 *   (local inference bills per token exactly never).
 	 * - `totalCost: 0, unpricedTokens: 4210` — nobody knows.
 	 * - `totalCost: 0.12, unpricedTokens: 900` — partly known; the total is a
 	 *   floor, not the answer.
 	 *
-	 * A count rather than a flag because a run mixes turns: a step can name its
+	 * A count rather than a flag because a turn mixes turns: a step can name its
 	 * own model and a provider chain can swap members mid-run.
 	 */
 	unpricedTokens: number

package/src/types/connector/core.ts

@@ -38,7 +38,7 @@ export interface ConnectorMethod<TInput = unknown, TOutput = unknown> {
 
 /**
  * **Declared, not implemented.** Nothing reads a trigger and nothing emits
- * a {@link ConnectorEvent}; no inbound event starts a run today.
+ * a {@link ConnectorEvent}; no inbound event starts a turn today.
  *
  * Said here rather than left to be discovered, because a connector author
  * who declares triggers gets no error and no events — the worst combination
@@ -75,7 +75,7 @@ export interface ConnectorTrigger {
 /**
  * @deprecated The SDK does not emit inbound connector events. Define the
  * event envelope at the host boundary that owns subscription, de-duplication,
- * delivery, and run admission.
+ * delivery, and turn admission.
  */
 export interface ConnectorEvent {
 	connectorId: ConnectorId

package/src/types/connector/definition.ts

@@ -29,7 +29,7 @@ export interface ConnectorDefinition<TConfig = unknown> {
 	/**
 	 * Declared, not implemented — see {@link ConnectorTrigger}.
 	 *
-	 * @deprecated The SDK never reads this field or starts a run from it. Move
+	 * @deprecated The SDK never reads this field or starts a turn from it. Move
 	 * subscription metadata into a host-owned store before the next major.
 	 * It remains readable through `ConnectorRegistry` during this migration
 	 * release so existing host dispatchers do not break without warning.

package/src/types/connector/mcp.ts

@@ -424,7 +424,7 @@ export interface MCPClientConfig {
 	 * `DEFAULT_MCP_REQUEST_TIMEOUT_MS`.
 	 *
 	 * Without one, a wedged stdio server left every caller pending
-	 * forever — no error, no failure, just a run that stopped.
+	 * forever — no error, no failure, just a turn that stopped.
 	 */
 	requestTimeoutMs?: number
 	/**

package/src/types/errors/catalog.ts

@@ -150,13 +150,13 @@ export const DEFAULT_ERROR_RULES: readonly ErrorCatalogRule[] = [
 	{
 		id: 'provider.auth',
 		when: (facts) => facts.code === 'auth' || facts.status === 401,
-		message: 'The provider rejected the credentials for this run.',
+		message: 'The provider rejected the credentials for this turn.',
 		hint: 'Check that the API key is set, is not expired, and belongs to the account the model is billed to. Retrying will not help until it changes.',
 	},
 	{
 		id: 'provider.rate_limit',
 		when: (facts) => facts.code === 'rate_limit' || facts.status === 429,
-		message: 'The provider is rate limiting this run.',
+		message: 'The provider is rate limiting this turn.',
 		hint: 'Respect the provider retry delay when reported. Lower concurrency, or wait for the quota window to reset before resuming.',
 	},
 	{
@@ -172,7 +172,7 @@ export const DEFAULT_ERROR_RULES: readonly ErrorCatalogRule[] = [
 			facts.code === 'overloaded' ||
 			(facts.status !== undefined && facts.status >= 500),
 		message: 'The provider is failing on its own side.',
-		hint: 'Nothing in the run is wrong. Resume from the last checkpoint once the provider recovers.',
+		hint: 'Nothing in the turn is wrong. Resume from the last checkpoint once the provider recovers.',
 	},
 	{
 		id: 'provider.network',
@@ -184,7 +184,7 @@ export const DEFAULT_ERROR_RULES: readonly ErrorCatalogRule[] = [
 		id: 'provider.model_not_found',
 		when: (facts) => facts.code === 'not_found' || facts.status === 404,
 		message: 'The provider does not recognise the model or endpoint requested.',
-		hint: "Check `runConfig.model` against the provider's current model list — a model id that was valid can be retired, and a deployment-scoped provider needs the deployment name rather than the base model name.",
+		hint: "Check `turnConfig.model` against the provider's current model list — a model id that was valid can be retired, and a deployment-scoped provider needs the deployment name rather than the base model name.",
 	},
 	{
 		id: 'provider.content_filter',

package/src/types/errors/index.ts

@@ -7,7 +7,7 @@ import { ProviderError, classifyProviderError } from '../provider/errors.js'
  * `PlatformError` was declared and never constructed — a shape nothing
  * produced and nothing consumed. Meanwhile the runtime threw bare `Error`
  * everywhere, so a caller catching a failure from `query()` could not tell
- * "the model rate-limited us" from "the run was configured wrong" from
+ * "the model rate-limited us" from "the turn was configured wrong" from
  * "that checkpoint does not exist". The only recourse was matching on
  * message text, which is not an interface.
  *
@@ -18,19 +18,19 @@ import { ProviderError, classifyProviderError } from '../provider/errors.js'
  * host's.
  */
 export type NamzuErrorCode =
-	/** The run was set up wrong — missing model, contradictory options. Retrying cannot help. */
+	/** The turn was set up wrong — missing model, contradictory options. Retrying cannot help. */
 	| 'invalid_config'
 	/** The upstream model call failed. `details.providerCode` narrows it. */
 	| 'provider_error'
 	/** A tool could not be executed or resolved. */
 	| 'tool_error'
-	/** A referenced checkpoint, run or emergency dump does not exist. */
+	/** A referenced checkpoint, session or turn does not exist. */
 	| 'not_found'
 	/** A plugin hook failed or refused. */
 	| 'plugin_error'
-	/** The provider or environment cannot do what the run requires. */
+	/** The provider or environment cannot do what the turn requires. */
 	| 'capability_unavailable'
-	/** Persistence (checkpoint store, run store, workspace) failed. */
+	/** Persistence (checkpoint store, session log, workspace) failed. */
 	| 'storage_error'
 	/** Unclassified. Treated as non-retryable. */
 	| 'unknown'