@namzu/sdk 42.0.2 → 44.0.0

package/src/compaction/reducer.ts

@@ -9,7 +9,7 @@ import { findRetainedIndices } from './retention.js'
  * them apart has to guess. `'threshold'` is speculative — the estimate says
  * the window is filling, nothing has failed, and declining costs only some
  * headroom. `'overflow'` is the provider having already rejected the
- * prompt: declining there ends the run.
+ * prompt: declining there ends the turn.
  */
 export type ContextReductionReason = 'threshold' | 'overflow'
 
@@ -22,23 +22,23 @@ export interface ContextReduction {
 	readonly estimatedTokens: number
 	/** What it has to fit in. Resolved from the model when the host did not say. */
 	readonly contextWindowTokens: number
-	/** The model this run is calling, for a reducer that varies by model. */
+	/** The model this turn is calling, for a reducer that varies by model. */
 	readonly model: string
-	/** The run's configured recent-window size, as a starting point. */
+	/** The turn's configured recent-window size, as a starting point. */
 	readonly keepRecentMessages: number
 }
 
 /**
- * Replace the run's history with a shorter one.
+ * Replace the turn's history with a shorter one.
  *
  * Returning `undefined` means "I could not shorten this" and is a first-class
- * answer, not a failure — on `'threshold'` the run simply continues, and on
+ * answer, not a failure — on `'threshold'` the turn simply continues, and on
  * `'overflow'` it fails with an irreducible-prompt error instead of retrying
  * a prompt nothing changed. That is deliberate: a reducer that returned the
  * input unchanged while reporting success would send the same rejected
  * prompt again and burn a call to learn the same thing.
  *
- * A reducer OWNS reduction for the run it governs. The built-in structured
+ * A reducer OWNS reduction for the turn it governs. The built-in structured
  * pass — LLM-verified summarization, stale tool-result clearing, working
  * state slots — does not also run, because two mechanisms editing the same
  * history in one pass cannot both be reasoned about.
@@ -50,7 +50,7 @@ export interface ContextReduction {
  *    working-memory slot; dropping them changes who the agent is.
  * 2. `tool_use` and its `tool_result` stay together. A split pair is a 400
  *    from the provider, so a reducer that splits one turns a context problem
- *    into a dead run. {@link findSafeTrimIndex} is exported for this.
+ *    into a dead turn. {@link findSafeTrimIndex} is exported for this.
  * 3. Messages marked `retain` survive. That marker is how a caller says a
  *    fact in the middle of the conversation outranks recency.
  */
