@namzu/sdk 2.0.0 → 3.0.0

package/src/types/run/memory-promotion.ts

@@ -0,0 +1,112 @@
+import type { RunId } from '../ids/index.js'
+
+/**
+ * What a run learned, offered to whoever decides what is worth keeping.
+ *
+ * namzu could store a memory and could not *form* one. `MemoryStore` and
+ * its disk implementation have been here all along, and the only path
+ * into them is the model calling `save_memory` — so a run that worked out
+ * a durable fact and never thought to write it down lost it at settle,
+ * along with everything the compaction pass had already extracted and
+ * structured on the way.
+ *
+ * The extraction is the part that was already built: the compaction pass
+ * distils the transcript into decisions, discoveries, constraints and
+ * failures precisely because a summary of prose is worth less than a list
+ * of facts. That structure was serialized into one system message and
+ * then dropped on the floor when the run ended.
+ */
+export interface RunMemoryCandidate {
+	readonly runId: RunId
+	/** What the run was asked to do, as the extractor recorded it. */
+	readonly task: string
+	/** Choices the run made and did not revisit. */
+	readonly decisions: readonly string[]
+	/** Things it found out — the shape of a codebase, the name of a table. */
+	readonly discoveries: readonly string[]
+	/** What the user said must hold. The most durable category of the four. */
+	readonly userRequirements: readonly string[]
+	/** Approaches that failed, so a later run does not pay for them again. */
+	readonly failures: readonly string[]
+	/** Facts about the machine, the toolchain, the environment. */
+	readonly environment: readonly string[]
+	/** Files the run touched, by path. */
+	readonly files: readonly string[]
+	/**
+	 * How many entries each capped list dropped during the run.
+	 *
+	 * Carried rather than hidden: a host deciding whether this is worth
+	 * storing should know it is looking at a truncated record.
+	 */
+	readonly evicted: Readonly<Record<string, number>>
+}
+
+/**
+ * Decide what a finished run should leave behind.
+ *
+ * Called once, when the run settles, with everything the compaction pass
+ * extracted. Deliberately a callback rather than a store the runtime
+ * writes into: what is worth remembering is a policy question the host
+ * owns, and a runtime that decided it would be writing a row for every
+ * run whether or not anything happened.
+ *
+ * Never blocks and never fails the run. It runs after the answer is
+ * settled, so a throw is logged and swallowed — a memory that failed to
+ * form must not retract an answer that was already produced. A host that
+ * needs the write to be part of the run's success should do it in its own
+ * code, where it can fail loudly.
+ */
+export type PromoteMemory = (candidate: RunMemoryCandidate) => void | Promise<void>
+
+/**
+ * Project the compaction pass's working state into a promotion candidate.
+ *
+ * A projection rather than the state itself, for the same reason the
+ * plugin hooks got one: the working state is an internal structure with
+ * caps, eviction counters and slot objects that exist to serve
+ * compaction, and handing it over would make every future field of it
+ * part of a host-facing contract by accident.
+ */
+export function toMemoryCandidate(
+	runId: RunId,
+	state: {
+		task: string
+		decisions: string[]
+		discoveries: string[]
+		userRequirements: string[]
+		failures: string[]
+		environment: string[]
+		files: Map<string, unknown>
+		evicted: Record<string, number>
+	},
+): RunMemoryCandidate {
+	return {
+		runId,
+		task: state.task,
+		decisions: [...state.decisions],
+		discoveries: [...state.discoveries],
+		userRequirements: [...state.userRequirements],
+		failures: [...state.failures],
+		environment: [...state.environment],
+		files: [...state.files.keys()],
+		evicted: { ...state.evicted },
+	}
+}
+
+/**
+ * The candidate for this run, or `undefined` when there is nothing to
+ * offer.
+ *
+ * A separate function because "was anything extracted?" is a decision,
+ * and a decision inlined into a `try` is one a test cannot tell apart
+ * from the catch that swallows its failure. Without an extractor there
+ * is no working state, and inventing an empty candidate would ask a host
+ * to store a record of nothing.
+ */
+export function memoryCandidateFor(
+	runId: RunId,
+	manager: { getState(): Parameters<typeof toMemoryCandidate>[1] } | undefined,
+): RunMemoryCandidate | undefined {
+	if (!manager) return undefined
+	return toMemoryCandidate(runId, manager.getState())
+}

