@namzu/sdk 42.0.2 → 44.0.0

package/src/public-tools.ts

@@ -15,7 +15,14 @@ export { defineTool } from './tools/defineTool.js'
 // Containment, for a host or sibling package that resolves caller-supplied
 // paths against a root. Both were internal while three call sites outside
 // this file needed them.
-export { isWithin, resolveWithin, resolveWithinReal } from './tools/paths.js'
+export {
+	OUTSIDE_ROOTS_GUIDANCE,
+	isWithin,
+	pathOutsideRoots,
+	resolveWithin,
+	resolveWithinReal,
+	toolRoots,
+} from './tools/paths.js'
 // A host that surfaces its own untrusted content to a model needs the same
 // framing the kernel applies to connector prompts and delegated results — and
 // the reader for it, because a screen that judges a result has to reach past
@@ -40,7 +47,7 @@ export { builtinCommandArguments, commandArgumentOf } from './tools/command-argu
 export { ReadFileTool } from './tools/builtins/read-file.js'
 export { WriteFileTool } from './tools/builtins/write-file.js'
 export { EditTool } from './tools/builtins/edit.js'
-export { BashTool } from './tools/builtins/bash.js'
+export { BashTool, SANDBOX_ESCAPE_NOT_APPROVED } from './tools/builtins/bash.js'
 export { LSP_TOOL_NAME, LspTool, getCodeNavigationTools } from './tools/builtins/lsp.js'
 export { GlobTool } from './tools/builtins/glob.js'
 export { GrepTool } from './tools/builtins/grep.js'
@@ -55,12 +62,12 @@ export { JobTool } from './tools/builtins/job.js'
 // the same unbacked suggestion `job` itself exists to fix.
 export { WaitForJobTool } from './tools/builtins/wait-for-job.js'
 // Loads a skill's instructions, and adopts the tool scope it declares.
-// NOT in the default builtin set: a run with no skills has nothing for it
+// NOT in the default builtin set: a turn with no skills has nothing for it
 // to do, and offering a tool that can only refuse is worse than not
 // offering it. Hosts register it alongside a skills registry.
 export { SKILL_TOOL_NAME, SkillTool, parseAllowedTools } from './tools/builtins/skill.js'
 // Both declare `category: 'network'`, which is what the authorization
-// presets branch on. NOT in the default builtin set: a run with no web
+// presets branch on. NOT in the default builtin set: a turn with no web
 // provider has nothing for them to do, and only the `unattended` preset --
 // the one requiring the sandbox to confine the network -- auto-approves
 // them.
@@ -72,14 +79,14 @@ export {
 } from './tools/builtins/web.js'
 // The paragraph neither tool owns: how to use the two together, and what a
 // fetched page is. Registered with the prompt contribution registry only
-// when the tools are — guidance about tools a run does not have spends the
+// when the tools are — guidance about tools a turn does not have spends the
 // cached prefix telling the model to cite a search it cannot run.
 export {
 	WEB_GUIDANCE_CONTRIBUTION_ID,
 	webGuidanceContribution,
 } from './tools/builtins/web-guidance.js'
-// A program the model wrote, calling this run's own tools in a loop. Opt-in
-// and NOT in the default builtin set: a run that does not need
+// A program the model wrote, calling this turn's own tools in a loop. Opt-in
+// and NOT in the default builtin set: a turn that does not need
 // model-authored control flow should not have a way to execute
 // model-authored text, and "the tool was there so it got used" is not a
 // threat model.

package/src/public-types.ts

@@ -40,7 +40,6 @@ export type {
 } from './directory/derive-supervisor.js'
 export type * from './types/toolset/index.js'
 export type * from './types/permission/index.js'
-export type * from './types/run/index.js'
 export type * from './types/errors/index.js'
 export type * from './types/provider/index.js'
 export type * from './types/agent/index.js'
@@ -70,11 +69,15 @@ export type * from './types/doctor/index.js'
 export type * from './types/workspace/index.js'
 export type * from './types/goal/index.js'
 