@@ -60,7 +60,7 @@ export type ContextReducer = (
 
 export interface SlidingWindowOptions {
 	/**
-	 * How many trailing messages to keep. Defaults to the run's configured
+	 * How many trailing messages to keep. Defaults to the turn's configured
 	 * `keepRecentMessages`, so the same knob governs both strategies.
 	 */
 	readonly keepRecentMessages?: number

package/src/compaction/retention.ts

@@ -12,10 +12,10 @@ import type { AssistantMessage, Message, ToolMessage } from '../types/message/in
  * is host-rendered per turn and does not know what the user said.
  *
  * `retain` says it directly. The cost of the marker is paid by whoever
- * sets it: pinned turns are exempt from the reclaim that keeps a long run
+ * sets it: pinned turns are exempt from the reclaim that keeps a long turn
  * alive, so pinning the whole history is a way to make compaction useless.
  * Nothing here enforces a ceiling — a limit would have to guess which pin
- * mattered, and dropping the wrong one silently is worse than the run
+ * mattered, and dropping the wrong one silently is worse than the turn
  * overflowing loudly.
  */
 

package/src/compaction/salience/bm25.ts

@@ -1,5 +1,5 @@
 /**
- * BM25 over the run's own messages.
+ * BM25 over the turn's own messages.
  *
  * The corpus is small — a few hundred documents at most — so the index
  * is rebuilt from term frequencies each pass rather than maintained
@@ -7,7 +7,7 @@
  * constants are the textbook ones (k1 = 1.2, b = 0.75). What matters
  * here is not ranking quality against a web corpus but that a message
  * mentioning the goal's identifiers outscores one that does not, and
- * that a term every message contains (the run's own file name, say)
+ * that a term every message contains (the turn's own file name, say)
  * stops counting.
  */
 

package/src/compaction/salience/goal.ts

@@ -2,12 +2,12 @@
  * The goal vector: what "relevant" is measured against.
  *
  * Not the whole history — that would make every message relevant to
- * itself — but the four things that say what the run is for right now:
+ * itself — but the four things that say what the turn is for right now:
  * the first user message (the task), the most recent user turns (the
  * requirements as they were refined), the open items of the task list
- * when the run keeps one, and the latest assistant text (its stated
+ * when the turn keeps one, and the latest assistant text (its stated
  * intent). Weighted by repetition rather than a coefficient: the task
- * statement is included twice so a run that has drifted into detail is
+ * statement is included twice so a turn that has drifted into detail is
  * still scored against what it was asked to do.
  */
 

package/src/compaction/salience/minhash.ts

@@ -5,7 +5,7 @@
  * a line number moves — and still the same output. Three-word shingles
  * hashed 64 ways give a Jaccard estimate that is stable against those
  * edits and cheap enough to compare every message against every other
- * once per pass at the sizes a run reaches. Hashing is FNV-1a with a
+ * once per pass at the sizes a turn reaches. Hashing is FNV-1a with a
  * per-slot seed; nothing here needs to be cryptographic, only consistent
  * within a process.
  */

package/src/compaction/salience/score.ts

@@ -3,7 +3,7 @@
  *
  * The compaction pass chose what to keep by position — the floor, the
  * last few turns, the last few tool results — and a fact stated in the
- * middle of a long run aged out at the same rate as chatter. This gives
+ * middle of a long turn aged out at the same rate as chatter. This gives
  * every message a number instead, from four things the kernel can
  * observe without a model:
  *
@@ -19,7 +19,7 @@
  * What no score may cross is stated as `protected`: the leading system
  * run, `retain` markers with the turn they pull in, the most recent
  * turns, and the other half of a tool-call pair. Pure, like `plan.ts`:
- * no run, no logger, no provider, so it can be asked without one.
+ * no turn, no logger, no provider, so it can be asked without one.
  */
 
 import type { AssistantMessage, Message, ToolMessage } from '../../types/message/index.js'
@@ -242,7 +242,7 @@ export function scoreMessages(
 		} else if (message.role === 'tool') {
 			// Used is used: one identifier from this result named by a later
 			// turn is the evidence, and a count would let the recency of
-			// everything after it outvote the one result the run came back
+			// everything after it outvote the one result the turn came back
 			// for. The eval that placed the account id deep in an early dump
 			// and cited it later watched the salience pass clear it under a
 			// thirds rule.

package/src/compaction/salience/tokenize.ts

@@ -6,7 +6,7 @@
  * nothing and `removeTodo` as another; the model, asked about `store`,
  * is looking at both. So a path splits on its separators, a `camelCase`
  * or `snake_case` identifier splits into its words AND keeps its whole
- * form, and a dotted attribute key (`namzu.run.id`) yields both the key
+ * form, and a dotted attribute key (`namzu.turn.id`) yields both the key
  * and its parts. Everything is lower-cased; nothing is stemmed, because
  * a stemmer that turns `tests` into `test` also turns `testing` into it,
  * and the false matches cost more than the missed ones in a corpus this

package/src/compaction/verifier.ts

@@ -112,8 +112,8 @@ function truncateMessages(messages: readonly Message[], budget: number): string
  * The verifier runs outside the iteration loop, so its usage never reached
  * `runMgr.accumulateUsage` and the guard could not see it — and it fires
  * exactly when the context is largest, making it the most expensive call
- * the run does not count. A one-method sink keeps the compaction layer
- * from depending on `RunPersistence`.
+ * the turn does not count. A one-method sink keeps the compaction layer
+ * from depending on `TurnRecorder`.
  */
 export type UsageSink = (usage: TokenUsage) => void
 
@@ -136,11 +136,11 @@ export async function buildVerifiedSummary(
 	config: CompactionConfig,
 	onUsage?: UsageSink,
 	/**
-	 * The run's model. Required in practice: this used to send `model: ''`,
+	 * The turn's model. Required in practice: this used to send `model: ''`,
 	 * which some drivers quietly default and others reject outright — on
 	 * some backends the model id IS the endpoint. So compaction's verifier failed
-	 * exactly on the providers where a long run most needs it, and the
-	 * failure surfaced as compaction killing the run it exists to save.
+	 * exactly on the providers where a long turn most needs it, and the
+	 * failure surfaced as compaction killing the turn it exists to save.
 	 */
 	model?: string,
 	options: CompactionVerificationOptions = {},
@@ -162,7 +162,7 @@ export async function buildVerifiedSummary(
 
 /**
  * Query-only seam for a provider whose idle/retry/fallback order was already
- * composed at run admission. Wrapping that chain again would put an idle
+ * composed at turn admission. Wrapping that chain again would put an idle
  * timer around retry backoff and misclassify a healthy recovery pause as a
  * stalled stream. This symbol is intentionally absent from the package barrel.
  */
@@ -243,7 +243,7 @@ async function buildVerifiedSummaryWithProvider(
 	// content at all — and used to fall through to the append below, stamping a
 	// bare `## LLM Verification Additions` heading with nothing under it. That
 	// empty promise then rides in the compaction summary, and therefore in every
-	// subsequent system prompt, for the rest of the run. A heading with no body
+	// subsequent system prompt, for the rest of the turn. A heading with no body
 	// is not a verification result; treat a silent verifier the same as one that
 	// had nothing to say.
 	if (responseText === 'COMPLETE' || responseText.length === 0) {

package/src/compaction/wire.ts

@@ -10,7 +10,7 @@ import type { FileSlot, PinSlot, PlanSlot, ToolResultSlot, WorkingState } from '
  * it — `serializeState` is cumulative, so within one process that is true.
  *
  * Across a resume it was not. The manager was rebuilt empty on every
- * `query()`, so the second compaction of a resumed run summarized only
+ * `query()`, so the second compaction of a resumed turn summarized only
  * post-resume activity and deleted the summary that held everything
  * before it. The restore path goes out of its way to carry that summary
  * forward (it is the only surviving record of the history the first pass

package/src/config/registry.ts

@@ -4,7 +4,7 @@ import { type ConfigOverrideStore, InMemoryConfigOverrideStore } from '../store/
 import { type Logger, resolveLogger } from '../utils/logger.js'
 
 /**
- * Configuration a plugin declares and an operator retunes while a run is
+ * Configuration a plugin declares and an operator retunes while a turn is
  * live.
  *
  * `config/runtime.ts` is one Zod schema parsed once into `RUNTIME_DEFAULTS`
@@ -68,7 +68,7 @@ export interface ConfigRegistryOptions {
 	/**
 	 * Prefix for this registry's store keys. Set by {@link ConfigRegistry.scope}.
 	 *
-	 * Two concurrent runs share a process and a store; without a prefix the
+	 * Two concurrent turns share a process and a store; without a prefix the
 	 * second would read the first's overrides and retune it.
 	 */
 	readonly scopeId?: string
@@ -110,9 +110,9 @@ export class ConfigRegistry {
 	}
 
 	/**
-	 * A registry for one run, sharing this one's store.
+	 * A registry for one turn, sharing this one's store.
 	 *
-	 * Namespaces and watchers are per scope — two concurrent runs cannot see
+	 * Namespaces and watchers are per scope — two concurrent turns cannot see
 	 * or retune each other — while the store is shared so an operator's
 	 * override written under one scope is not lost when it ends. The same
 	 * arrangement `ScopedConnectorRegistry` uses, keyed the same way.

package/src/config/runtime.ts

@@ -35,7 +35,7 @@ export const CompactionConfigSchema = z.object({
 	/**
 	 * Optional model context-window size (tokens) the compaction trigger
 	 * measures the CURRENT window against. NO default: when omitted the
-	 * trigger falls back to the run-level cumulative `tokenBudget` exactly as
+	 * trigger falls back to the turn-level cumulative `tokenBudget` exactly as
 	 * before, so existing consumers are byte-identical. Hosts that keep
 	 * `tokenBudget` unlimited (0) set this so compaction fires on
 	 * window-pressure instead of being a silent no-op.
@@ -51,7 +51,7 @@ export const CompactionConfigSchema = z.object({
 	 * trigger armed, so the next iteration compacts again — paying a
 	 * summarization call and busting the prompt-cache prefix each time, for
 	 * nothing. A pass that cannot reach this level logs the shortfall and
-	 * the run continues rather than repeating a move that does not work.
+	 * the turn continues rather than repeating a move that does not work.
 	 *
 	 * The field was declared and set by the shipped CLI but read by nothing;
 	 * the choice was to implement it or delete it, and thrash is a real
@@ -121,7 +121,7 @@ export const CompactionConfigSchema = z.object({
 	/**
 	 * Entries pinned at the head of each capped list, never evicted.
 	 *
-	 * Eviction used to drop the OLDEST entry, so a long run silently
+	 * Eviction used to drop the OLDEST entry, so a long turn silently
 	 * deleted the decision that set its approach while keeping the last
 	 * twenty-five incidental notes. The early entries are the load-bearing
 	 * ones and the recent ones are still in the un-compacted tail.

package/src/connector/http-operation.ts

@@ -142,7 +142,7 @@ export async function readConnectorResponseBody(
  *
  * The promise race is intentional. Forwarding a signal cannot settle a custom
  * fetch/body implementation that ignores it, and a connector lifecycle is a
- * public entry point independent of the run executor's own tool deadline.
+ * public entry point independent of the turn executor's own tool deadline.
  */
 export class ConnectorHttpOperation {
 	readonly signal: AbortSignal

package/src/connector/mcp/adapter.ts

@@ -337,7 +337,7 @@ const MAX_TUPLE_ARITY = 32
  * server JSON Schema → Zod → JSON Schema on the wire. So whatever is emitted
  * here has to be a construct the receiving wire accepts, and a construct it
  * rejects fails the ENTIRE request rather than degrading one tool — taking
- * down every run that offered the toolset. A faithful conversion that cannot
+ * down every turn that offered the toolset. A faithful conversion that cannot
  * be sent is strictly worse than a lossy one that can.
  *
  * NO positional shape is a construct every wire accepts. That was measured the

package/src/connector/mcp/client.ts

@@ -903,7 +903,7 @@ export class MCPClient {
 	 * and on `http_sse` (whose reply arrives on a separate channel) a
 	 * server that wedged left the promise pending forever. Combined with
 	 * an executor that awaited tools unbounded, one unresponsive MCP
-	 * server hung the whole run with no error and no `run_failed`: not a
+	 * server hung the whole turn with no error and no `turn_failed`: not a
 	 * crash, just a process that stopped.
 	 */
 	private request(

package/src/connector/mcp/discovery.ts

@@ -32,7 +32,7 @@ export interface MCPToolDiscoveryOptions {
 	 * Called when a server's tool set differs from the previous discovery.
 	 *
 	 * Drift is reported rather than blocked because the right response is a
-	 * host decision: a dev server legitimately changes between runs, while
+	 * host decision: a dev server legitimately changes between turns, 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.
@@ -116,7 +116,7 @@ export class MCPToolDiscovery {
 
 		// The boundary. Without it the REMOTE side decides what enters the
 		// agent's registry, which inverts least privilege: a server could
-		// add a tool between two runs and it became callable with nobody
+		// add a tool between two turns and it became callable with nobody
 		// having agreed to it.
 		const policy = this.options.policies?.[state.serverName] ?? this.options.policies?.['*']
 		const { admitted, refused } = applyToolPolicy(advertised, policy)

package/src/connector/mcp/policy.ts

@@ -7,7 +7,7 @@ import type { MCPToolDefinition } from '../../types/connector/index.js'
  * Discovery used to take whatever the server offered, which puts the
  * REMOTE side in charge of what enters the agent's tool registry — the
  * exact inversion of least privilege. A server could add a tool between
- * two runs and it became callable with no one having agreed to it.
+ * two turns and it became callable with no one having agreed to it.
  */
 export interface MCPToolPolicy {
 	/**

package/src/connector/mcp/prompt-adapter.ts

@@ -22,7 +22,7 @@ import type { MCPClient } from './client.js'
  *   server changes its wording. Worse, system position READS as
  *   instruction, which is the last thing text from a remote party should
  *   read as.
- * - A slash command routes through the host's UI, so a headless run — the
+ * - A slash command routes through the host's UI, so a headless turn — the
  *   case this kernel is built for — could never use one.
  *
  * A tool call is explicit, auditable, passes the same admission policy and
@@ -139,14 +139,14 @@ export function mcpPromptToToolDefinition(
 					),
 				}
 			} catch (err) {
-				// Cancellation belongs to the run, not to the remote prompt. Turning
+				// Cancellation belongs to the turn, not to the remote prompt. Turning
 				// it into an ordinary failed tool result would let the executor treat
 				// a withdrawn operation as one the model may route around.
 				if (context.abortSignal?.aborted) throw context.abortSignal.reason
 				// Returned to the MODEL rather than thrown. A prompt that
 				// cannot be fetched — a server that went away, an argument it
 				// rejected — is something the agent can work around, and
-				// killing the run over it would be the wrong trade for a
+				// killing the turn over it would be the wrong trade for a
 				// read-only lookup.
 				return {
 					success: false,

package/src/constants/a2a/index.ts

@@ -1,17 +1,24 @@
-import type { WireRunStatus } from '../../contracts/index.js'
+import type { WireTurnStatus } from '../../contracts/session/turn-status.js'
 import type { A2ATaskState } from '../../types/a2a/index.js'
 
 export const A2A_PROTOCOL_VERSION = '0.3.0'
 
-export const RUN_STATUS_TO_A2A: Record<WireRunStatus, A2ATaskState> = {
+/**
+ * A turn's wire status as an A2A task state. An A2A task is one namzu turn.
+ *
+ * `awaiting_input` is `input-required`: the turn waits on a person, and a peer
+ * that read `running` would wait forever for an answer nobody gives.
+ */
+export const TURN_STATUS_TO_A2A: Readonly<Record<WireTurnStatus, A2ATaskState>> = Object.freeze({
 	queued: 'pending',
 	running: 'running',
+	awaiting_input: 'input-required',
 	completed: 'completed',
 	failed: 'failed',
 	cancelled: 'canceled',
 	cancelling: 'running',
 	expired: 'failed',
-}
+})
 
 export const TERMINAL_STATES: ReadonlySet<A2ATaskState> = new Set([
 	'completed',

package/src/constants/continuation.ts

@@ -8,7 +8,7 @@
  * The exact string is the marker used by `resolveResult` (in
  * `manager/run/persistence.ts`) to detect auto-continuation
  * boundaries: when walking the message tail it skips user messages
- * that match this constant verbatim, so the run's `result` field
+ * that match this constant verbatim, so the turn's `result` field
  * concatenates the full multi-turn assistant output instead of only
  * surfacing the trailing continuation chunk.
  *

package/src/constants/index.ts

@@ -12,7 +12,6 @@ export * from './continuation.js'
 export * from './limits.js'
 export * from './bus/index.js'
 export * from './authorization/index.js'
-export * from './emergency.js'
 export * from './plugin/index.js'
 export * from './sandbox/index.js'
 export * from './secret-patterns.js'

package/src/constants/limits.ts

@@ -1,7 +1,7 @@
 import type { CostInfo, TokenUsage } from '../types/common/index.js'
 
 /**
- * The starting value for a run: nothing accumulated, nothing unpriced.
+ * The starting value for a turn: nothing accumulated, nothing unpriced.
  *
  * Carries NO rate fields, and that is load-bearing rather than tidy. It is what
  * lets {@link import('../utils/cost.js').accumulateCost} tell "fresh" from
@@ -9,7 +9,7 @@ import type { CostInfo, TokenUsage } from '../types/common/index.js'
  * no rates AND no unpriced tokens AND a zero total, and no accumulated one can
  * have all three.
  *
- * It also stops reading as a rate card of zero. `inputCostPer1M: 0` on a run
+ * It also stops reading as a rate card of zero. `inputCostPer1M: 0` on a turn
  * nobody has priced says the model is free, which was exactly the confusion
  * `unpricedTokens` was added to end.
  */

package/src/constants/telemetry/index.ts

@@ -42,11 +42,19 @@ export const GENAI = {
 
 	AGENT_NAME: 'gen_ai.agent.name',
 	AGENT_ID: 'gen_ai.agent.id',
+
+	/**
+	 * The conversation a span belongs to. In namzu that is the session: the
+	 * value is the `sessionId`.
+	 */
+	CONVERSATION_ID: 'gen_ai.conversation.id',
 } as const
 
 export const NAMZU = {
-	RUN_ID: 'namzu.run.id',
-	RUN_STATUS: 'namzu.run.status',
+	TURN_ID: 'namzu.turn.id',
+	TURN_STATUS: 'namzu.turn.status',
+	/** Set on a child session's spans: the parent session that delegated it. */
+	SESSION_PARENT_ID: 'namzu.session.parent_id',
 	ITERATION: 'namzu.iteration',
 	TOOL_SUCCESS: 'namzu.tool.success',
 	TOOL_ERROR: 'namzu.tool.error',
@@ -55,24 +63,19 @@ export const NAMZU = {
 	CACHE_WRITE_TOKENS: 'namzu.cache.write_tokens',
 	CACHE_DISCOUNT: 'namzu.cache.discount',
 
-	// Correlation attributes for the run's own logger — see
-	// RunContextFactory.buildLogger (runtime/query/context.ts). RUN_ID above
-	// already covered the run itself; these are the layers above it
-	// (Tenant -> Project -> Thread -> Session -> Run, Convention #17) that
-	// used to reach the run's logger as four bare, un-namespaced keys.
+	// Correlation attributes for a turn's own logger — see
+	// TurnContextFactory.buildLogger (runtime/query/context.ts). TURN_ID above
+	// covers the turn itself; these are the layers above it
+	// (Tenant -> Project -> Topic -> Session -> Turn, Convention #17).
 	SESSION_ID: 'namzu.session.id',
 	THREAD_ID: 'namzu.thread.id',
 	PROJECT_ID: 'namzu.project.id',
 	TENANT_ID: 'namzu.tenant.id',
-	// Set only when a run was started by another run (the sub-agent gateway
-	// path) — see query()'s params.parentRunId in runtime/query/index.ts.
-	// Previously reached the RunContext's own fields but never the logger.
-	RUN_PARENT_ID: 'namzu.run.parent_id',
 
 	// AbstractAgent's per-instance identity (agents/AbstractAgent.ts). The id
 	// half reuses GENAI.AGENT_ID — an agent's id is the same concept whether
 	// it is read off a span or a log record, and GENAI.AGENT_ID already
-	// exists and is already bound at the run's own correlated logger and
+	// exists and is already bound at the turn's own correlated logger and
 	// root span. TYPE has no GENAI analogue, so it is new.
 	AGENT_TYPE: 'namzu.agent.type',
 

package/src/constants/tools/index.ts

@@ -61,8 +61,8 @@ export const DANGEROUS_PATTERNS = [
 export const FILESYSTEM_TOOLS = new Set(['glob', 'read', 'write', 'bash'])
 
 /**
- * Subdirectory of a run directory holding tool output that exceeded the
- * model-visible budget. Kept beside the run so it is cleaned up with the
+ * Subdirectory of a turn directory holding tool output that exceeded the
+ * model-visible budget. Kept beside the turn so it is cleaned up with the
  * run and reachable by the agent through its own `read`/`grep`.
  */
 export const TOOL_OUTPUT_DIR_NAME = 'tool-output'