package/src/types/run/prepare-step.ts

@@ -0,0 +1,109 @@
+import type { RunId } from '../ids/index.js'
+import type { Message } from '../message/index.js'
+import type { StepResult } from './step.js'
+
+/**
+ * What the loop knows before it calls the model again.
+ *
+ * `stopWhen` (shipped earlier) let a run DECIDE TO STOP based on what the
+ * steps produced. This is the other half of the same idea: deciding how
+ * the next step should be shaped. Without it, a run's tool surface, model
+ * and sampling parameters are fixed at `query()` time, so a phased agent —
+ * research with search tools, then write with file tools, then verify with
+ * a cheaper model — had to be built as three separate runs, each losing
+ * the prior one's context.
+ */
+export interface PrepareStepContext {
+	readonly runId: RunId
+	/** 1-based, matching the iteration number in events and traces. */
+	readonly stepNumber: number
+	/** Full history as it stands, so a decision can read what happened. */
+	readonly messages: readonly Message[]
+	/** Every completed step, in order. */
+	readonly steps: readonly StepResult[]
+
+	/**
+	 * What the stages before this one decided, when several were supplied.
+	 *
+	 * Empty for the first stage, and empty for a single `prepareStep`.
+	 * Reading it is how a later stage refines an earlier one — narrowing a
+	 * tool set that has already been narrowed, or leaving a model alone
+	 * because something upstream had a reason to change it.
+	 */
+	readonly prepared: Readonly<PrepareStepResult>
+}
+
+/**
+ * Overrides for the NEXT step. Every field is optional; an omitted field
+ * keeps the run's configured value, and returning nothing at all is the
+ * same as not supplying a `prepareStep`.
+ */
+export interface PrepareStepResult {
+	/**
+	 * Restrict which tools the model may call this step, by name. Names
+	 * that are not registered are dropped with a warning rather than
+	 * failing the run — a phase list that outlives a tool rename should
+	 * narrow the surface, not kill the agent mid-run.
+	 *
+	 * **This costs a prompt-cache prefix.** Tools render at position 0, so
+	 * changing the set between steps invalidates the cached prefix for that
+	 * step. That is inherent to narrowing, not an implementation detail, so
+	 * it is worth doing when a phase boundary genuinely changes what the
+	 * agent should reach for — and not worth doing every step.
+	 *
+	 * Note it does NOT touch `tool_choice`. Not every provider has an `allowed_tools`
+	 * parameter, and moving `tool_choice` invalidates cached MESSAGE blocks
+	 * as well — a strictly worse trade for the same effect.
+	 */
+	readonly activeTools?: readonly string[]
+
+	/** Use a different model for this step. */
+	readonly model?: string
+
+	/**
+	 * Guidance for this step ONLY, appended as a system message that is not
+	 * retained afterwards.
+	 *
+	 * Kept separate from the run's system prompt on purpose: the prompt is
+	 * the cached prefix, and rewriting it per step would bust the cache on
+	 * every iteration for what is usually one sentence of phase direction.
+	 */
+	readonly system?: string
+
+	readonly temperature?: number
+	readonly maxResponseTokens?: number
+}
+
+/**
+ * Called before each model call, with everything the run has produced so
+ * far.
+ *
+ * A throw fails OPEN — the step proceeds with the run's configured values.
+ * Same reasoning as `stopWhen` and deliberately opposite to a guardrail: a
+ * broken step-shaping hook should not kill an otherwise healthy run, and
+ * unlike a safety check, nothing unsafe gets through when it is skipped.
+ */
+export type PrepareStep = (
+	context: PrepareStepContext,
+) => PrepareStepResult | undefined | Promise<PrepareStepResult | undefined>
+
+/**
+ * One shaping stage, or several applied in order.
+ *
+ * A single slot is enough for one concern and no help with two. A host
+ * with a per-tenant system prefix AND a cost-based model downgrade had to
+ * hand-compose them into one callback, which puts the ordering in the
+ * host's code where nothing can see it and makes each concern's failure
+ * the other's problem.
+ *
+ * An ARRAY is ordered by declaration, not by registration. That
+ * distinction is the whole reason this is safe where a plugin-style
+ * fan-out would not be: the author writes the order down, so "who wins"
+ * is a line of their code rather than an accident of install history.
+ * Each stage sees what the ones before it decided, and a later stage
+ * overrides a field an earlier one set — last writer wins, visibly.
+ *
+ * A stage that throws is skipped and the rest still run, so one broken
+ * concern cannot silently disable the others.
+ */
+export type PrepareStepChain = PrepareStep | readonly PrepareStep[]