-// Session-hierarchy type surface (ses_010 moved entities here).
+// The session → turn → message surface: sessions, turns, their events,
+// records, checkpoints and durable state. The only definition of a turn.
 export type * from './types/session/index.js'
 
 // ─── wire surface (contracts/) ────────────────────────────────────────────
 
+// Turn and session wire shapes (WireTurn, WireTurnStatus, CreateTurnRequest,
+// CreateEphemeralSessionRequest, SessionStreamEvent, …) come through
+// `export * from './contracts/session/index.js'` in public-runtime.ts.
 export type {
 	AgentDefaults,
 	AgentInfo,
@@ -82,20 +85,11 @@ export type {
 	ApiErrorType,
 	ApiPermissionMode,
 	CreateMessageRequest,
-	CreateRunRequest,
-	CreateStatelessRunRequest,
 	ISOTimestamp,
 	PaginatedResponse,
 	PaginationParams,
-	RunConfig,
-	RunHierarchyNode,
-	RunStopReason,
-	RunUsage,
-	StreamEvent,
-	StreamEventType,
+	SessionTreeNode,
 	ToolCallInfo,
-	WireRun,
-	WireRunStatus,
 } from './contracts/api.js'
 
 // ─── runtime-config type shapes ───────────────────────────────────────────
@@ -117,7 +111,7 @@ export type {
 
 export type { CacheRates, ModelPricing } from './utils/cost.js'
 export type { VendorRates } from './pricing/index.js'
-export type { PricingSubject } from './manager/run/persistence.js'
+export type { PricingSubject } from './manager/session/turn-recorder.js'
 export type {
 	FrontmatterValue,
 	ParsedFrontmatter,
@@ -151,8 +145,8 @@ export type {
 export type {
 	LimitCheckResult,
 	LimitCheckerState,
-	RunReporter,
-} from './run/index.js'
+	TurnReporter,
+} from './turn/index.js'
 
 export type {
 	AgentIdentity,
@@ -168,6 +162,10 @@ export type {
 	DiskMemoryStoreConfig,
 	DiskTaskStoreConfig,
 	Identifiable,
+	MarkdownMemoryStoreConfig,
+	MemoryContentRejection,
+	MemoryImportOutcome,
+	RenderedMemoryIndex,
 	Timestamped,
 } from './store/index.js'
 
@@ -210,9 +208,8 @@ export type {
 } from './tools/coordinator/index.js'
 
 export type {
-	PathBuilder,
-	RegisterSharedRunPlanInput,
-	SharedRunWorkspaceConfig,
+	RegisterSharedSessionPlanInput,
+	SharedSessionWorkspaceConfig,
 } from './session/workspace/index.js'
 
 export type {
@@ -235,7 +232,22 @@ export type {
 	ConnectorToolStrategy,
 } from './connector/tools/index.js'
 
-export type { CreateRunFromA2A } from './bridge/a2a/index.js'
+export type {
+	A2AContextResolution,
+	CreateTurnFromA2A,
+	MapTurnToA2ATaskOptions,
+} from './bridge/a2a/index.js'
+export type {
+	ExternalSessionLookup,
+	ExternalSessionResolution,
+	ResolveExternalSessionOptions,
+} from './bridge/external-session.js'
+
+export type { CheckpointRecords, RecordedPark } from './runtime/query/checkpoint.js'
+
+export type { TaskContextScope } from './store/task/context.js'
+
+export type { TaskToolScope } from './tools/task/index.js'
 
 export type { MappedStreamEvent } from './bridge/sse/index.js'
 
@@ -338,13 +350,13 @@ export type {
 	ResolvedCredential,
 } from './vault/CredentialProvider.js'
 
-// Who answers when a run asks a human, as a value rather than a closure
+// Who answers when a turn asks a human, as a value rather than a closure
 // captured at `query()` start. See `types/hitl/policy.ts`.
 export type {
 	ApprovalPolicy,
 	ApprovalPolicyChange,
 	ApprovalPolicyChangedEvent,
-	RunApprovalPolicy,
+	SessionApprovalPolicy,
 } from './types/hitl/policy.js'
 
 export type {
@@ -406,15 +418,15 @@ export type {
 
 export type {
 	ReadModel,
-	RunStatusReadModelOptions,
-	RunStatusState,
+	SessionStatusReadModelOptions,
+	SessionStatusState,
 } from './read-model/index.js'
 
 export type {
-	RunQueryOptions,
-	RunTranscriptUnavailableReason,
+	SessionQueryOptions,
+	SessionTranscriptUnavailableReason,
 	ShedPass,
-} from './run-query/index.js'
+} from './session-query/index.js'
 
 export type {
 	OpenTerminalOptions,
@@ -428,22 +440,8 @@ export type {
 // Existing Topic snapshots can initialize an in-memory delegation store.
 export type { Topic, TopicStatus } from './types/topic/entity.js'
 
-export type {
-	TokenBudgetAccountSnapshot,
-	TokenBudgetRequestSnapshot,
-	TokenBudgetSnapshot,
-	TokenBudgetSummary,
-	TokenBudgetPersistence,
-} from './run/token-budget.js'
-export type {
-	TokenBudgetStore,
-	TokenBudgetScope,
-	TokenBudgetBinding,
-} from './types/run/token-budget-store.js'
-export type {
-	DiskTokenBudgetStoreConfig,
-	OpenTokenBudgetOptions,
-} from './store/run/token-budget-disk.js'
+// Token ledgers (SessionTokenBudget*, keyed by rootSessionId + rootTurnId)
+// come through `export * from './store/budget/index.js'` in public-runtime.ts.
 
 export type {
 	RequestContextPart,
@@ -556,22 +554,20 @@ export type {
 	ResidentArchiveListOptions,
 } from './manager/resident/agenda.js'
 
-export type { SqliteSessionStoreConfig } from './store/session/sqlite.js'
-
-export type {
-	RunEvidenceScope,
-	DiskRunEvidenceOptions,
-	RunEvidenceSearchOptions,
-	RunEvidenceMatch,
-	RunEvidenceSearchResult,
-	RunEvidenceReadOptions,
-	RunEvidenceReadResult,
-	RunEvidenceSource,
-	RunTextEvidenceSearchOptions,
-	RunTextEvidenceMatch,
-	RunTextEvidenceSearchResult,
-	RunTextEvidenceReadResult,
-	RunTextEvidenceSource,
+export type {
+	SessionEvidenceScope,
+	SessionEvidenceSourceOptions,
+	SessionEvidenceSearchOptions,
+	SessionEvidenceMatch,
+	SessionEvidenceSearchResult,
+	SessionEvidenceReadOptions,
+	SessionEvidenceReadResult,
+	SessionEvidenceSource,
+	SessionTextEvidenceSearchOptions,
+	SessionTextEvidenceMatch,
+	SessionTextEvidenceSearchResult,
+	SessionTextEvidenceReadResult,
+	SessionTextEvidenceSource,
 } from './store/evidence/types.js'
 export type { EvidenceRecordKind } from './store/evidence/source-kind.js'
 export type {
@@ -595,7 +591,7 @@ export type {
 	JsonClaimVerdict,
 	JsonClaimVerifierOptions,
 	JsonClaimVerifier,
-} from './run/json-claim-verifier.js'
+} from './turn/json-claim-verifier.js'
 
 export type {
 	SqliteResidentLearningStoreOptions,
@@ -610,3 +606,19 @@ export type {
 	ResidentLearningObservationRecord,
 	ResidentLearningTarget,
 } from './manager/resident/learning-observation.js'
+
+// ─── sessions, turns and the session log: paths and log lines ────────────
+// The session types themselves come through `./types/session/index.js` above.
+
+export type { ResolveNamzuHomeOptions } from './session/home.js'
+export type {
+	EnsureProjectOptions,
+	EnsuredProject,
+	SessionLocator,
+	SessionPathsOptions,
+	TempRootOptions,
+} from './session/paths.js'
+export type {
+	ParsedSessionLogLine,
+	SessionLogLineFault,
+} from './session/log-hash.js'

package/src/rag/embedding.ts

@@ -116,7 +116,7 @@ export class HttpEmbeddingProvider implements EmbeddingProvider {
 			const reason = callerSignal?.reason
 			// Settle the public operation with the caller's exact reason before
 			// aborting fetch: transports commonly turn every abort into a generic
-			// DOMException, which would erase who stopped the run.
+			// DOMException, which would erase who stopped the turn.
 			rejectCallerAbort?.(reason)
 			if (!transport.signal.aborted) transport.abort(reason)
 		}

package/src/read-model/index.ts

@@ -10,5 +10,5 @@ export {
 	UnknownReadModelError,
 } from './registry.js'
 export type { ReadModel } from './registry.js'
-export { RUN_STATUS_READ_MODEL_ID, createRunStatusReadModel } from './run-status.js'
-export type { RunStatusReadModelOptions, RunStatusState } from './run-status.js'
+export { SESSION_STATUS_READ_MODEL_ID, createSessionStatusReadModel } from './session-status.js'
+export type { SessionStatusReadModelOptions, SessionStatusState } from './session-status.js'

package/src/read-model/registry.ts

@@ -1,13 +1,13 @@
-import type { PersistedRunEvent } from '../types/run/index.js'
+import type { SessionRecord } from '../types/session/index.js'
 
 /**
- * A derived value maintained incrementally from the run's event log.
+ * A derived value maintained incrementally from the turn's event log.
  *
- * Everything derived from a run was computed by scanning what was in hand
- * at the moment somebody asked — `deriveRunStatus` takes a status and a
- * park and answers about that instant. That works while the whole run fits
+ * Everything derived from a turn was computed by scanning what was in hand
+ * at the moment somebody asked — `deriveTurnStatus` takes a status and a
+ * park and answers about that instant. That works while the whole turn fits
  * in memory and stops working the moment it does not: a caller wanting the
- * status of a run whose history has been compacted, or of a run in another
+ * status of a turn whose history has been compacted, or of a turn in another
  * process, has to load the log and fold it, and every caller folds it
  * slightly differently.
  *
@@ -31,7 +31,7 @@ export interface ReadModel<TState> {
 	 * and cheap; the registry does not compare, and a model that allocated
 	 * a fresh state per event would still be correct, only wasteful.
 	 */
-	apply(state: TState, event: PersistedRunEvent): TState
+	apply(state: TState, event: SessionRecord): TState
 }
 
 /** An event the registry has already folded in. */
@@ -81,9 +81,9 @@ export class ReadModelCollisionError extends Error {
 }
 
 /**
- * Every projection of one run, advanced together.
+ * Every projection of one turn, advanced together.
  *
- * Together, and that is the design: a registry per run rather than per
+ * Together, and that is the design: a registry per turn rather than per
  * model, so `lastSeq` is one number and a caller reading two projections
  * cannot be handed states derived from different prefixes of the same log.
  */
@@ -113,7 +113,7 @@ export class ReadModelRegistry {
 	 * rebuilds with {@link replay} instead, which is honest about starting
 	 * over.
 	 */
-	apply(event: PersistedRunEvent): void {
+	apply(event: SessionRecord): void {
 		if (event.seq <= this.seq) {
 			throw new DuplicateEventError({ seq: event.seq, lastSeq: this.seq })
 		}
@@ -134,7 +134,7 @@ export class ReadModelRegistry {
 	 * correct answer by paying for the whole log rather than a plausible one
 	 * by pretending it did not miss anything.
 	 */
-	replay(events: readonly PersistedRunEvent[]): void {
+	replay(events: readonly SessionRecord[]): void {
 		for (const [id, model] of this.models) this.states.set(id, model.initial())
 		this.seq = 0
 		for (const event of events) this.apply(event)

package/src/read-model/session-status.ts

@@ -0,0 +1,87 @@
+import type { HITLDecisionRequest, PendingDecision } from '../types/hitl/index.js'
+import { deriveTurnStatus } from '../types/session/derive-status.js'
+import type { TurnExecutionStatus, TurnStatus } from '../types/session/index.js'
+import type { ReadModel } from './registry.js'
+
+/**
+ * A session's status, maintained from its own log.
+ *
+ * `deriveTurnStatus` answers about an instant: hand it a status and a park
+ * and it projects them. This derives both from the session log's records —
+ * the turn lifecycle and the `decision_*` records — so the projection needs
+ * the log and nothing else, in this process or another.
+ *
+ * The instant-projector is still what answers; this only feeds it, so the
+ * rule for `awaiting_hitl_resolution` has one implementation.
+ */
+
+export const SESSION_STATUS_READ_MODEL_ID = 'namzu.session.status'
+
+export interface SessionStatusState {
+	/** The execution status of the session's latest turn (`idle` before any). */
+	readonly execution: TurnExecutionStatus
+	/** The outstanding park, if the log says there is one. */
+	readonly park?: PendingDecision
+	/** `deriveTurnStatus` at the moment the last record was folded in. */
+	readonly status: TurnStatus
+}
+
+/**
+ * `now` is injected: `awaiting_hitl` becomes `awaiting_hitl_resolution` when
+ * a deadline passes, and a deadline passes without any record being
+ * appended. The state a fold holds is the status as of the last record; a
+ * caller that needs the answer right now re-projects with its own clock.
+ */
+export interface SessionStatusReadModelOptions {
+	readonly now?: () => number
+}
+
+export function createSessionStatusReadModel(
+	options: SessionStatusReadModelOptions = {},
+): ReadModel<SessionStatusState> {
+	const now = options.now ?? Date.now
+
+	const project = (execution: TurnExecutionStatus, park?: PendingDecision): SessionStatusState => ({
+		execution,
+		...(park ? { park } : {}),
+		status: deriveTurnStatus({ status: execution, ...(park ? { park } : {}), now: now() }),
+	})
+
+	return {
+		id: SESSION_STATUS_READ_MODEL_ID,
+		// `idle`, not `pending`: a session whose log holds no turn has not been
+		// queued by anything this projection saw.
+		initial: () => project('idle'),
+
+		apply(state, record) {
+			switch (record.type) {
+				case 'turn_started':
+					return project('running')
+				case 'turn_completed':
+					return project(record.settlement.status)
+				case 'turn_failed':
+					return project('failed')
+				case 'decision_requested':
+					// A park, as the log records one, with its absolute deadline.
+					return project(state.execution === 'idle' ? 'running' : state.execution, {
+						request: record.request as unknown as HITLDecisionRequest,
+						parkedAt: Date.parse(record.ts),
+						...(record.deadlineAt !== undefined
+							? { deadlineAt: Date.parse(record.deadlineAt) }
+							: {}),
+					})
+				case 'decision_resolved':
+				case 'decision_expired':
+				case 'turn_resuming':
+					// Answered (or ended): dropping the park moves the turn back to
+					// `running` on the answer, not on the turn's next step.
+					return project(state.execution)
+				default:
+					// A pause is not a park: `turn_paused` with no open decision is
+					// a provider wait, and inventing `awaiting_hitl` for it would
+					// report a human as owing an answer nobody asked them for.
+					return state
+			}
+		},
+	}
+}

package/src/registry/command/kernel-commands.ts

@@ -20,7 +20,7 @@ import type { TaskStore } from '../../types/task/index.js'
  * A registry with nothing in it is a declaration, and this repo has a rule
  * about those. These are facts a host would otherwise have to reach into
  * kernel internals to answer: the current Session goal, tracked work,
- * operator-invocable skills, and the agents this run may delegate to. Each is
+ * operator-invocable skills, and the agents this turn may delegate to. Each is
  * computed or owned here and should not acquire a second host-specific source.
  *
  * Deliberately NOT here: anything that would need a decision the kernel
@@ -31,13 +31,13 @@ import type { TaskStore } from '../../types/task/index.js'
  */
 
 export interface KernelCommandOptions {
-	/** Absent is a real state — not every run tracks tasks. */
+	/** Absent is a real state — not every turn tracks tasks. */
 	readonly taskStore?: TaskStore
 	readonly allowedAgentIds?: readonly string[]
 	/**
-	 * The run's skills, for the operator-facing half of the listing.
+	 * The turn's skills, for the operator-facing half of the listing.
 	 *
-	 * Absent is a real state: a run with no skills registry has none, which
+	 * Absent is a real state: a turn with no skills registry has none, which
 	 * is different from having none registered.
 	 */
 	readonly skills?: readonly Skill[]
@@ -265,17 +265,17 @@ export function kernelHostCommands(options: KernelCommandOptions): HostCommandDe
 		},
 		{
 			name: 'tasks',
-			description: 'List the work this run is tracking.',
+			description: 'List the work this turn is tracking.',
 			hint: 'id, status, owner and subject for every task in the store',
 			async handler() {
 				// REFUSED rather than an empty report. "There are no tasks" and
-				// "this run has no task store" are different answers, and a host
+				// "this turn has no task store" are different answers, and a host
 				// that shows the first for the second gives an operator a
 				// confident zero nobody computed.
 				if (!options.taskStore) {
 					return {
 						kind: 'refused',
-						reason: 'This run has no task store, so there is nothing to list.',
+						reason: 'This turn has no task store, so there is nothing to list.',
 					}
 				}
 				const tasks = await options.taskStore.list()
@@ -304,7 +304,7 @@ export function kernelHostCommands(options: KernelCommandOptions): HostCommandDe
 				if (!options.skills) {
 					return {
 						kind: 'refused',
-						reason: 'This run has no skills registry, so there is nothing to list.',
+						reason: 'This turn has no skills registry, so there is nothing to list.',
 					}
 				}
 				return {
@@ -322,12 +322,12 @@ export function kernelHostCommands(options: KernelCommandOptions): HostCommandDe
 		},
 		{
 			name: 'agents',
-			description: 'List the agents this run may delegate to.',
+			description: 'List the agents this turn may delegate to.',
 			hint: 'the roster, as the delegation tools see it',
 			handler() {
 				// An empty roster IS the answer here, unlike the store above: the
 				// question is "who may I call", and "nobody" is a complete and
-				// correct reply that a run with delegation off should get.
+				// correct reply that a turn with delegation off should get.
 				return {
 					kind: 'report',
 					title: 'Agents',

package/src/registry/tool/dialect.ts

@@ -43,7 +43,7 @@ export type JsonSchemaDialect = 'draft-07' | '2020-12'
  * which is the waste `renderToolSchema`'s own cache exists to remove, and it
  * would hand a fresh object to the wire each time. The tools block renders at
  * position 0 of the prompt-cache prefix, so a differently-ordered but equal
- * object still invalidates the cache for the whole run. Caching the conversion
+ * object still invalidates the cache for the whole turn. Caching the conversion
  * keeps the bytes identical across iterations.
  */
 const CONVERTED = new Map<JsonSchemaDialect, WeakMap<object, Record<string, unknown>>>()

package/src/registry/tool/execute.ts

@@ -82,7 +82,7 @@ const SEARCH_WEIGHT_ARGUMENT = 3
  * and the tools most likely to carry a bad name are registered deferred,
  * so it fired the moment one was activated with nothing naming the
  * culprit. Failing at registration instead names the tool, at the moment
- * something can still be done about it, and costs the run nothing.
+ * something can still be done about it, and costs the turn nothing.
  *
  * One driver already ratified passing names through untouched, on the
  * grounds that a confusing name is "a naming problem to fix in the
@@ -167,7 +167,7 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 	}
 
 	/**
-	 * Snapshot membership and availability for another run without changing this
+	 * Snapshot membership and availability for another turn without changing this
 	 * registry. Discovery, registration and suspension then affect only the fork.
 	 * Definitions, handlers and configuration remain shared; this is not a deep
 	 * clone or an authorization boundary. Prepared executions belong only to the
@@ -555,6 +555,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 					[GENAI.TOOL_NAME]: toolName,
 					[GENAI.TOOL_TYPE]: 'function',
 					...(context.toolUseId !== undefined ? { [GENAI.TOOL_CALL_ID]: context.toolUseId } : {}),
+					...toolSpanIdentity(context),
 					[NAMZU.TOOL_SUCCESS]: false,
 					[NAMZU.TOOL_ERROR]: toErrorMessage(err),
 				})
@@ -594,13 +595,14 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 				// asynchronously.
 				//
 				// Conditional because `toolUseId` is optional: a host calling
-				// a tool directly, outside a run, has no call to correlate to,
+				// a tool directly, outside a turn, has no call to correlate to,
 				// and an attribute set to `undefined` is worse than an absent
 				// one — it reaches the exporter as a key with no value.
 				span.setAttributes({
 					[GENAI.TOOL_NAME]: toolName,
 					[GENAI.TOOL_TYPE]: 'function',
 					...(context.toolUseId !== undefined ? { [GENAI.TOOL_CALL_ID]: context.toolUseId } : {}),
+					...toolSpanIdentity(context),
 				})
 
 				const availability = this.getAvailability(toolName)
@@ -693,10 +695,10 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 						// Explicit configuration wins, at whichever boundary it
 						// was made. A registry built WITH `resultGuardrails`
 						// has stated its policy — including `[]`, which means
-						// none — and a run must not overrule it. A registry
-						// built without one declared none, so the run's apply;
+						// none — and a turn must not overrule it. A registry
+						// built without one declared none, so the turn's apply;
 						// that is the ordinary case, since a host assembles a
-						// registry and hands it to a run it does not own.
+						// registry and hands it to a turn it does not own.
 						this.resultGuardrails ?? runResultGuardrails,
 						produced,
 						{
@@ -735,7 +737,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 					// tool call. Everything below turns an exception into a
 					// result the model reads and works around, which is what
 					// `refuse` is for — doing it to a `halt` would silently
-					// demote the one verdict that says the run must not
+					// demote the one verdict that says the turn must not
 					// continue.
 					if (err instanceof ToolResultHalted) {
 						span.setAttributes({
@@ -917,3 +919,14 @@ function describeRequiredInput(schema: { _def?: unknown }): string {
 		return 'Could not introspect required parameters.'
 	}
 }
+
+/**
+ * The session and turn a tool span belongs to. A host calling a tool
+ * directly may pass a context without them, so each is set only when present.
+ */
+function toolSpanIdentity(context: ToolContext): Record<string, string> {
+	return {
+		...(context.sessionId ? { [GENAI.CONVERSATION_ID]: context.sessionId } : {}),
+		...(context.turnId ? { [NAMZU.TURN_ID]: context.turnId } : {}),
+	}
+}

package/src/registry/tool/portable.ts

@@ -146,7 +146,7 @@ export function findPortableSchemaViolations(
  * Returns the input unchanged — the SAME reference — when nothing needs
  * rewriting, which is the overwhelming common case. The tools block sits at
  * position 0 of the prompt-cache prefix, so a fresh, equal object per request
- * would invalidate the cache for the whole run.
+ * would invalidate the cache for the whole turn.
  */
 export function toPortableToolSchema(json: Record<string, unknown>): Record<string, unknown> {
 	return makePortable(json) as Record<string, unknown>

package/src/registry/tool/presentation.ts

@@ -53,7 +53,7 @@ export function genericLabel(input: unknown): string {
 }
 
 /**
- * `registry` is the `ToolRegistryContract` a run already holds, so a
+ * `registry` is the `ToolRegistryContract` a turn already holds, so a
  * presenter never needs its own copy of what is registered — and a tool
  * added at runtime by a plugin is presentable the moment it is registered.
  */

package/src/registry/tool/schema.ts

@@ -19,7 +19,7 @@ import { toPortableToolSchema } from './portable.js'
  *    schema does not change between iterations; the work was pure waste,
  *    and worse, it made byte-stability a hope rather than a guarantee. The
  *    tools block sits at the head of the prompt-cache prefix, so a single
- *    reordered key would invalidate the entire cache for the run.
+ *    reordered key would invalidate the entire cache for the turn.
  *
  * Memoizing on the schema OBJECT (a `WeakMap`, so an unregistered tool's
  * entry is collectable) makes the rendering both free and identical across