@namzu/sdk 43.0.0 → 44.1.0

package/src/telemetry/attributes.ts

@@ -1,8 +1,9 @@
 import { context as otelContext, trace } from '@opentelemetry/api'
 export { GENAI, NAMZU } from '../constants/telemetry/index.js'
 
-export function agentRunSpanName(agentName: string): string {
-	return `namzu.agent.run ${agentName}`
+/** The root span of one turn. It carries `gen_ai.conversation.id` (the session) and `namzu.turn.id`. */
+export function agentTurnSpanName(agentName: string): string {
+	return `namzu.agent.turn ${agentName}`
 }
 
 export function agentIterationSpanName(iteration: number): string {
@@ -17,7 +18,7 @@ export function toolSpanName(toolName: string): string {
  * OTel GenAI semconv names the model-call span `chat {model}`.
  *
  * There was no span around the model call at all — `chatSpanName` existed
- * in `@namzu/telemetry` with zero call sites — so a run's traces carried
+ * in `@namzu/telemetry` with zero call sites — so a turn's traces carried
  * no LLM latency whatsoever, and the token attributes landed on the
  * iteration span instead of the operation that produced them.
  */
@@ -31,8 +32,8 @@ export function chatSpanName(model: string): string {
  * Async generators cannot use `startActiveSpan` for parenting: a generator
  * body resumes on its CONSUMER's async context, so whatever was active when
  * the parent span was created is gone by the time the child is made. Every
- * span-owning body in the run loop is a generator, which is why a 20-turn
- * run emitted 21 disconnected root spans. Passing the parent explicitly is
+ * span-owning body in the turn loop is a generator, which is why a
+ * 20-iteration turn emitted 21 disconnected root spans. Passing the parent explicitly is
  * the only thing that works here.
  */
 export function parentContext(parent?: import('@opentelemetry/api').Span | SerializedSpanContext) {
@@ -54,12 +55,12 @@ export function parentContext(parent?: import('@opentelemetry/api').Span | Seria
  *
  * `parentContext` used to accept only a live in-memory span, so a parent
  * that had to survive a process boundary could not be expressed at all — a
- * run that crashed at iteration 12 and resumed produced two traces with
+ * turn that crashed at iteration 12 and resumed produced two traces with
  * different trace ids and no link between them, and the crash and its
  * recovery could not be put on one timeline. Every span carries
- * `namzu.run.id`, which is enough to FIND both traces by query and not
- * enough to see one waterfall; and that much disappears for a replay fork,
- * which mints a new run id.
+ * `namzu.turn.id`, which is enough to FIND both traces by query and not
+ * enough to see one waterfall; and that much disappears for a fork, which
+ * starts a new session.
  *
  * Flat strings rather than the OTel type so it survives `JSON.stringify`
  * into a checkpoint unchanged.

package/src/telemetry/metrics.ts

@@ -22,7 +22,7 @@ let cached: { meter: Meter; instruments: Instruments } | undefined
 interface Instruments {
 	tokens: Counter
 	toolCalls: Counter
-	runDuration: Histogram
+	turnDuration: Histogram
 	llmDuration: Histogram
 	timeToFirstToken: Histogram
 	toolDuration: Histogram
@@ -43,8 +43,8 @@ function build(meter: Meter): Instruments {
 			description: 'Tool calls executed',
 			unit: '{call}',
 		}),
-		runDuration: meter.createHistogram('namzu.run.duration', {
-			description: 'Agent run duration',
+		turnDuration: meter.createHistogram('namzu.turn.duration', {
+			description: 'Agent turn duration',
 			unit: 's',
 		}),
 		llmDuration: meter.createHistogram('gen_ai.client.operation.duration', {
@@ -176,9 +176,9 @@ export function recordTimeToFirstToken(model: string, durationMs: number): void
 	instruments().timeToFirstToken.record(durationMs / 1000, { [GENAI.REQUEST_MODEL]: model })
 }
 
-/** Record how long a whole run took, keyed by how it settled. */
-export function recordRunDuration(status: string, durationMs: number): void {
-	instruments().runDuration.record(durationMs / 1000, { [NAMZU.RUN_STATUS]: status })
+/** Record how long a whole turn took, keyed by how it settled. */
+export function recordTurnDuration(status: string, durationMs: number): void {
+	instruments().turnDuration.record(durationMs / 1000, { [NAMZU.TURN_STATUS]: status })
 }
 
 /** Record how long one model request took. */

package/src/telemetry/runtime-accessors.ts

@@ -44,7 +44,7 @@ export function getActiveSpanContext(): SpanContext | undefined {
 	// this touches past the api boundary is a HOST's object. A third-party
 	// `ContextManager` whose `active()` throws would otherwise raise that
 	// exception inside every log call in the kernel — turning a logging
-	// integration bug into a run failure, at a call site nobody reading it
+	// integration bug into a turn failure, at a call site nobody reading it
 	// would suspect of being able to throw.
 	//
 	// Swallowed rather than reported, unlike a dropped record: this cannot

package/src/test-support/ids.ts

@@ -15,7 +15,6 @@ import type {
 	CredentialId,
 	DeliverableId,
 	DocumentId,
-	EmergencySaveId,
 	EnvironmentId,
 	ExecutionContextId,
 	HandoffId,
@@ -31,7 +30,7 @@ import type {
 	PlanId,
 	PluginId,
 	ProjectId,
-	RunId,
+	RecordId,
 	SandboxId,
 	SessionId,
 	SubSessionId,
@@ -40,6 +39,7 @@ import type {
 	TenantId,
 	ToolCallId,
 	TopicId,
+	TurnId,
 	UserId,
 	VaultRef,
 	WorkspaceId,
@@ -61,10 +61,11 @@ export function fixtureUuid(label: string): string {
 
 /**
  * One entry per entity type, keyed by the bare concept rather than the
- * type name — `fixtureId.run('a')`, not `fixtureId.RunId('a')`.
+ * type name — `fixtureId.turn('a')`, not `fixtureId.TurnId('a')`.
  */
 export const fixtureId = {
-	run: (suffix: string): RunId => unsafeId<RunId>(fixtureUuid(`run_${suffix}`)),
+	turn: (suffix: string): TurnId => unsafeId<TurnId>(fixtureUuid(`turn_${suffix}`)),
+	record: (suffix: string): RecordId => unsafeId<RecordId>(fixtureUuid(`rec_${suffix}`)),
 	message: (suffix: string): MessageId => unsafeId<MessageId>(fixtureUuid(`msg_${suffix}`)),
 	session: (suffix: string): SessionId => unsafeId<SessionId>(fixtureUuid(`ses_${suffix}`)),
 	toolCall: (suffix: string): ToolCallId => unsafeId<ToolCallId>(fixtureUuid(`call_${suffix}`)),
@@ -94,8 +95,6 @@ export const fixtureId = {
 	advisory: (suffix: string): AdvisoryId => unsafeId<AdvisoryId>(fixtureUuid(`adv_${suffix}`)),
 	advisoryCall: (suffix: string): AdvisoryCallId =>
 		unsafeId<AdvisoryCallId>(fixtureUuid(`advc_${suffix}`)),
-	emergencySave: (suffix: string): EmergencySaveId =>
-		unsafeId<EmergencySaveId>(fixtureUuid(`esave_${suffix}`)),
 	memory: (suffix: string): MemoryId => unsafeId<MemoryId>(fixtureUuid(`mem_${suffix}`)),
 	plugin: (suffix: string): PluginId => unsafeId<PluginId>(fixtureUuid(`plg_${suffix}`)),
 	sandbox: (suffix: string): SandboxId => unsafeId<SandboxId>(fixtureUuid(`sbx_${suffix}`)),

package/src/testing.ts

@@ -12,26 +12,21 @@
  * which is how each one is shown to fail a deliberately wrong
  * implementation.
  *
- * This barrel exists because the subpath used to point straight at the
- * checkpoint-store file. A second suite would have had to either move that
- * file's export or claim a subpath of its own, and neither is a decision a
- * consumer should absorb.
+ * A custom session log (a database, an object store) is proved against
+ * the session-log suite; a provider driver against the driver suite.
  */
 
 export {
-	CHECKPOINT_STORE_CONTRACT_VERSION,
-	defineCheckpointStoreConformance,
-} from './store/run/conformance.js'
+	SESSION_LOG_CONTRACT_VERSION,
+	defineSessionLogConformance,
+} from './store/session-log/conformance.js'
 export type {
-	CheckpointStoreCapabilities,
-	CheckpointStoreConformanceOptions,
-	CheckpointStoreHandle,
-	ConformanceAssertion,
-	ConformanceDescribe,
-	ConformanceExpect,
-	ConformanceIt,
-	MakeCheckpointStore,
-} from './store/run/conformance.js'
+	MakeSessionLog,
+	SessionLogAssertion,
+	SessionLogConformanceOptions,
+	SessionLogHandle,
+	SessionLogTamper,
+} from './store/session-log/conformance.js'
 
 export {
 	PROVIDER_DRIVER_CONTRACT_VERSION,

package/src/tools/advisory/index.ts

@@ -77,7 +77,7 @@ export function buildAdvisoryTools(opts: AdvisoryToolsOptions): ToolDefinition[]
 		permissions: [],
 		readOnly: true,
 		destructive: false,
-		// Consultations debit one run account and one per-run advisory quota.
+		// Consultations debit one turn account and one per-turn advisory quota.
 		// Serial execution makes the next admission see the preceding receipt.
 		concurrencySafe: false,
 		async execute({ advisor_id, question, domain, urgency, include_context }) {

package/src/tools/builtins/bash.ts

@@ -16,7 +16,7 @@ import { scrubInheritedEnv } from '../env-scrub.js'
 // still alias their own var to `NAMZU_BASH_TIMEOUT_MS` at deploy
 // time if they want a unified knob.
 // Two minutes, not an hour. The old default meant a wedged command held
-// the turn — and, before per-tool deadlines existed, the whole run — for
+// the turn — and, before per-tool deadlines existed, the whole turn — for
 // up to 3600s while ignoring Stop entirely. The model can still ask for
 // longer via the tool's own `timeout` argument when it knows a build is
 // slow; the point is that the DEFAULT is survivable.
@@ -66,6 +66,12 @@ const inputSchema = z.object({
 		.describe(
 			'Start the command as a background job and return its id immediately, instead of waiting. The turn is not held open; await its completion with `wait_for_job` — one call, no waiting turns. Use `job` with action "read" only for incremental output while it keeps running, or to pick up after a `wait_for_job` call times out. Use for watchers, dev servers and long builds. Do NOT write `cmd &` yourself — under the sandbox the shell that backgrounds it exits immediately and takes the job with it.',
 		),
+	dangerously_disable_sandbox: z
+		.boolean()
+		.optional()
+		.describe(
+			'Run this one command on the host, outside the sandbox. Only meaningful when commands are sandboxed, and only for a command that cannot work inside it (it needs the network, a path the sandbox does not mount, a host tool). The user is asked to approve it every time, whatever else is approved (plan and strict modes refuse it); with nobody to ask it is refused. Never set it to get around a permission refusal, and never with run_in_background.',
+		),
 })
 
 type BashInput = z.infer<typeof inputSchema>
@@ -279,6 +285,13 @@ function isDangerousCommand(command: string): boolean {
 export const SANDBOX_CANNOT_DETACH =
 	'run_in_background is unavailable: this sandbox cannot start a detached process, and the job will not be run on the host to get around it. Run the command in the foreground, or raise `timeout` up to the tool maximum.'
 
+/**
+ * The refusal when a call asks to leave the sandbox without a confirmed
+ * approval; exported so the test states the same words.
+ */
+export const SANDBOX_ESCAPE_NOT_APPROVED =
+	'dangerously_disable_sandbox was not approved for this call, so the command did not run. Leaving the sandbox needs the user to confirm it each time, and this turn either cannot ask or does not allow it. Run the command inside the sandbox, or tell the user what it needs and let them run it.'
+
 export const BashTool = defineTool({
 	name: 'bash',
 	description:
@@ -289,6 +302,9 @@ export const BashTool = defineTool({
 	// so a permission rule about it is a rule about several commands more often
 	// than not. Naming the argument is what lets the gate read it that way.
 	commandArgument: 'command',
+	// The kernel reviews a call that sets it under a sandbox every time and
+	// confirms it only by id; see `ToolDefinition.sandboxEscapeArgument`.
+	sandboxEscapeArgument: 'dangerously_disable_sandbox',
 	permissions: ['shell_execute'],
 	readOnly: false,
 	destructive: (input: BashInput) => isDangerousCommand(input.command),
@@ -309,8 +325,29 @@ export const BashTool = defineTool({
 			}
 		}
 
+		// Asked to leave the sandbox. Honoured only on the executor's word that
+		// a reviewer confirmed THIS call (`sandboxEscapeApproved`); the input
+		// alone is the model's request, never the permission. Without a
+		// sandbox there is nothing to leave and the flag changes nothing.
+		const leaveSandbox = input.dangerously_disable_sandbox === true && context.sandbox !== undefined
+		if (leaveSandbox && context.sandboxEscapeApproved !== true) {
+			return {
+				success: false,
+				output: '',
+				error: SANDBOX_ESCAPE_NOT_APPROVED,
+			}
+		}
+		if (leaveSandbox && input.run_in_background) {
+			return {
+				success: false,
+				output: '',
+				error:
+					'dangerously_disable_sandbox cannot be combined with run_in_background: a job started on the host would outlive the approval given for this one call. Run it in the foreground.',
+			}
+		}
+
 		if (input.run_in_background) {
-			// A sandboxed run gets a registry only when its sandbox can start a
+			// A sandboxed turn gets a registry only when its sandbox can start a
 			// detached process inside the boundary (`Sandbox.spawnDetached`);
 			// the executor withholds it otherwise. This check is for direct
 			// tool callers, who could hand a host registry and a sandbox to the
@@ -361,7 +398,7 @@ export const BashTool = defineTool({
 		// Sandbox-aware: route through sandbox.exec() when available.
 		//
 		// `context.workingDirectory` is the HOST-side workspace path the
-		// SDK consumer chose for the run (Vandal: `/var/lib/vandal/sessions/<task>`),
+		// SDK consumer chose for the turn (Vandal: `/var/lib/vandal/sessions/<task>`),
 		// which is meaningless inside the sandbox container. Forwarding
 		// it as `cwd` would either land on a path that doesn't exist
 		// (and the worker would `mkdir -p` it inside the container,
@@ -376,7 +413,7 @@ export const BashTool = defineTool({
 		// `SandboxExecOptions.workspaceRelativeCwd` field; the bash
 		// builtin doesn't have that requirement today.
 		const onOutput = shellProgress(context.report)
-		if (context.sandbox) {
+		if (context.sandbox && !leaveSandbox) {
 			const result = await context.sandbox.exec('/bin/sh', ['-c', input.command], {
 				timeout: input.timeout,
 				env: context.env,
@@ -451,7 +488,7 @@ export const BashTool = defineTool({
 			return {
 				success: true,
 				output: formatShellOutput(stdout, stderr) || '(no output)',
-				data: { exitCode: 0 },
+				data: { exitCode: 0, ...(leaveSandbox ? { sandboxed: false, sandboxEscape: true } : {}) },
 			}
 		} catch (err) {
 			const failure = err as NodeJS.ErrnoException & {
@@ -495,6 +532,7 @@ export const BashTool = defineTool({
 				output: output || '(no output)',
 				data: {
 					...(exitCode !== undefined ? { exitCode } : {}),
+					...(leaveSandbox ? { sandboxed: false, sandboxEscape: true } : {}),
 					timedOut,
 					stdoutTruncated: failure.stdoutTruncated ?? false,
 					stderrTruncated: failure.stderrTruncated ?? false,

package/src/tools/builtins/content-fingerprint.ts

@@ -6,7 +6,7 @@ import { createHash } from 'node:crypto'
  * Used to answer one question at mutation admission: is the file still what
  * the agent read? An `edit` or full replacement is based on a remembered
  * body, and before the write begins that body can move — a person editing in
- * an editor, another process, a second agent run. The in-process mutation
+ * an editor, another process, a second agent's turn. The in-process mutation
  * lock serializes this runtime's own writers and is blind to every one of
  * those.
  *
@@ -18,7 +18,7 @@ import { createHash } from 'node:crypto'
  *
  * Truncated deliberately. This distinguishes two bodies; it is not a
  * security boundary, and a full digest per read costs bytes in a structure
- * that lives for the whole run.
+ * that lives for the whole turn.
  */
 export function fingerprintContent(content: string): string {
 	return createHash('sha256').update(content, 'utf-8').digest('hex').slice(0, 16)

package/src/tools/builtins/edit-apply.ts

@@ -117,7 +117,7 @@ function normalizeInsertLine(
 		// the file" reaches for the word it knows, and every one of these says
 		// the same unambiguous thing. Refusing them bought strictness and cost
 		// a full model round trip per occurrence — measured by a consuming host
-		// as the single largest source of tool-call waste in its runs.
+		// as the single largest source of tool-call waste in its turns.
 		if (END_ALIASES.has(normalized)) return { success: true, value: 'end' }
 		const parsed = Number(value)
 		if (Number.isInteger(parsed) && parsed >= 0) return { success: true, value: parsed }

package/src/tools/builtins/edit.ts

@@ -288,6 +288,9 @@ export const EditTool = defineTool({
 	validationErrorHint:
 		'Three shapes. Replace: {"path":"file.md","old_string":"exact unique text","new_string":"replacement text"} (optional "replace_all": true). Insert: {"path":"file.md","insertLine":"end","new_string":"text to add"} where insertLine is a non-negative line number or "end". Batch: {"path":"file.md","edits":[{"old_string":"a","new_string":"b"},{"old_string":"c","new_string":"d"}]} applied in order, all or nothing. Exactly one of old_string, insertLine or edits — a call carrying more than one of them is refused rather than resolved.',
 	category: 'filesystem',
+	// Declared so a path outside the turn's roots can be reviewed before the
+	// call runs, rather than refused after. See `ToolDefinition.pathArgument`.
+	pathArgument: 'path',
 	permissions: ['file_write'],
 	readOnly: false,
 	destructive: false,

package/src/tools/builtins/glob.ts

@@ -61,6 +61,9 @@ export const GlobTool = defineTool({
 		'Finds regular files by glob pattern in a bounded search. "*" searches one directory; use "**" explicitly for recursive discovery. Returns at most 500 paths and identifies incomplete searches. Does not follow symlinks.',
 	inputSchema,
 	category: 'filesystem',
+	// Declared so a path outside the turn's roots can be reviewed before the
+	// call runs, rather than refused after. See `ToolDefinition.pathArgument`.
+	pathArgument: 'path',
 	permissions: ['file_read'],
 	readOnly: true,
 	destructive: false,

package/src/tools/builtins/grep.ts

@@ -94,6 +94,9 @@ export const GrepTool = defineTool({
 		'Searches file contents using a regular expression. Returns matching lines with file paths, line numbers, and optional context lines. Searches incrementally with a bounded traversal; identifies incomplete searches. Skips binary files, files over 5 MB, and symlinks. Choose the narrowest relevant directory.',
 	inputSchema,
 	category: 'analysis',
+	// Declared so a path outside the turn's roots can be reviewed before the
+	// call runs, rather than refused after. See `ToolDefinition.pathArgument`.
+	pathArgument: 'path',
 	permissions: ['file_read'],
 	readOnly: true,
 	destructive: false,

package/src/tools/builtins/job.ts

@@ -20,7 +20,7 @@ const inputSchema = z.object({
 	action: z
 		.enum(['read', 'list', 'kill'])
 		.describe(
-			'read: output since `from_offset`. list: every background job this run started, with status. kill: stop a job and everything it forked.',
+			'read: output since `from_offset`. list: every background job this turn started, with status. kill: stop a job and everything it forked.',
 		),
 	id: z
 		.string()
@@ -86,7 +86,7 @@ export const JobTool = defineTool({
 			return {
 				success: false,
 				output: '',
-				error: `action "${input.action}" needs an id. Use action "list" to see the jobs this run has started.`,
+				error: `action "${input.action}" needs an id. Use action "list" to see the jobs this turn has started.`,
 			}
 		}
 
@@ -127,9 +127,9 @@ export const JobTool = defineTool({
 				},
 			}
 		} catch (err) {
-			// An id from another run reads as unknown here, because the
-			// owner-bound view refuses it. That is the intended answer: a run
-			// should not be able to confirm another run's job exists.
+			// An id from another turn reads as unknown here, because the
+			// owner-bound view refuses it. That is the intended answer: a turn
+			// should not be able to confirm another turn's job exists.
 			return {
 				success: false,
 				output: '',

package/src/tools/builtins/ls.ts

@@ -209,6 +209,9 @@ export const LsTool = defineTool({
 		'Lists directory contents. Shows files and directories with sizes. Supports recursive listing with depth limit, and hidden file display.',
 	inputSchema,
 	category: 'filesystem',
+	// Declared so a path outside the turn's roots can be reviewed before the
+	// call runs, rather than refused after. See `ToolDefinition.pathArgument`.
+	pathArgument: 'path',
 	permissions: ['file_read'],
 	readOnly: true,
 	destructive: false,

package/src/tools/builtins/lsp.ts

@@ -70,6 +70,9 @@ export const LspTool = defineTool({
 		'Resolves a symbol through a language server: where it is declared, and everywhere it is used. Use it instead of grep when the answer has to be right — grep finds the identifier in comments and strings and misses call sites that come through a re-export.',
 	inputSchema,
 	category: 'filesystem',
+	// Declared so a path outside the turn's roots can be reviewed before the
+	// call runs, rather than refused after. See `ToolDefinition.pathArgument`.
+	pathArgument: 'path',
 	permissions: ['file_read'],
 	readOnly: true,
 	destructive: false,
@@ -86,7 +89,7 @@ export const LspTool = defineTool({
 				success: false,
 				output: '',
 				error:
-					'This run has no code navigation provider, so there is nothing to resolve against. A host supplies one on the tool context; `grep` is the fallback, and it answers a different question.',
+					'This turn has no code navigation provider, so there is nothing to resolve against. A host supplies one on the tool context; `grep` is the fallback, and it answers a different question.',
 			}
 		}
 
@@ -203,7 +206,7 @@ function failedMessage(error: string): string {
 /**
  * The tool, only when there is something for it to call.
  *
- * A function rather than a constant because the decision is per run: the
+ * A function rather than a constant because the decision is per turn: the
  * same process can serve one session with a language server and one
  * without, and a module-level constant would have to pick.
  */

package/src/tools/builtins/read-file.ts

@@ -40,6 +40,9 @@ export const ReadFileTool = defineTool({
 		'Reads a file and returns its contents with line numbers. Supports readRange ([start,end], 1-indexed inclusive) or offset/limit for large files. Without a window it returns the first 2000 lines and says so — pass offset/limit to continue.',
 	inputSchema,
 	category: 'filesystem',
+	// Declared so a path outside the turn's roots can be reviewed before the
+	// call runs, rather than refused after. See `ToolDefinition.pathArgument`.
+	pathArgument: 'path',
 	permissions: ['file_read'],
 	readOnly: true,
 	destructive: false,

package/src/tools/builtins/run-code.ts

@@ -5,22 +5,22 @@ import { WorkerCodeRuntime } from '../../execution/code-runtime/worker.js'
 import { defineTool } from '../defineTool.js'
 
 /**
- * A program the model wrote, calling the run's own tools.
+ * A program the model wrote, calling the turn's own tools.
  *
  * Twenty tool calls to filter a list is twenty model turns, each at full
  * context size with the whole conversation resent. The same work is one
  * loop. That is the entire argument for this tool, and it only holds if the
  * loop cannot reach further than the twenty calls could have.
  *
- * **The program's reach is the RUN's reach, and nothing wider.** Every
- * capability it can call is a tool already in this run's registry and
+ * **The program's reach is the TURN's reach, and nothing wider.** Every
+ * capability it can call is a tool already in this turn's registry and
  * narrowed by the turn's `allowedTools`. The host dispatch records every
- * child in the run and applies the run's operator authorization gate. An
+ * child in the turn and applies the turn's operator authorization gate. An
  * explicit allow proceeds; a denial or an undecided child fails closed and
  * leaves a durable refusal, because an already-executing parent cannot open
  * a second durable human-review turn on the program's behalf.
  *
- * Opt-in, and not in the default builtin set. A run that does not need
+ * 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.
@@ -40,7 +40,7 @@ const inputSchema = z.object({
 		),
 })
 
-type RunCodeInput = z.infer<typeof inputSchema>
+type CodeToolInput = z.infer<typeof inputSchema>
 
 export const RUN_CODE_TOOL_NAME = 'run_code'
 
@@ -65,7 +65,7 @@ export function buildRunCodeTool(options: RunCodeToolOptions = {}) {
 
 	return defineTool({
 		name: RUN_CODE_TOOL_NAME,
-		description: `Runs a short JavaScript program that can call this run's own tools in a loop. Use it when the same tool would otherwise be called many times in a row — filtering, retrying, fanning out — and not for a single call. ${
+		description: `Runs a short JavaScript program that can call this turn's own tools in a loop. Use it when the same tool would otherwise be called many times in a row — filtering, retrying, fanning out — and not for a single call. ${
 			options.toolResultMode === 'structured'
 				? 'Each successful call() returns { output: string, data?: JSON value }. Filter data locally and return only the needed result. Failed calls reject.'
 				: 'Each successful call() returns the tool output string. Failed calls reject.'
@@ -82,13 +82,13 @@ export function buildRunCodeTool(options: RunCodeToolOptions = {}) {
 		destructive: true,
 		concurrencySafe: false,
 
-		async execute(input: RunCodeInput, context) {
+		async execute(input: CodeToolInput, context) {
 			const dispatch = context.dispatchTool
 			if (!dispatch) {
 				return {
 					success: false,
 					output: '',
-					error: 'This run provides no way to dispatch a tool, so a program has nothing to call.',
+					error: 'This turn provides no way to dispatch a tool, so a program has nothing to call.',
 				}
 			}
 
@@ -109,7 +109,7 @@ export function buildRunCodeTool(options: RunCodeToolOptions = {}) {
 				maxOutputBytes: options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT,
 				...(context.abortSignal ? { signal: context.abortSignal } : {}),
 				onHostCall: async (request, operation) => {
-					// Through the run-owned nested dispatch: registry narrowing,
+					// Through the turn-owned nested dispatch: registry narrowing,
 					// operator authorization, audit/event lineage and invocation
 					// cancellation remain host-owned rather than worker-owned.
 					try {
@@ -141,7 +141,7 @@ export function buildRunCodeTool(options: RunCodeToolOptions = {}) {
 
 			const notes = [
 				refused.length > 0
-					? `[not granted, and refused to the program: ${refused.join(', ')} — this turn allows only ${turnAllows?.join(', ') ?? 'the run default'}]`
+					? `[not granted, and refused to the program: ${refused.join(', ')} — this turn allows only ${turnAllows?.join(', ') ?? 'the turn default'}]`
 					: '',
 				result.outputTruncated
 					? '[the program printed more than the output limit and was cut here]'

package/src/tools/builtins/skill.ts

@@ -9,7 +9,7 @@ import { defineTool } from '../defineTool.js'
  *
  * The manifest in the system prompt told the model that a SKILL.md exists
  * and to "read the SKILL.md at its <location> before writing code" — which
- * is a filesystem instruction, so a run with no filesystem tools could see
+ * is a filesystem instruction, so a turn with no filesystem tools could see
  * every skill it had and open none of them. The protocol text even admits
  * it: *"when the runtime exposes filesystem or skill-loading tools"*. There
  * was no skill-loading tool.
@@ -274,7 +274,7 @@ export const SkillTool = defineTool({
 				success: false,
 				output: '',
 				error:
-					'This run has no skills registry, so there is nothing to load. Proceed without the skill.',
+					'This turn has no skills registry, so there is nothing to load. Proceed without the skill.',
 			}
 		}
 
@@ -433,7 +433,7 @@ export const SkillTool = defineTool({
 			// the field as a declaration.
 			//
 			// Absent `adoptSkillScope`, the notice still goes out and is all
-			// there is: a host driving this tool outside a run has no executor
+			// there is: a host driving this tool outside a turn has no executor
 			// to enforce anything, and saying nothing would be worse than
 			// advice.
 			context.adoptSkillScope?.({ skill: skill.metadata.name, allowedTools: allowed })

package/src/tools/builtins/wait-for-job-bounds.ts

@@ -14,7 +14,7 @@ import type { BackgroundJobRegistryRef } from '../../types/tool/index.js'
  * as progress would make the idle bound unable to fire for a wedged job at
  * all, which is the exact failure this exists to catch.
  *
- *  - the **run bound** counts elapsed time and is never refreshed. It
+ *  - the **wall-clock bound** counts elapsed time and is never refreshed. It
  *    exists for a job that stays busy forever (a server, a stuck build).
  *  - the **idle bound** counts time since output last grew, and resets
  *    whenever it does. It exists for a job that stopped producing anything
@@ -26,10 +26,10 @@ import type { BackgroundJobRegistryRef } from '../../types/tool/index.js'
  */
 export interface JobWaitOptions {
 	/** Elapsed-time ceiling, never refreshed. */
-	readonly runMs: number
+	readonly wallMs: number
 	/**
 	 * Time-without-new-output ceiling, refreshed whenever `read` returns
-	 * more than it did last tick. Omit to bound by the run clock alone.
+	 * more than it did last tick. Omit to bound by the turn clock alone.
 	 */
 	readonly idleMs?: number
 	/** Resume from here rather than the start of what the job has retained. */
@@ -53,7 +53,7 @@ export type JobWaitOutcome =
 	| ({
 			readonly kind: 'timeout'
 			/** Which clock ran out. */
-			readonly cause: 'idle' | 'run'
+			readonly cause: 'idle' | 'wall'
 			readonly elapsedMs: number
 	  } & JobWaitProgress)
 
@@ -126,11 +126,11 @@ export async function waitForJobWithBounds(
 				if (settled) return
 				drain()
 				const elapsed = now() - startedAt
-				if (elapsed >= options.runMs) {
+				if (elapsed >= options.wallMs) {
 					clearInterval(tick)
 					resolve({
 						kind: 'timeout',
-						cause: 'run',
+						cause: 'wall',
 						elapsedMs: elapsed,
 						output,
 						nextOffset: cursor,

package/src/tools/builtins/wait-for-job.ts

@@ -120,18 +120,18 @@ export const WaitForJobTool = defineTool({
 		// case the kernel's hold exists to back up, and one that started the
 		// wait and then ended its turn is the same case a beat later. Nothing
 		// infers this from the job's existence — a dev server the model never
-		// waited on never holds a run open. See `runtime/jobs/awaited-jobs.ts`.
+		// waited on never holds a turn open. See `runtime/jobs/awaited-jobs.ts`.
 		jobs.markAwaited?.(input.id)
 
 		let outcome: Awaited<ReturnType<typeof waitForJobWithBounds>>
 		try {
 			outcome = await waitForJobWithBounds(jobs, input.id, {
-				runMs: input.timeout_ms ?? DEFAULT_TIMEOUT_MS,
+				wallMs: input.timeout_ms ?? DEFAULT_TIMEOUT_MS,
 				idleMs: input.idle_timeout_ms ?? DEFAULT_IDLE_TIMEOUT_MS,
 				signal: context.abortSignal,
 			})
 		} catch {
-			// The signal fired before either bound did — Stop, or the run's
+			// The signal fired before either bound did — Stop, or the turn's
 			// own deadline. The job is untouched: ending a WAIT is not
 			// ending the WORK. The executor has already raced this same
 			// signal against the whole call and reports the cancellation

package/src/tools/builtins/web-guidance.ts

@@ -11,7 +11,7 @@ import { WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME } from './web.js'
  * it twice and still leave the joint rule — search then fetch — belonging
  * to neither.
  *
- * `static`, because it depends on nothing that can change inside a run: the
+ * `static`, because it depends on nothing that can change inside a turn: the
  * two tool names are constants, and the guidance is the same on every turn.
  * That is what lets it sit in the cached prefix rather than being re-sent.
  *
@@ -26,7 +26,7 @@ export const WEB_GUIDANCE_CONTRIBUTION_ID = 'namzu.web.citations'
 /**
  * Registered only when the web tools are.
  *
- * Guidance about tools a run does not have is worse than absent: it spends
+ * Guidance about tools a turn does not have is worse than absent: it spends
  * the cached prefix telling the model to cite results from a search it
  * cannot run, and a model that follows it produces citations for pages
  * nobody fetched.