package/src/types/run/state.ts

@@ -0,0 +1,111 @@
+import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
+import type { CheckpointId, PendingDecision } from '../hitl/index.js'
+import type { RunId, SessionId, TenantId } from '../ids/index.js'
+import type { Message } from '../message/index.js'
+import type { ProjectId, ThreadId } from '../session/ids.js'
+import type { StopReason } from './stop-reason.js'
+
+/**
+ * Everything needed to pick a run back up in a DIFFERENT process.
+ *
+ * A run's live state was spread across objects that only exist in memory —
+ * `RunPersistence`, `GuardCoordinator`, the suspended `await` inside a HITL
+ * gate. `IterationCheckpoint` carries the history and the budgets, but it
+ * is keyed by a store scope the reader has to already know, and it says
+ * nothing about the run's status or why it stopped. So "resume this run"
+ * meant "the original process is still alive and holding it".
+ *
+ * That is the constraint this removes. `RunState` is a flat, JSON-safe
+ * snapshot: a serverless handler writes one when a run parks, returns, and
+ * a later invocation — a different container — reads it back and continues.
+ *
+ * It is a SNAPSHOT, not a live handle. Nothing in it points at a socket, a
+ * sandbox, a provider client, or an open file. Re-establishing those is the
+ * host's job on the way back in, which is exactly why they are absent.
+ */
+export interface RunState {
+	/**
+	 * Schema version. Bumped when the shape changes incompatibly, so a
+	 * host that stored a snapshot with an older SDK gets a clear failure
+	 * from {@link parseRunState} instead of a partial restore.
+	 */
+	readonly version: 1
+
+	readonly runId: RunId
+	readonly sessionId: SessionId
+	readonly threadId: ThreadId
+	readonly projectId: ProjectId
+	readonly tenantId: TenantId
+	/** Present for sub-runs, so a hierarchical store can key the snapshot. */
+	readonly parentRunId?: RunId
+
+	readonly agentId?: string
+	readonly agentName?: string
+
+	readonly status: AgentStatus
+	readonly stopReason?: StopReason
+	readonly lastError?: string
+
+	readonly messages: Message[]
+	readonly tokenUsage: TokenUsage
+	readonly costInfo: CostInfo
+	readonly currentIteration: number
+	readonly startedAt: number
+	/**
+	 * Wall-clock the run has already consumed. Restored into the guard so a
+	 * resumed run does not get a fresh timeout budget — the timeout is a
+	 * property of the RUN, not of the process hosting it.
+	 */
+	readonly elapsedMs: number
+
+	/**
+	 * The checkpoint this snapshot corresponds to, when one was written.
+	 * Pass it as `resumeFromCheckpoint`.
+	 */
+	readonly checkpointId?: CheckpointId
+
+	/**
+	 * The decision the run is parked on, if any. A host reads this to know
+	 * what to ask a human, and feeds the answer back as
+	 * `QueryParams.pendingDecision`.
+	 */
+	readonly pending?: PendingDecision
+
+	readonly capturedAt: number
+}
+
+/** Thrown by {@link parseRunState} when a snapshot cannot be trusted. */
+export class RunStateVersionError extends Error {
+	constructor(
+		readonly found: unknown,
+		readonly expected: number,
+	) {
+		super(
+			`RunState version mismatch: snapshot declares ${JSON.stringify(found)}, this SDK reads ${expected}. Restoring across an incompatible version would silently drop fields; re-run instead.`,
+		)
+		this.name = 'RunStateVersionError'
+	}
+}
+
+export const RUN_STATE_VERSION = 1 as const
+
+/**
+ * Parse a serialized snapshot, refusing anything this SDK cannot fully
+ * restore.
+ *
+ * The version guard is the point. A snapshot is written by one deployment
+ * and read by another, possibly weeks later and possibly after an SDK
+ * upgrade; a silent partial restore there produces a run that looks healthy
+ * and has lost its budgets. Failing loudly is the only honest option.
+ */
+export function parseRunState(json: string | unknown): RunState {
+	const raw: unknown = typeof json === 'string' ? JSON.parse(json) : json
+	if (typeof raw !== 'object' || raw === null) {
+		throw new RunStateVersionError(raw, RUN_STATE_VERSION)
+	}
+	const version = (raw as { version?: unknown }).version
+	if (version !== RUN_STATE_VERSION) {
+		throw new RunStateVersionError(version, RUN_STATE_VERSION)
+	}
+	return raw as RunState
+}

package/src/types/run/step.ts

@@ -0,0 +1,95 @@
+import type { CostInfo, TokenUsage } from '../common/index.js'
+import type { MessageId } from '../ids/index.js'
+import type { ToolCall } from '../message/index.js'
+
+/**
+ * What one iteration of the agent loop did.
+ *
+ * None of this was reachable before. `Run` and `BaseAgentResult` have no
+ * `steps[]`, so a host that persisted the returned `Run` — the natural
+ * thing — permanently lost per-step attribution: answering "which step
+ * cost the most" meant correlating raw `RunEvent`s by iteration number and
+ * diffing cumulative counters, and per-tool duration was never emitted at
+ * all. Every field here was already computed somewhere in the loop.
+ */
+export interface StepResult {
+	/** 1-based, matching `iteration` on the run events. */
+	stepNumber: number
+	model: string
+	messageId: MessageId
+	/** Assistant text for this step, if any. */
+	content: string | null
+	toolCalls: readonly ToolCall[]
+	/** Tool outcomes, in the same order as `toolCalls`. */
+	toolResults: readonly StepToolResult[]
+	finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter'
+	/** Usage for THIS step, not the run's cumulative total. */
+	usage: TokenUsage
+	/** Cost delta attributable to this step. Zero without a pricing table. */
+	costDelta: CostInfo
+	startedAt: number
+	/** Wall-clock for the whole step, including tool execution. */
+	durationMs: number
+	/** Portion of `durationMs` spent inside tools. */
+	toolExecutionMs: number
+}
+
+export interface StepToolResult {
+	toolCallId: string
+	toolName: string
+	/** Text form, after the model-visible output budget was applied. */
+	output: string
+	isError: boolean
+	durationMs: number
+}
+
+/**
+ * A programmable halt condition, evaluated after each step's tools have
+ * run.
+ *
+ * `GuardCoordinator` — the only halt before this — consumes
+ * `{aborted, totalTokens, totalCost, currentIteration, startTime}` and
+ * never sees messages, tool calls or results. So "stop after three steps
+ * with no progress" and "stop once the plan is complete" were
+ * inexpressible, and a terminal `submit_answer` tool could not end the
+ * run: the model had to be prompt-begged to stop, with `maxIterations:
+ * 200` as the only backstop.
+ *
+ * Returning `true` ends the run with `stop_reason: 'stop_condition'`.
+ */
+export type StopCondition = (state: StopConditionState) => boolean | Promise<boolean>
+
+export interface StopConditionState {
+	/** Every step so far, most recent last. */
+	readonly steps: readonly StepResult[]
+	readonly latestStep: StepResult
+	readonly totalUsage: TokenUsage
+	readonly totalCost: CostInfo
+}
+
+/** Stop once `n` steps have completed. */
+export function stepCountIs(n: number): StopCondition {
+	return ({ steps }) => steps.length >= n
+}
+
+/**
+ * Stop when the latest step called any of `names`.
+ *
+ * The tool still executes and its result is still recorded — the run ends
+ * after, not instead. That is what makes a `submit_answer` / `verify` tool
+ * usable as a terminator without losing its output.
+ */
+export function hasToolCall(...names: string[]): StopCondition {
+	const wanted = new Set(names)
+	return ({ latestStep }) => latestStep.toolCalls.some((tc) => wanted.has(tc.function.name))
+}
+
+/** Stop when any of the given conditions does. */
+export function anyOf(...conditions: StopCondition[]): StopCondition {
+	return async (state) => {
+		for (const condition of conditions) {
+			if (await condition(state)) return true
+		}
+		return false
+	}
+}

package/src/types/run/stop-reason.ts

@@ -6,13 +6,31 @@ export type StopReason =
 	| 'max_iterations'
 	| 'cancelled'
 	| 'plan_rejected'
+	/** A caller-supplied `stopWhen` predicate returned true. */
+	| 'stop_condition'
+	/** The model never produced a valid structured output within its retries. */
+	| 'structured_output_failed'
+	/**
+	 * A host reviewer kept rejecting the answer and the run ran out of
+	 * attempts.
+	 *
+	 * Distinct from a budget stop on purpose: without it the run would end
+	 * on `max_iterations` or a token cap, naming the resource it exhausted
+	 * rather than the judgement that exhausted it — and the reader would go
+	 * looking for a loop instead of at the reviewer.
+	 */
+	| 'answer_rejected'
+	/** An input guardrail refused the run before it started. */
+	| 'input_guardrail'
+	/** An output guardrail refused the produced result. */
+	| 'output_guardrail'
 	| 'paused'
 	| 'error'
 
 /**
  * Per-LLM-message stop reason — distinct from the run-level {@link StopReason}.
  *
- * Mirrors the union of Anthropic and OpenAI finish reasons normalised into a
+ * The union of the finish reasons providers report, normalised into a
  * provider-agnostic vocabulary. `forced_finalize` is a Namzu-specific value
  * emitted by the orchestrator when iteration limits force a final response
  * without a model-issued stop reason.
@@ -25,3 +43,13 @@ export type MessageStopReason =
 	| 'pause_turn'
 	| 'refusal'
 	| 'forced_finalize'
+	/**
+	 * The turn was cancelled mid-stream.
+	 *
+	 * Also Namzu-specific, and added because the cancel path had no way to
+	 * close the message it had opened: it re-threw from inside the chunk
+	 * loop, so the terminal event never fired and a host consuming the
+	 * message lifecycle saw a message begin and never end. A turn that
+	 * stops is still a turn that finished streaming, whatever stopped it.
+	 */
+	| 'cancelled'

package/src/types/sandbox/index.ts

@@ -32,6 +32,32 @@ export function assertSandboxStatus(status: SandboxStatus): void {
 
 export type SandboxEnvironment = 'linux-namespace' | 'macos-seatbelt' | 'basic'
 
+/**
+ * A security control a sandbox tier either provides or does not.
+ *
+ * The environment name alone does not say what a caller actually gets:
+ * one tier denies the network outright while another leaves the host
+ * filesystem fully visible, and both used to answer to the same provider
+ * name. A caller that turned isolation on for a reason needs to state
+ * which control it is relying on, so a host that cannot supply it can
+ * refuse instead of quietly handing back less.
+ *
+ *  - `filesystem` — the spawned process cannot read or write outside the
+ *    sandbox root.
+ *  - `network` — the spawned process cannot reach the network.
+ *  - `process` — the spawned process cannot see or signal host processes.
+ */
+export type SandboxIsolationControl = 'filesystem' | 'network' | 'process'
+
+export const SANDBOX_ISOLATION_CONTROLS: readonly SandboxIsolationControl[] = [
+	'filesystem',
+	'network',
+	'process',
+]
+
+/** What a tier actually enforces, per control. */
+export type SandboxIsolationReport = Readonly<Record<SandboxIsolationControl, boolean>>
+
 export function assertSandboxEnvironment(env: SandboxEnvironment): void {
 	switch (env) {
 		case 'linux-namespace':
@@ -56,6 +82,17 @@ export interface SandboxExecResult {
 	readonly signal?: string
 	readonly timedOut: boolean
 	readonly durationMs: number
+	/**
+	 * Set when the backend clipped the stream at its output cap.
+	 *
+	 * The firecracker protocol already computed these, but they had no slot
+	 * in this contract, so they were dropped at the type boundary and the
+	 * model saw a complete-looking result that had silently lost its tail —
+	 * against the kernel's own convention that it does not truncate
+	 * silently.
+	 */
+	readonly stdoutTruncated?: boolean
+	readonly stderrTruncated?: boolean
 }
 
 // ---------------------------------------------------------------------------
@@ -66,6 +103,15 @@ export interface SandboxExecOptions {
 	readonly timeout?: number
 	readonly env?: Record<string, string>
 	readonly cwd?: string
+	/**
+	 * Cancellation for the command. A backend that honours it kills the
+	 * process; one that does not simply ignores it, so this is additive.
+	 *
+	 * Without it a Stop (or a per-tool deadline) could only ever abandon
+	 * the *wait* — the sandboxed process kept running after the host
+	 * believed the run had been cancelled.
+	 */
+	readonly signal?: AbortSignal
 }
 
 // ---------------------------------------------------------------------------
@@ -87,16 +133,44 @@ export interface SandboxFileEntry {
 // Sandbox interface — the core abstraction
 // ---------------------------------------------------------------------------
 
+/**
+ * A network policy applied to a LIVE sandbox.
+ *
+ * The whole point is that it can change mid-life. The common shape —
+ * "fetch the repository with a token, then drop to deny-all before running
+ * anything the repository contains" — was not expressible at all: the
+ * policy was frozen at provider construction, so a host had to build a
+ * second provider and a second sandbox, copying the work across.
+ */
+export interface SandboxNetworkPolicy {
+	/**
+	 * Hosts the sandbox may reach. Empty denies everything.
+	 *
+	 * `api.example.com` matches that host; `.example.com` matches the
+	 * domain and its subdomains. Substring matching is deliberately not
+	 * offered — `example.com` as a substring would admit
+	 * `example.com.attacker.net`.
+	 */
+	readonly allowedHosts: readonly string[]
+}
+
 export interface Sandbox {
 	readonly id: SandboxId
 	readonly status: SandboxStatus
 	readonly rootDir: string
 	readonly environment: SandboxEnvironment
 	exec(command: string, args?: string[], opts?: SandboxExecOptions): Promise<SandboxExecResult>
+
 	/**
-	 * Atomically replace the destination body: readers must observe either the
-	 * previous complete body or the new complete body, never a truncated file.
+	 * Narrow or widen what this sandbox can reach, while it is running.
+	 *
+	 * Optional, and a backend that cannot enforce it must **throw** rather
+	 * than accept and ignore. A network policy that is accepted and not
+	 * applied is worse than one that was never offered: the caller stops
+	 * looking, and the run proceeds believing it is confined. That is the
+	 * same rule the tiered sandbox provider follows, for the same reason.
 	 */
+	setNetworkPolicy?(policy: SandboxNetworkPolicy): Promise<void>
 	writeFile(path: string, content: string | Buffer): Promise<void>
 	readFile(path: string): Promise<Buffer>
 	/**
@@ -128,10 +202,10 @@ export interface Sandbox {
 //
 // Why the `Container` prefix on these types: the layout shape encodes
 // container-tier semantics (bind-mount sources, `/mnt/...` container
-// paths, RW outputs surface). MicroVM tiers (e2b, fly-machines,
-// firecracker-containerd) carry layout-equivalent state that does
-// not map onto bind-mount flags — managed snapshots, attached
-// volumes, registry-pulled rootfs. Naming the public type
+// paths, RW outputs surface). A microVM tier carries
+// layout-equivalent state that does not map onto bind-mount flags —
+// snapshots, attached volumes, a rootfs pulled from a registry.
+// Naming the public type
 // `SandboxLayout` would either (a) make every future microVM adapter
 // pretend its volume model fits a bind-mount shape, or (b) force a
 // breaking rename when we add `MicroVMSandboxLayout` later. Naming
@@ -203,9 +277,9 @@ export interface ContainerSandboxLayoutMount {
 }
 
 /**
- * Declarative multi-mount taxonomy for a CONTAINER sandbox. Mirrors
- * the layout Anthropic's container architecture exposes to the model
- * (Claude container blueprint, Code Interpreter, "skills"):
+ * Declarative multi-mount taxonomy for a CONTAINER sandbox. A container
+ * needs one place the user will see and several the user will not, and
+ * the difference has to be legible to the model from the path alone:
  *
  *  - `outputs` — RW bind. User-visible output surface that the
  *    user consumes after the run. Default container path
@@ -248,7 +322,7 @@ export interface ContainerSandboxLayout {
 	 * not a child of it: the output collector / output watcher
 	 * scans `outputs` only, so anything the agent writes under
 	 * `scratch` is invisible to the user by construction. Mirrors the
-	 * Anthropic Cowork pattern (`/home/claude` as scratch vs.
+	 * separation between scratch space (invisible to the collector) and
 	 * `/mnt/user-data/outputs` as the user-visible output area).
 	 * Hosts that don't need a separate scratch mount may omit this.
 	 */
@@ -312,7 +386,7 @@ export interface SandboxCreateConfig {
  * Putting layout on `SandboxCreateConfig` would let the SDK runtime
  * (`drainQuery`) call `provider.create()` without it and trigger a
  * runtime validation failure that the type system cannot catch — a
- * trap Codex flagged in the second review round. Hosts spawning a
+ * trap flagged in the second review round. Hosts spawning a
  * sandbox per task construct one provider per task too; the same
  * closure that knows the per-task `hostPath`s is the one that calls
  * `createSandboxProvider`.
@@ -339,7 +413,14 @@ export const SandboxConfigSchema = z.object({
 	timeoutMs: z.number().positive().default(SANDBOX_DEFAULT_TIMEOUT_MS),
 	memoryLimitMb: z.number().positive().default(SANDBOX_DEFAULT_MEMORY_LIMIT_MB),
 	maxProcesses: z.number().positive().default(SANDBOX_DEFAULT_MAX_PROCESSES),
-	cleanupOnDestroy: z.boolean().default(true),
+	/**
+	 * Controls the run depends on. Provider construction throws when the
+	 * host cannot enforce one of them. Empty by default, which keeps
+	 * best-effort behaviour for callers that never asked for a guarantee —
+	 * but a caller that did ask now gets it or gets an error, never a
+	 * quiet downgrade.
+	 */
+	requireIsolation: z.array(z.enum(['filesystem', 'network', 'process'])).default([]),
 })
 
 export type SandboxConfig = z.infer<typeof SandboxConfigSchema>

package/src/types/structured-output/index.ts

@@ -14,12 +14,13 @@ export interface StructuredOutputConfig<TSchema extends z.ZodType = z.ZodType> {
 	schema: TSchema
 
 	/**
-	 * Whether to force the model to use the structured_output tool.
-	 * When true, sets tool_choice to force the tool.
-	 * When false, the model may choose to call it or not.
-	 * Default: true
+	 * Turns spent re-prompting when the model answers in prose or fails
+	 * validation. Defaults to {@link DEFAULT_STRUCTURED_OUTPUT_RETRIES}.
+	 *
+	 * Bounded so a model that cannot satisfy the schema fails loudly rather
+	 * than iterating against `maxIterations`.
 	 */
-	enforceToolChoice?: boolean
+	maxRetries?: number
 }
 
 /**

package/src/types/thread/entity.ts

@@ -44,9 +44,8 @@ export type ThreadStatus = 'open' | 'archived'
  * - **Sessions are the immediate work unit.** A user or agent enters a
  *   Thread and opens/resumes Sessions for the concrete interval of work.
  *
- * This is the mental model ses_001 ratified (Phase 0, 2026-04-18). Industry
- * frameworks (OpenAI Responses, LangGraph, Claude Agent SDK, Temporal) do
- * not have an exact analogue for the Thread layer — it is Namzu's answer to
+ * This is the mental model ses_001 ratified (Phase 0, 2026-04-18). The
+ * Thread layer has no counterpart elsewhere — it is Namzu's answer to
  * the question "how do you expose a multi-session topic to A2A without
  * coupling it to the Project's filesystem identity?".
  *