@demicodes/agent 0.10.1 → 0.10.3

package/dist/index.mjs

@@ -1,15 +1,14 @@
-import { a as cloneBlocks, i as applyTranscriptPatches, n as createWebSocketServerTransport, o as ProviderStreamError, r as AgentClient, s as isContextLengthExceeded, t as createWebSocketClientTransport } from "./websocket-transport-os0mfcLi.mjs";
-import { AbortError, abortable, asError, asRecord, asString, bytesToBase64, createId, delay, isAbortError, isRecord, noop, parseJsonOrString, safeJsonStringify, throwIfAborted, truncate } from "@demicodes/utils";
+import { a as cloneBlocks, i as applyTranscriptPatches, n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-Bod0puog.mjs";
+import { AbortError, abortable, asError, asRecord, asString, createId, delay, isAbortError, isRecord, noop, parseJsonOrString, safeJsonStringify, throwIfAborted, truncate } from "@demicodes/utils";
 import { BashEnvironment, CommandRegistry, MAX_TIMEOUT_MS, heredocDelimiter, shellQuote } from "@demicodes/shell";
 import { providerRuntime } from "@demicodes/provider";
-import { modelAcceptsMediaType, sniffModelMediaType } from "@demicodes/core";
 //#region src/transcript.ts
 const DEFAULT_MODEL_TEXT_HEAD_CHARS = 8e3;
 const DEFAULT_MODEL_TEXT_TAIL_CHARS = 8e3;
 const IMAGE_BASE_TOKENS = 1600;
 const IMAGE_BYTES_PER_TOKEN = 1e3;
 const DOCUMENT_BYTES_PER_TOKEN = 4;
-var TranscriptLog = class {
+var Transcript = class {
 	blocks;
 	idFactory;
 	now;
@@ -24,7 +23,7 @@ var TranscriptLog = class {
 		this.replayHeadChars = options.replayTextBounds?.headChars ?? DEFAULT_MODEL_TEXT_HEAD_CHARS;
 		this.replayTailChars = options.replayTextBounds?.tailChars ?? DEFAULT_MODEL_TEXT_TAIL_CHARS;
 	}
-	toJSON() {
+	snapshot() {
 		return { blocks: structuredClone(this.blocks) };
 	}
 	/** Monotonic revision, advanced once per drained patch batch. */
@@ -149,22 +148,6 @@ var TranscriptLog = class {
 		}
 		return null;
 	}
-	/**
-	* Drops the blocks from `index` onward, returning true when anything went.
-	* Used to unwind a turn to its resume point before re-inferring.
-	*/
-	truncateFrom(index) {
-		let changed = false;
-		for (let i = this.blocks.length - 1; i >= index; i -= 1) {
-			this.blocks.splice(i, 1);
-			this.record({
-				op: "remove",
-				path: ["blocks", i]
-			});
-			changed = true;
-		}
-		return changed;
-	}
 	applyProviderEvent(model, event) {
 		switch (event.type) {
 			case "thinking_start": return this.appendThinking(model, "");
@@ -189,7 +172,7 @@ var TranscriptLog = class {
 				status: "executing",
 				streamingOutput: [],
 				output: [],
-				view: null
+				metadata: null
 			});
 			case "response": return this.appendBlock({
 				type: "response",
@@ -204,20 +187,19 @@ var TranscriptLog = class {
 				createdAt: this.now(),
 				model,
 				message: event.message,
-				code: event.code,
-				...event.diagnostics ? { diagnostics: event.diagnostics } : {}
+				code: event.code
 			});
 			case "abort": return this.pushAbort(model);
 		}
 	}
-	completeToolCall(toolUseId, output, isError = false, view = null) {
+	completeToolCall(toolUseId, output, isError = false, metadata = null) {
 		const index = findPendingToolCallIndex(this.blocks, toolUseId);
 		if (index === null) return null;
 		const block = this.blocks[index];
 		block.status = isError ? "error" : "completed";
 		block.output = output;
 		block.streamingOutput = [];
-		block.view = view;
+		block.metadata = metadata;
 		this.recordBlockReplace(index);
 		return block;
 	}
@@ -396,15 +378,9 @@ var TranscriptLog = class {
 	* history), it anchors the estimate and only blocks streamed after it are
 	* char-estimated; otherwise the whole replay window is estimated at ~4
 	* chars/token with fixed weights for images and documents.
-	*
-	* When `contextWindow` is given, an anchor larger than the window is
-	* discarded: a single request's usage physically cannot exceed the window,
-	* so such a value is a provider violation of the response-usage contract
-	* (e.g. a turn-cumulative total) and would poison the estimate.
 	*/
-	estimateContextTokens(contextWindow) {
-		let anchor = this.usageAnchor();
-		if (anchor !== null && contextWindow !== void 0 && contextWindow > 0 && anchor.tokens > contextWindow) anchor = null;
+	estimateContextTokens() {
+		const anchor = this.usageAnchor();
 		if (anchor === null) return this.replayableBlocks().reduce((total, block) => total + estimateBlockTokens(block), 0);
 		let total = anchor.tokens;
 		for (let i = anchor.blockIndex + 1; i < this.blocks.length; i += 1) total += estimateBlockTokens(this.blocks[i]);
@@ -555,7 +531,6 @@ function stringifyUserContent(content) {
 	switch (content.type) {
 		case "text": return content.text;
 		case "image": return content.source.type === "url" ? content.source.url : content.source.mediaType;
-		case "video": return content.source.type === "url" ? content.source.url : content.source.mediaType;
 		case "document": return `${content.source.fileName} ${content.source.mediaType}`;
 		case "reference": return content.reference;
 	}
@@ -564,7 +539,6 @@ function stringifyToolResult(content) {
 	switch (content.type) {
 		case "text": return content.text;
 		case "image": return content.source.mediaType;
-		case "video": return content.source.mediaType;
 	}
 }
 function boundUserContent(content, headChars, tailChars) {
@@ -620,57 +594,6 @@ function retryDelayMs(policy, attempt, retryAfterMs) {
 	return Math.floor(Math.random() * ceiling);
 }
 //#endregion
-//#region src/recovery.ts
-/**
-* Whether a block is a leftover of the failed attempt that nobody can have acted on.
-*
-* Everything else has to be assumed acted on. Transcript blocks stream outward as
-* they are produced and products turn them into effects that cannot be recalled —
-* rendering them, posting them to a chat, executing the tool they describe. A tool
-* call counts whatever its status: one still marked executing outlived the process
-* that was running it, so whether its effect landed is unknown, and unknown has to
-* be treated as landed. An abort block is history the user created, not a leftover.
-*
-* Thinking is the interesting case: products display it, but nothing keys off it and
-* a rerun simply reasons again, so it is discardable. A `response` is not — it
-* records a provider request that did complete, and its usage anchors the context
-* estimate for everything after it.
-*/
-function isDiscardableLeftover(block) {
-	switch (block.type) {
-		case "thinking":
-		case "redacted_thinking":
-		case "error": return true;
-		case "text": return block.text.trim().length === 0;
-		default: return false;
-	}
-}
-/**
-* Finds how far back an unfinished turn can be unwound before re-inferring.
-*
-* This is the single decision behind both recovery paths. A transient provider
-* failure and a human asking to continue a dead round ask the same question — how
-* do we finish this turn — and the answer depends only on what has already left
-* the process, never on which of the two asked or on how the turn died.
-*/
-function findResumePoint(blocks) {
-	for (let i = blocks.length - 1; i >= 0; i -= 1) {
-		const block = blocks[i];
-		if (block.type === "user") return {
-			cut: i + 1,
-			isFullRerun: true
-		};
-		if (!isDiscardableLeftover(block)) return {
-			cut: i + 1,
-			isFullRerun: false
-		};
-	}
-	return {
-		cut: blocks.length,
-		isFullRerun: false
-	};
-}
-//#endregion
 //#region src/yield-scheduler.ts
 /**
 * Tracks scheduled `yield` wakeups and their timers. This class owns only the
@@ -689,15 +612,14 @@ var YieldScheduler = class {
 		return this.pending.length > 0;
 	}
 	/** Registers a new (unarmed) wakeup and returns its id. */
-	schedule(durationMs, metadata) {
+	schedule(durationMs) {
 		const id = this.idFactory();
 		this.pending.push({
 			id,
 			durationMs,
 			timer: null,
 			dueAt: null,
-			armed: false,
-			metadata
+			armed: false
 		});
 		return id;
 	}
@@ -708,7 +630,7 @@ var YieldScheduler = class {
 			if (wakeup.armed) continue;
 			wakeup.armed = true;
 			wakeup.dueAt = now + wakeup.durationMs;
-			wakeup.timer = setTimeout(() => this.onFire(wakeup.id, wakeup.metadata), wakeup.durationMs);
+			wakeup.timer = setTimeout(() => this.onFire(wakeup.id), wakeup.durationMs);
 		}
 	}
 	/** Removes the wakeup with `wakeupId` (clearing its timer); returns whether it existed. */
@@ -867,6 +789,21 @@ function buildCompactionSummaryRequest(rendered, context) {
 	};
 }
 //#endregion
+//#region src/provider-stream-error.ts
+/** Error carrying a provider stream's error code (e.g. `context_length_exceeded`). */
+var ProviderStreamError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.name = "ProviderStreamError";
+		this.code = code;
+	}
+};
+/** Whether an error is a provider stream error reporting the context window was exceeded. */
+function isContextLengthExceeded(error) {
+	return error instanceof ProviderStreamError && error.code === "context_length_exceeded";
+}
+//#endregion
 //#region src/compaction-controller.ts
 /**
 * Owns the compaction algorithm: pick a window of old transcript blocks, summarize
@@ -883,9 +820,9 @@ var CompactionController = class {
 		const contextWindow = targetModel.model.contextWindow;
 		if (contextWindow <= 0) return;
 		const threshold = Math.floor(contextWindow * this.host.thresholdRatio);
-		if (this.host.transcript.estimateContextTokens(contextWindow) < threshold) return;
+		if (this.host.transcript.estimateContextTokens() < threshold) return;
 		await this.host.runWithCompactingPhase(async () => {
-			for (let attempt = 0; attempt < 8 && this.host.transcript.estimateContextTokens(contextWindow) >= threshold; attempt += 1) if (!await this.run()) break;
+			for (let attempt = 0; attempt < 8 && this.host.transcript.estimateContextTokens() >= threshold; attempt += 1) if (!await this.run()) break;
 		});
 	}
 	/** Runs one compaction pass before a turn when the current model is over threshold. */
@@ -893,7 +830,7 @@ var CompactionController = class {
 		const contextWindow = this.host.model.model.contextWindow;
 		if (contextWindow <= 0) return;
 		const threshold = Math.floor(contextWindow * this.host.thresholdRatio);
-		if (this.host.transcript.estimateContextTokens(contextWindow) < threshold) return;
+		if (this.host.transcript.estimateContextTokens() < threshold) return;
 		await this.host.runWithCompactingPhase(() => this.run());
 	}
 	/** Runs one compaction pass; returns whether it compacted anything. */
@@ -923,7 +860,7 @@ var CompactionController = class {
 		return false;
 	}
 	async generateSummary(blocks) {
-		const rendered = renderItemsForSummary(new TranscriptLog(blocks).collectInferenceItems());
+		const rendered = renderItemsForSummary(new Transcript(blocks).collectInferenceItems());
 		const policy = this.host.retryPolicy;
 		for (let attempt = 1;; attempt += 1) {
 			const request = buildCompactionSummaryRequest(rendered, {
@@ -942,16 +879,10 @@ var CompactionController = class {
 				if (event.type === "text_delta") summary += event.text;
 				if (event.type === "abort") throw new AbortError();
 				if (event.type === "error") {
-					const diagnostics = {
-						source: event.diagnostics?.source ?? "unknown",
-						...event.diagnostics,
-						clientRequestId: request.requestId
-					};
-					if (!(summary.length === 0 && attempt < policy.maxAttempts && isRetryableCode(policy, event.code))) throw new ProviderStreamError(event.message, event.code, diagnostics);
+					if (!(summary.length === 0 && attempt < policy.maxAttempts && isRetryableCode(policy, event.code))) throw new ProviderStreamError(event.message, event.code);
 					transient = {
 						code: event.code,
-						retryAfterMs: event.retryAfterMs ?? null,
-						diagnostics
+						retryAfterMs: event.retryAfterMs ?? null
 					};
 					break;
 				}
@@ -962,8 +893,7 @@ var CompactionController = class {
 				type: "retry_scheduled",
 				attempt,
 				delayMs,
-				code: transient.code,
-				diagnostics: transient.diagnostics
+				code: transient.code
 			});
 			await abortable(delay(delayMs), request.cancel);
 		}
@@ -986,7 +916,6 @@ var ProviderTurnLoop = class {
 		let autoCompactions = 0;
 		while (true) {
 			throwIfAborted(this.host.currentSignal());
-			await this.host.materializePendingSteers();
 			const steerContinuationBeforeStream = this.host.steerContinuationCount;
 			const shouldAutoRecover = await this.streamProviderOnce();
 			throwIfAborted(this.host.currentSignal());
@@ -1011,9 +940,8 @@ var ProviderTurnLoop = class {
 	}
 	/**
 	* Streams one provider response, silently retrying transient failures
-	* (rate_limit/overloaded) with backoff. A retry is taken only when everything
-	* the failed attempt put in the transcript can be unwound — the same question
-	* `resume` asks, so an automatic recovery and a human-driven one never disagree.
+	* (rate_limit/overloaded) with backoff — but only while the attempt has
+	* produced no transcript content, so a retry can never duplicate output.
 	* The turn stays in provider_streaming across backoff waits so steers keep
 	* queueing instead of being rejected.
 	*/
@@ -1028,8 +956,7 @@ var ProviderTurnLoop = class {
 					type: "retry_scheduled",
 					attempt: outcome.attempt,
 					delayMs: outcome.delayMs,
-					code: outcome.code,
-					diagnostics: outcome.diagnostics
+					code: outcome.code
 				});
 				await abortable(delay(outcome.delayMs), this.host.currentSignal());
 			}
@@ -1039,47 +966,26 @@ var ProviderTurnLoop = class {
 	}
 	async streamAttempt(attempt, policy) {
 		const request = this.buildInferenceRequest();
-		const attemptStart = this.host.transcript.blocks.length;
 		const run = this.host.provider.run(request);
 		let shouldAutoRecover = false;
-		let hasPendingThinkingStart = false;
+		let produced = false;
 		this.host.setActiveProviderRun(run);
 		try {
 			for await (const event of this.host.streamProvider(request, run)) {
 				throwIfAborted(request.cancel);
 				if (event.type === "abort") throw new AbortError();
-				if (event.type === "thinking_start") {
-					hasPendingThinkingStart = true;
-					continue;
-				}
 				if (event.type === "error") {
-					const diagnostics = {
-						source: event.diagnostics?.source ?? "unknown",
-						...event.diagnostics,
-						clientRequestId: request.requestId
-					};
-					const errorEvent = {
-						...event,
-						diagnostics
+					if (!produced && attempt < policy.maxAttempts && isRetryableCode(policy, event.code)) return {
+						type: "retry",
+						attempt,
+						delayMs: retryDelayMs(policy, attempt, event.retryAfterMs ?? null),
+						code: event.code
 					};
-					if (findResumePoint(this.host.transcript.blocks).cut <= attemptStart && attempt < policy.maxAttempts && isRetryableCode(policy, errorEvent.code)) {
-						if (this.host.transcript.truncateFrom(attemptStart)) await this.host.commitTranscript();
-						return {
-							type: "retry",
-							attempt,
-							delayMs: retryDelayMs(policy, attempt, errorEvent.retryAfterMs ?? null),
-							code: errorEvent.code,
-							diagnostics: errorEvent.diagnostics
-						};
-					}
-					await this.applyProviderEvent(errorEvent);
-					throw new ProviderStreamError(errorEvent.message, errorEvent.code, errorEvent.diagnostics);
-				}
-				if (hasPendingThinkingStart) {
-					await this.applyProviderEvent({ type: "thinking_start" });
-					hasPendingThinkingStart = false;
+					await this.applyProviderEvent(event);
+					throw new ProviderStreamError(event.message, event.code);
 				}
 				await this.applyProviderEvent(event);
+				produced = true;
 				if (event.type === "response" && this.isUsageNearLimit(event.usage)) shouldAutoRecover = true;
 			}
 		} finally {
@@ -1117,7 +1023,7 @@ var ProviderTurnLoop = class {
 				}
 				const input = parseJsonOrString(toolCall.input);
 				const result = await this.invokeToolAsResult(tool, toolCall.toolUseId, input);
-				this.host.transcript.completeToolCall(toolCall.toolUseId, result.output, result.isError ?? false, result.view ?? null);
+				this.host.transcript.completeToolCall(toolCall.toolUseId, result.output, result.isError ?? false, result.metadata ?? result.continuation ?? null);
 				await this.host.runtime.lifecycle?.({
 					type: "after_tool_call",
 					agentSessionId: this.host.agentSessionId,
@@ -1125,8 +1031,7 @@ var ProviderTurnLoop = class {
 					transcript: this.host.transcript,
 					toolCallId: toolCall.toolUseId,
 					toolName: toolCall.toolName,
-					result,
-					metadata: this.host.metadata
+					result
 				});
 				await this.host.commitTranscript();
 				if (!options.deferSteerMaterialization) await this.host.materializeSteersArrivedSince(steerContinuationBeforeTool);
@@ -1149,7 +1054,6 @@ var ProviderTurnLoop = class {
 			model: this.host.model,
 			toolCallId,
 			signal,
-			metadata: this.host.metadata,
 			emitProgress: (progress) => {
 				this.host.emit({
 					type: "tool_progress",
@@ -1172,10 +1076,7 @@ var ProviderTurnLoop = class {
 					text: `Tool failed: ${normalized.message}`
 				}],
 				isError: true,
-				view: {
-					kind: "tool_error",
-					error: normalized.message
-				}
+				metadata: { error: normalized.message }
 			};
 		}
 	}
@@ -1183,8 +1084,7 @@ var ProviderTurnLoop = class {
 		return this.host.runtime.tools({
 			agentSessionId: this.host.agentSessionId,
 			state: this.host.agentState,
-			cwd: this.host.cwd,
-			metadata: this.host.metadata
+			cwd: this.host.cwd
 		});
 	}
 	buildInferenceRequest() {
@@ -1238,9 +1138,6 @@ var AgentSession = class AgentSession {
 	listeners = /* @__PURE__ */ new Set();
 	pendingActions = [];
 	queued = [];
-	get modelSelection() {
-		return this.model;
-	}
 	transcriptLog;
 	agentState;
 	currentPhase = "idle";
@@ -1250,7 +1147,6 @@ var AgentSession = class AgentSession {
 	activeTurnId = null;
 	activeTurnPhase = null;
 	activeProviderRun = null;
-	activeMetadata = null;
 	steerQueue = new PendingSteerQueue();
 	yields;
 	compaction;
@@ -1262,27 +1158,22 @@ var AgentSession = class AgentSession {
 	persistTimer = null;
 	persistDirty = false;
 	/**
-	* Restores a session from a checkpoint. Ownership of the checkpoint (including
+	* Restores a session from a snapshot. Ownership of the snapshot (including
 	* `state`) transfers to the session: the caller must not mutate it afterwards.
 	* Passing state by reference — not a clone — lets the caller share the same
 	* object with harness closures (host/commands), keeping one live state.
 	*/
-	static fromCheckpoint(params, options = {}) {
-		if (params.checkpoint.harnessName !== params.runtime.harnessName) throw new Error(`AgentSession: checkpoint harness "${params.checkpoint.harnessName}" does not match "${params.runtime.harnessName}"`);
-		const checkpoint = params.checkpoint;
-		const session = new AgentSession({
+	static fromSnapshot(params, options = {}) {
+		if (params.snapshot.harnessName !== params.runtime.harnessName) throw new Error(`AgentSession: snapshot harness "${params.snapshot.harnessName}" does not match "${params.runtime.harnessName}"`);
+		const snapshot = params.snapshot;
+		return new AgentSession({
 			provider: params.provider,
-			model: checkpoint.model,
-			cwd: checkpoint.cwd,
+			model: snapshot.model,
+			cwd: snapshot.cwd,
 			runtime: params.runtime,
-			transcript: checkpoint.transcript,
-			state: checkpoint.state
+			transcript: snapshot.transcript,
+			state: snapshot.state
 		}, options);
-		for (const toolCall of session.transcriptLog.pendingToolCalls()) session.transcriptLog.completeToolCall(toolCall.toolUseId, [{
-			type: "text",
-			text: `Tool call interrupted: ${toolCall.toolName} (the process died before a result was recorded)`
-		}], true);
-		return session;
 	}
 	constructor(params, options = {}) {
 		this.provider = params.provider;
@@ -1292,8 +1183,8 @@ var AgentSession = class AgentSession {
 		this.agentState = params.state === void 0 ? params.runtime.initialState() : params.state;
 		this.agentSessionId = options.agentSessionId ?? createId();
 		this.idFactory = options.idFactory ?? createId;
-		this.yields = new YieldScheduler(this.idFactory, (wakeupId, metadata) => {
-			this.deliverYieldWakeup(wakeupId, metadata);
+		this.yields = new YieldScheduler(this.idFactory, (wakeupId) => {
+			this.deliverYieldWakeup(wakeupId);
 		});
 		this.store = options.store;
 		this.persistIntervalMs = options.persistIntervalMs ?? DEFAULT_PERSIST_INTERVAL_MS;
@@ -1304,7 +1195,7 @@ var AgentSession = class AgentSession {
 			idFactory: this.idFactory,
 			now: options.now
 		};
-		this.transcriptLog = params.transcript instanceof TranscriptLog ? params.transcript : new TranscriptLog(params.transcript?.blocks ?? [], transcriptOptions);
+		this.transcriptLog = params.transcript instanceof Transcript ? params.transcript : new Transcript(params.transcript?.blocks ?? [], transcriptOptions);
 		const self = this;
 		const compactionHost = {
 			get transcript() {
@@ -1371,9 +1262,6 @@ var AgentSession = class AgentSession {
 			get retryPolicy() {
 				return self.retryPolicy;
 			},
-			get metadata() {
-				return self.activeMetadata;
-			},
 			currentSignal: () => self.currentSignal(),
 			currentTurnId: () => self.currentTurnId(),
 			nextRequestId: () => self.idFactory(),
@@ -1391,8 +1279,7 @@ var AgentSession = class AgentSession {
 			runWithCompactingPhase: (fn) => self.runWithCompactingPhase(fn),
 			commitTranscript: () => self.commitTranscript(),
 			emit: (event) => self.emit(event),
-			materializeSteersArrivedSince: (count) => self.materializePendingSteersArrivedSince(count),
-			materializePendingSteers: () => self.materializePendingSteersForCurrentTurn()
+			materializeSteersArrivedSince: (count) => self.materializePendingSteersArrivedSince(count)
 		};
 		this.turnLoop = new ProviderTurnLoop(turnLoopHost);
 	}
@@ -1402,46 +1289,27 @@ var AgentSession = class AgentSession {
 			type: "send",
 			id,
 			content,
-			metadata: cloneMetadata(options.metadata),
 			resolve: noop,
 			reject: noop
 		});
 	}
-	/**
-	* Discards the whole latest turn and runs it again from the user's input.
-	*
-	* This is "regenerate": it is only meaningful when the caller wants a different
-	* answer to the same question and knows the turn's effects can be repeated. It is
-	* NOT the way to recover a failed turn — use `resume`, which unwinds only as far
-	* as is safe.
-	*/
-	retry(options = {}) {
+	retry() {
 		return this.enqueue({
 			type: "retry",
-			metadata: cloneMetadata(options.metadata),
 			resolve: noop,
 			reject: noop
 		});
 	}
-	/**
-	* Finishes a turn that did not finish, after an abort or a terminal provider
-	* error. Unwinds to the turn's resume point — dropping the failed attempt's
-	* leftovers, keeping everything that already left the process — and re-infers
-	* from there. Callers do not choose the granularity and do not need to know how
-	* the turn died.
-	*/
-	resume(options = {}) {
+	resume() {
 		return this.enqueue({
 			type: "resume",
-			metadata: cloneMetadata(options.metadata),
 			resolve: noop,
 			reject: noop
 		});
 	}
-	compact(options = {}) {
+	compact() {
 		return this.enqueue({
 			type: "compact",
-			metadata: cloneMetadata(options.metadata),
 			resolve: noop,
 			reject: noop
 		});
@@ -1544,8 +1412,8 @@ var AgentSession = class AgentSession {
 			canAbortAgain: false
 		};
 	}
-	scheduleYieldWakeup(durationMs, metadata = this.activeMetadata) {
-		const wakeupId = this.yields.schedule(durationMs, metadata);
+	scheduleYieldWakeup(durationMs) {
+		const wakeupId = this.yields.schedule(durationMs);
 		return {
 			output: [{
 				type: "text",
@@ -1555,7 +1423,7 @@ var AgentSession = class AgentSession {
 					`durationMs: ${durationMs}`
 				].join("\n")
 			}],
-			view: {
+			metadata: {
 				kind: "yield_wakeup",
 				wakeupId,
 				durationMs
@@ -1704,13 +1572,13 @@ var AgentSession = class AgentSession {
 			action.resolve();
 		}
 	}
-	async deliverYieldWakeup(wakeupId, metadata) {
+	async deliverYieldWakeup(wakeupId) {
 		if (!this.yields.take(wakeupId)) return;
 		const content = [{
 			type: "text",
 			text: "Scheduled yield wakeup fired. Continue the previous work and inspect any running command with shell_status when needed."
 		}];
-		if (metadata === this.activeMetadata && this.canAcceptInternalSteer()) try {
+		if (this.canAcceptInternalSteer()) try {
 			await this.steerInternal(content, wakeupId, true);
 			return;
 		} catch (error) {
@@ -1719,7 +1587,7 @@ var AgentSession = class AgentSession {
 				error: asError(error)
 			});
 		}
-		this.enqueueHiddenSend(content, metadata);
+		this.enqueueHiddenSend(content);
 	}
 	canAcceptInternalSteer() {
 		try {
@@ -1751,12 +1619,11 @@ var AgentSession = class AgentSession {
 			hidden
 		});
 	}
-	enqueueHiddenSend(content, metadata) {
+	enqueueHiddenSend(content) {
 		this.enqueue({
 			type: "send",
 			id: this.idFactory(),
 			content,
-			metadata,
 			hidden: true,
 			resolve: noop,
 			reject: noop
@@ -1765,13 +1632,13 @@ var AgentSession = class AgentSession {
 	steerDelivery() {
 		if (!this.activeTurnId || !this.currentAbortController || !this.activeTurnPhase) throw new Error("AgentSession: no active turn to steer");
 		if (this.currentAbortController.signal.aborted) throw new Error("AgentSession: active turn is aborted");
-		if (this.activeTurnPhase === "finalizing") throw new Error("AgentSession: active turn cannot accept steering while finalizing");
+		if (this.activeTurnPhase === "compacting" || this.activeTurnPhase === "finalizing") throw new Error(`AgentSession: active turn cannot accept steering while ${this.activeTurnPhase}`);
 		const run = this.activeProviderRun;
 		if (run?.steer) return {
 			type: "provider",
 			run
 		};
-		if (this.activeTurnPhase === "tool_executing" || this.activeTurnPhase === "provider_streaming" || this.activeTurnPhase === "compacting") return { type: "next_provider_continuation" };
+		if (this.activeTurnPhase === "tool_executing" || this.activeTurnPhase === "provider_streaming") return { type: "next_provider_continuation" };
 		throw new Error("AgentSession: active turn cannot accept steering now");
 	}
 	enqueue(action) {
@@ -1804,7 +1671,6 @@ var AgentSession = class AgentSession {
 				if (action.type === "send") this.removeQueuedMessage(action.id);
 				this.currentAbortController = new AbortController();
 				this.activeTurnId = action.type === "send" ? action.id : this.idFactory();
-				this.activeMetadata = action.metadata;
 				this.abortRecorded = false;
 				try {
 					await this.executeAction(action);
@@ -1846,7 +1712,6 @@ var AgentSession = class AgentSession {
 					this.discardPendingSteersForCurrentTurn();
 					this.activeTurnPhase = "finalizing";
 					this.activeProviderRun = null;
-					this.activeMetadata = null;
 					this.currentAbortController = null;
 					this.activeTurnId = null;
 					this.activeTurnPhase = null;
@@ -1880,7 +1745,6 @@ var AgentSession = class AgentSession {
 				this.setPhase("compacting");
 				this.activeTurnPhase = "compacting";
 				await this.compaction.run();
-				await this.materializePendingSteersForCurrentTurn();
 				return;
 		}
 	}
@@ -1921,8 +1785,7 @@ var AgentSession = class AgentSession {
 			agentSessionId: this.agentSessionId,
 			state: this.agentState,
 			transcript: this.transcriptLog,
-			content,
-			metadata: this.activeMetadata
+			content
 		});
 		const resolvedContent = await this.resolveReferences(content);
 		await this.applyPendingModelSwitch();
@@ -1941,8 +1804,7 @@ var AgentSession = class AgentSession {
 			agentSessionId: this.agentSessionId,
 			cwd: this.cwd,
 			transcript: this.transcriptLog,
-			signal,
-			metadata: this.activeMetadata
+			signal
 		}, content)), signal);
 	}
 	async executeRetry() {
@@ -1954,29 +1816,15 @@ var AgentSession = class AgentSession {
 			agentSessionId: this.agentSessionId,
 			state: this.agentState,
 			transcript: this.transcriptLog,
-			reason: "retry",
-			metadata: this.activeMetadata
+			reason: "retry"
 		});
 		await this.commitTranscript();
 		await this.applyPendingModelSwitch();
 		await this.compaction.preflight();
 		await this.turnLoop.run();
 	}
-	/**
-	* Finishes an unfinished turn. Unwinds to its resume point — dropping the failed
-	* attempt's leftovers, keeping everything that already left the process — and
-	* re-infers from there. When the whole turn turns out to be discardable this is
-	* a plain rerun, which spares the model a continuation boundary attached to a
-	* stub of its own aborted output.
-	*/
 	async executeResume() {
-		const { cut, isFullRerun } = findResumePoint(this.transcriptLog.blocks);
-		if (isFullRerun) {
-			await this.executeRetry();
-			return;
-		}
 		await this.applyPendingModelSwitch();
-		this.transcriptLog.truncateFrom(cut);
 		this.transcriptLog.markLatestAbortResumed();
 		this.transcriptLog.pushResumeTurn(this.currentTurnId(), this.model);
 		await this.commitTranscript();
@@ -2004,8 +1852,7 @@ var AgentSession = class AgentSession {
 			agentSessionId: this.agentSessionId,
 			state: this.agentState,
 			cwd: this.cwd,
-			transcript: this.transcriptLog,
-			metadata: this.activeMetadata
+			transcript: this.transcriptLog
 		};
 	}
 	currentSignal() {
@@ -2095,7 +1942,7 @@ var AgentSession = class AgentSession {
 	/**
 	* Publishes transcript changes: drains the mutation journal into a patch
 	* event (O(changed content), not O(transcript)) and schedules a throttled
-	* checkpoint write. Boundaries (action end, abort, dispose) flush the write.
+	* snapshot write. Boundaries (action end, abort, dispose) flush the write.
 	*/
 	async commitTranscript() {
 		const drained = this.transcriptLog.takePatches();
@@ -2112,7 +1959,7 @@ var AgentSession = class AgentSession {
 		if (this.persistTimer) return;
 		this.persistTimer = setTimeout(() => {
 			this.persistTimer = null;
-			this.persistCheckpoint().catch((error) => {
+			this.persistSnapshot().catch((error) => {
 				this.emit({
 					type: "error",
 					error: asError(error)
@@ -2120,11 +1967,11 @@ var AgentSession = class AgentSession {
 			});
 		}, this.persistIntervalMs);
 	}
-	async persistCheckpoint() {
+	async persistSnapshot() {
 		if (!this.store || !this.persistDirty) return;
 		this.persistDirty = false;
-		await this.store.saveCheckpoint({
-			transcript: this.transcriptLog.toJSON(),
+		await this.store.saveSnapshot({
+			transcript: this.transcriptLog.snapshot(),
 			state: structuredClone(this.agentState),
 			phase: this.currentPhase,
 			queue: structuredClone(this.queuedMessages()),
@@ -2138,7 +1985,7 @@ var AgentSession = class AgentSession {
 			clearTimeout(this.persistTimer);
 			this.persistTimer = null;
 		}
-		await this.persistCheckpoint();
+		await this.persistSnapshot();
 	}
 	emit(event) {
 		for (const listener of this.listeners) listener(event);
@@ -2152,9 +1999,6 @@ var AgentSession = class AgentSession {
 function textContentSummary(content) {
 	return truncate(content.map((block) => block.type === "text" ? block.text : `[${block.type}]`).join("\n").trim(), 120, "...");
 }
-function cloneMetadata(metadata) {
-	return metadata === void 0 ? null : structuredClone(metadata);
-}
 async function readProviderIterator(iterator, signal) {
 	try {
 		return await abortable(iterator.next(), signal);
@@ -2230,6 +2074,7 @@ const APPROX_CHARS_PER_TOKEN = 4;
 const TOOL_DESCRIPTION_FIELD = "Concise title for the concrete user-visible state or result to make visible or confirm. Do not describe waiting, pausing, tool mechanics, generic actions, object labels, steps, tool names, ids, internals, or reasons.";
 const execRepeatStates = /* @__PURE__ */ new WeakMap();
 function createStandardAgentTools(options) {
+	const { environment } = options;
 	return [
 		{
 			name: "shell_exec",
@@ -2254,7 +2099,6 @@ function createStandardAgentTools(options) {
 			},
 			invoke: async (ctx, input) => {
 				const parsed = parseShellExecInput(input);
-				const environment = await resolveEnvironment(options.environment, ctx, { shellId: parsed.shellId });
 				const repeatGuard = repeatedShellExecResult(environment, ctx.agentSessionId, parsed.script);
 				if (repeatGuard) return repeatGuard;
 				const result = await environment.exec({
@@ -2282,9 +2126,7 @@ function createStandardAgentTools(options) {
 				}
 			},
 			invoke: async (ctx, input) => {
-				const parsed = parseShellStatusInput(input);
-				const environment = await resolveEnvironment(options.environment, ctx, { commandId: parsed.commandId });
-				const result = await environment.status(parsed);
+				const result = await environment.status(parseShellStatusInput(input));
 				ctx.emitProgress(result);
 				return finishShellToolResult(environment, result, ctx);
 			}
@@ -2306,10 +2148,8 @@ function createStandardAgentTools(options) {
 				}
 			},
 			invoke: async (ctx, input) => {
-				const parsed = parseShellWriteInput(input);
-				const environment = await resolveEnvironment(options.environment, ctx, { commandId: parsed.commandId });
 				const result = await environment.write({
-					...parsed,
+					...parseShellWriteInput(input),
 					signal: ctx.signal
 				});
 				ctx.emitProgress(result);
@@ -2332,9 +2172,7 @@ function createStandardAgentTools(options) {
 				}
 			},
 			invoke: async (ctx, input) => {
-				const parsed = parseShellAbortInput(input);
-				const environment = await resolveEnvironment(options.environment, ctx, { commandId: parsed.commandId });
-				const result = await environment.abort(parsed);
+				const result = await environment.abort(parseShellAbortInput(input));
 				ctx.emitProgress(result);
 				return {
 					...await finishShellToolResult(environment, result, ctx),
@@ -2365,136 +2203,31 @@ function createStandardAgentTools(options) {
 		}
 	];
 }
-function resolveEnvironment(source, ctx, handle) {
-	return typeof source === "function" ? source(ctx, handle) : source;
-}
-/**
-* How many bytes of each modality a tool may hand to the model.
-*
-* One number cannot serve both, because bytes buy wildly different amounts of
-* context per modality — measured against a frontier model, a KiB of video
-* costs ~2 tokens where a KiB of image costs ~50. A cap generous enough to show
-* a five-minute clip would let a single still eat a six-figure token budget.
-*
-* image (4 MiB): well past any sane still — a 4000x3000 PNG lands under it — so
-*   crossing this line is a mistake, not a use case.
-* video (16 MiB): roughly ten minutes at a viewing-grade encoding, and
-*   deliberately under the ~20 MB inline-payload ceiling the major APIs enforce.
-*   A larger cap buys no reach, only a rejection further downstream where the
-*   reason is harder to read.
-*
-* Bytes are a proxy, not a budget: for video they track cost reasonably at a
-* fixed encoding, but an image's real driver is its pixel dimensions.
-*/
-const DEFAULT_MAX_MEDIA_BYTES = {
-	image: 4 * 1024 * 1024,
-	video: 16 * 1024 * 1024
-};
 function shellPreviewBudgetTokens(contextWindow) {
 	return contextWindow >= LARGE_CONTEXT_THRESHOLD_TOKENS ? LARGE_CONTEXT_PREVIEW_TOKENS : SMALL_CONTEXT_PREVIEW_TOKENS;
 }
-function toShellToolResult(result, options = {}) {
+function toShellToolResult(result, toolCallId = "", options = {}) {
 	const output = [{
 		type: "text",
 		text: formatShellToolResult(result, options)
 	}];
-	if (result.status === "exited" && result.binaryStdout) {
-		const verdict = binaryStreamVerdict(result.binaryStdout, result.commandId, options.model, {
-			...DEFAULT_MAX_MEDIA_BYTES,
-			...options.maxMediaBytes
-		});
-		if (verdict.block) output.push(verdict.block);
-		if (verdict.note) output.push({
-			type: "text",
-			text: verdict.note
-		});
-	}
+	if (result.status === "exited" && result.assets) for (const asset of result.assets) output.push({
+		type: "image",
+		source: {
+			mediaType: asset.mediaType,
+			data: asset.data
+		}
+	});
 	return {
 		output,
 		isError: false,
-		view: shellToolView(result)
-	};
-}
-/** Character budget for a shell view's render window (tail-biased). */
-const SHELL_VIEW_MAX_CHARS = 32768;
-function shellToolView(result) {
-	const window = tailChunkWindow(result.output.chunks, SHELL_VIEW_MAX_CHARS);
-	const view = {
-		kind: "shell",
-		status: result.status,
-		shellId: result.shellId,
-		commandId: result.commandId,
-		runningMs: result.runningMs,
-		idleMs: result.idleMs,
-		chunks: window.chunks,
-		viewTruncated: window.truncated || result.output.truncated
-	};
-	if (result.status === "exited") {
-		view.exitCode = result.exitCode;
-		if (result.audit.length > 0) view.audit = result.audit;
-		if (result.commandMetadata && result.commandMetadata.length > 0) view.commandMeta = result.commandMetadata;
-	}
-	return view;
-}
-function tailChunkWindow(chunks, maxChars) {
-	const kept = [];
-	let total = 0;
-	for (let i = chunks.length - 1; i >= 0; i -= 1) {
-		const chunk = chunks[i];
-		if (chunk.text.length === 0) continue;
-		const remaining = maxChars - total;
-		if (remaining <= 0) return {
-			chunks: kept,
-			truncated: true
-		};
-		if (chunk.text.length <= remaining) {
-			kept.unshift({
-				stream: chunk.stream,
-				text: chunk.text
-			});
-			total += chunk.text.length;
-		} else {
-			kept.unshift({
-				stream: chunk.stream,
-				text: chunk.text.slice(chunk.text.length - remaining)
-			});
-			return {
-				chunks: kept,
-				truncated: true
-			};
-		}
-	}
-	return {
-		chunks: kept,
-		truncated: false
-	};
-}
-/**
-* Boundary decision for a binary final stream: attach as native media when the
-* magic matches the closed model-media set, the model accepts the type, and
-* the stream was not truncated; otherwise explain why nothing was attached.
-*/
-function binaryStreamVerdict(binary, commandId, model, maxMediaBytes) {
-	const media = sniffModelMediaType(binary.data);
-	const binPath = `/@/commands/${commandId}/stdout.bin`;
-	if (binary.truncated) return { note: `Binary stdout (${binary.totalBytes} bytes${media ? `, ${media.mediaType}` : ""}) exceeded the shell's ${binary.limitBytes}-byte binary limit (maxBinaryBytes) and was not attached; the raw bytes remain readable at ${binPath}. Produce a smaller version and re-run.` };
-	if (!media) return { note: `Binary stdout does not match any model-viewable media type; the raw bytes remain readable at ${binPath}.` };
-	if (!model || !modelAcceptsMediaType(model, media.mediaType)) return { note: `Binary stdout is ${media.mediaType}, which this model does not accept natively; the raw bytes remain readable at ${binPath}.` };
-	const cap = maxMediaBytes[media.kind];
-	if (binary.totalBytes > cap) return { note: `Binary stdout is ${media.mediaType} (${binary.totalBytes} bytes), over the ${cap}-byte ${media.kind} cap; it was not attached and the raw bytes remain readable at ${binPath}. Produce a smaller version — for video, fewer frames or a lower resolution — and re-run.` };
-	const source = {
-		mediaType: media.mediaType,
-		data: bytesToBase64(binary.data)
-	};
-	return {
-		block: media.kind === "video" ? {
-			type: "video",
-			source
-		} : {
-			type: "image",
-			source
-		},
-		note: `Attached stdout as ${media.mediaType} (${binary.totalBytes} bytes).`
+		metadata: result,
+		continuation: result.status === "running" ? {
+			toolCallId,
+			shellId: result.shellId,
+			commandId: result.commandId,
+			status: "running"
+		} : void 0
 	};
 }
 function parseShellExecInput(input) {
@@ -2556,8 +2289,8 @@ function repeatedShellExecResult(environment, agentSessionId, script) {
 			].join("\n")
 		}],
 		isError: true,
-		view: {
-			kind: "repeated_shell_exec",
+		metadata: {
+			kind: "repeated_identical_shell_exec",
 			script,
 			count
 		}
@@ -2615,11 +2348,10 @@ function boundedPreview(text, budgetTokens) {
 async function finishShellToolResult(environment, result, ctx) {
 	const previewBudgetTokens = shellPreviewBudgetTokens(ctx.model.model.contextWindow);
 	const exposeCommandHandle = shellCommandHandleRequired(result, previewBudgetTokens);
-	const toolResult = toShellToolResult(result, {
+	const toolResult = toShellToolResult(result, ctx.toolCallId, {
 		includePreview: true,
 		previewBudgetTokens,
-		exposeCommandHandle,
-		model: ctx.model.model
+		exposeCommandHandle
 	});
 	if (!exposeCommandHandle) await environment.releaseCommand(result.commandId);
 	return toolResult;
@@ -2632,20 +2364,12 @@ function shellCommandHandleRequired(result, budgetTokens) {
 }
 //#endregion
 //#region src/server.ts
-var RunCommandLineShellNotFoundError = class extends Error {
-	shellId;
-	constructor(shellId) {
-		super(`runCommandLine: shell "${shellId}" is not open in this process`);
-		this.shellId = shellId;
-		this.name = "RunCommandLineShellNotFoundError";
-	}
-};
-var RunCommandLineCommandNotRegisteredError = class extends Error {
-	commandName;
-	constructor(commandName) {
-		super(`runCommandLine: command "${commandName}" is not registered for this session`);
-		this.commandName = commandName;
-		this.name = "RunCommandLineCommandNotRegisteredError";
+var RunCommandLineSessionNotFoundError = class extends Error {
+	agentSessionId;
+	constructor(agentSessionId) {
+		super(`runCommandLine: no session "${agentSessionId}" is open in this process`);
+		this.agentSessionId = agentSessionId;
+		this.name = "RunCommandLineSessionNotFoundError";
 	}
 };
 var RunCommandLineTimeoutError = class extends Error {
@@ -2665,7 +2389,7 @@ var AgentServer = class {
 	providers;
 	shellOptions;
 	sessionOptions;
-	prepareShell;
+	prepareSessionShell;
 	bindings = /* @__PURE__ */ new Set();
 	sessionOwnership = new SessionOwnershipRegistry();
 	constructor(options) {
@@ -2673,7 +2397,7 @@ var AgentServer = class {
 		this.providers = createProviderMap(options.providers);
 		this.shellOptions = options.shell ?? {};
 		this.sessionOptions = options.session ?? {};
-		this.prepareShell = options.prepareShell ?? null;
+		this.prepareSessionShell = options.prepareSessionShell ?? null;
 	}
 	client() {
 		const transports = createInProcessTransportPair();
@@ -2687,7 +2411,7 @@ var AgentServer = class {
 			providers: this.providers,
 			shell: this.shellOptions,
 			session: this.sessionOptions,
-			prepareShell: this.prepareShell,
+			prepareSessionShell: this.prepareSessionShell,
 			sessions: this.sessionOwnership
 		});
 		this.bindings.add(binding);
@@ -2703,18 +2427,17 @@ var AgentServer = class {
 	* Transport-agnostic: callers (e.g. LocalHost command bridge) supply their
 	* own IPC; AgentServer only knows how to exec against the open session shell.
 	*/
-	async runCommandLine(shellId, name, args, opts) {
-		const owners = [...this.bindings].filter((binding) => binding.hasShell(shellId));
-		if (owners.length === 0) throw new RunCommandLineShellNotFoundError(shellId);
-		if (owners.length > 1) throw new Error(`runCommandLine: shell id "${shellId}" is not unique`);
-		return owners[0].runCommandLine(shellId, name, args, opts);
+	async runCommandLine(agentSessionId, name, args, opts) {
+		const binding = this.sessionOwnership.get(agentSessionId);
+		if (!binding) throw new RunCommandLineSessionNotFoundError(agentSessionId);
+		return binding.runCommandLine(name, args, opts);
 	}
 };
 /**
 * Tracks which transport binding currently owns each client-provided session
 * id. Opening a session id that is already owned takes it over: the previous
-* binding's session is closed (flushing its checkpoint) before the new open
-* proceeds, so two connections never write the same checkpoint key concurrently.
+* binding's session is closed (flushing its snapshot) before the new open
+* proceeds, so two connections never write the same snapshot key concurrently.
 */
 var SessionOwnershipRegistry = class {
 	holders = /* @__PURE__ */ new Map();
@@ -2736,17 +2459,14 @@ var AgentTransportBindingImpl = class {
 	providers;
 	shellOptions;
 	sessionOptions;
-	prepareShell;
+	prepareSessionShell;
 	sessions;
 	session = null;
 	currentAgent = null;
-	environmentsByHost = /* @__PURE__ */ new Map();
-	pendingEnvironmentsByHost = /* @__PURE__ */ new Map();
-	currentCommandRegistry = null;
+	currentEnvironment = null;
 	currentCwd = null;
 	currentProviderId = null;
 	currentSessionId = null;
-	currentCommandNames = /* @__PURE__ */ new Set();
 	unsubscribeSession = null;
 	unsubscribeTransport = null;
 	closed = false;
@@ -2756,7 +2476,7 @@ var AgentTransportBindingImpl = class {
 		this.providers = options.providers;
 		this.shellOptions = options.shell ?? {};
 		this.sessionOptions = options.session ?? {};
-		this.prepareShell = options.prepareShell;
+		this.prepareSessionShell = options.prepareSessionShell;
 		this.sessions = options.sessions;
 		this.unsubscribeTransport = this.transport.onFrame((frame) => {
 			this.handleFrame(frame);
@@ -2793,10 +2513,7 @@ var AgentTransportBindingImpl = class {
 				case "send": {
 					const session = this.sessionFor("send");
 					if (!session) return;
-					this.observeSessionAction(session.send(frame.content, {
-						id: frame.messageId,
-						metadata: frame.metadata
-					}));
+					this.observeSessionAction(session.send(frame.content, { id: frame.messageId }));
 					return;
 				}
 				case "dequeue_message": {
@@ -2889,19 +2606,19 @@ var AgentTransportBindingImpl = class {
 				case "retry": {
 					const session = this.sessionFor("retry");
 					if (!session || this.rejectIfBusy(session, "retry")) return;
-					this.observeSessionAction(session.retry({ metadata: frame.metadata }));
+					this.observeSessionAction(session.retry());
 					return;
 				}
 				case "resume": {
 					const session = this.sessionFor("resume");
 					if (!session || this.rejectIfBusy(session, "resume")) return;
-					this.observeSessionAction(session.resume({ metadata: frame.metadata }));
+					this.observeSessionAction(session.resume());
 					return;
 				}
 				case "compact": {
 					const session = this.sessionFor("compact");
 					if (!session || this.rejectIfBusy(session, "compact")) return;
-					this.observeSessionAction(session.compact({ metadata: frame.metadata }));
+					this.observeSessionAction(session.compact());
 					return;
 				}
 				case "abort": {
@@ -2923,7 +2640,7 @@ var AgentTransportBindingImpl = class {
 				case "sync_transcript": {
 					const session = this.sessionFor("sync_transcript");
 					if (!session) return;
-					this.sendTranscriptReset(session);
+					this.sendTranscriptSnapshot(session);
 					return;
 				}
 				case "close":
@@ -2950,30 +2667,41 @@ var AgentTransportBindingImpl = class {
 		await this.sessions.claim(agentSessionId, this);
 		this.currentSessionId = agentSessionId;
 		const initialState = agent.initialState();
-		const store = new HostAgentSessionStore((await agent.host({
+		const provisionalHost = agent.host({
 			state: initialState,
 			cwd: frame.cwd
-		})).store, agentSessionId);
-		const checkpoint = await store.loadCheckpoint();
-		const restoring = checkpoint !== null && checkpoint.harnessName === agent.name;
-		const state = restoring ? structuredClone(checkpoint.state) : initialState;
+		});
+		const store = new HostAgentSessionStore(provisionalHost.store, agentSessionId);
+		const snapshot = await store.loadSnapshot();
+		const restoring = snapshot !== null && snapshot.harnessName === agent.name;
+		const state = restoring ? structuredClone(snapshot.state) : initialState;
 		const harnessContext = {
 			state,
 			cwd: frame.cwd
 		};
+		const host = restoring ? agent.host(harnessContext) : provisionalHost;
 		const commands = agent.commands?.(harnessContext) ?? [];
 		const commandRegistry = new CommandRegistry();
 		for (const command of commands) commandRegistry.register(command);
-		const commandNames = commandRegistry.list().map((command) => command.name);
+		const environment = new BashEnvironment({
+			...this.prepareSessionShell ? await this.prepareSessionShell({
+				agentSessionId,
+				host,
+				commandNames: commandRegistry.list().map((command) => command.name),
+				shell: this.shellOptions
+			}) : this.shellOptions,
+			host,
+			commands: commandRegistry
+		});
 		let sessionRef = null;
 		const tools = createStandardAgentTools({
-			environment: (ctx, handle) => this.resolveEnvironment(ctx, handle),
-			scheduleYield: (ctx, durationMs) => {
+			environment,
+			scheduleYield: (_ctx, durationMs) => {
 				if (!sessionRef) throw new Error("AgentServer: session is not ready for yield scheduling");
-				return sessionRef.scheduleYieldWakeup(durationMs, ctx.metadata);
+				return sessionRef.scheduleYieldWakeup(durationMs);
 			}
 		});
-		const commandsPrompt = commandRegistry.renderHelp();
+		const commandsPrompt = commandRegistry.renderPrompt();
 		const runtime = {
 			harnessName: agent.name,
 			initialState: () => agent.initialState(),
@@ -2986,11 +2714,11 @@ var AgentTransportBindingImpl = class {
 			lifecycle: (event) => agent.lifecycle?.(event),
 			tools: () => tools
 		};
-		const session = restoring ? AgentSession.fromCheckpoint({
+		const session = restoring ? AgentSession.fromSnapshot({
 			provider,
 			runtime,
-			checkpoint: {
-				...checkpoint,
+			snapshot: {
+				...snapshot,
 				state
 			}
 		}, {
@@ -3011,14 +2739,13 @@ var AgentTransportBindingImpl = class {
 		sessionRef = session;
 		this.session = session;
 		this.currentAgent = agent;
-		this.currentCommandRegistry = commandRegistry;
+		this.currentEnvironment = environment;
 		this.currentCwd = frame.cwd;
 		this.currentProviderId = frame.provider.providerId;
-		this.currentCommandNames = new Set(commandNames);
 		if (restoring) session.updateModel(null, frame.provider.model);
 		this.unsubscribeSession = this.session.subscribe((event) => this.handleSessionEvent(event));
 		this.send({ type: "opened" });
-		this.sendTranscriptReset(session);
+		this.sendTranscriptSnapshot(session);
 		this.send({
 			type: "phase",
 			phase: this.session.phase()
@@ -3028,10 +2755,10 @@ var AgentTransportBindingImpl = class {
 			queue: this.session.queuedMessages()
 		});
 	}
-	sendTranscriptReset(session) {
+	sendTranscriptSnapshot(session) {
 		const transcript = session.transcript();
 		this.send({
-			type: "transcript_reset",
+			type: "transcript_snapshot",
 			blocks: cloneBlocks(transcript.blocks),
 			revision: transcript.revision
 		});
@@ -3065,8 +2792,7 @@ var AgentTransportBindingImpl = class {
 					type: "retry_scheduled",
 					attempt: event.attempt,
 					delayMs: event.delayMs,
-					code: event.code,
-					diagnostics: event.diagnostics
+					code: event.code
 				});
 				return;
 			case "error":
@@ -3101,13 +2827,11 @@ var AgentTransportBindingImpl = class {
 	async closeSession() {
 		const session = this.session;
 		const agent = this.currentAgent;
+		const environment = this.currentEnvironment;
 		const cwd = this.currentCwd;
 		try {
 			if (session) await session.dispose();
-			const pendingEnvironments = await Promise.allSettled(this.pendingEnvironmentsByHost.values());
-			const environments = new Set(this.environmentsByHost.values());
-			for (const result of pendingEnvironments) if (result.status === "fulfilled") environments.add(result.value);
-			await Promise.all([...environments].map((environment) => environment.disposeAllShells()));
+			if (environment) await environment.disposeAllShells();
 			if (session && agent && cwd) await agent.dispose?.({
 				agentSessionId: session.id(),
 				state: session.state(),
@@ -3119,12 +2843,9 @@ var AgentTransportBindingImpl = class {
 			this.unsubscribeSession = null;
 			this.session = null;
 			this.currentAgent = null;
-			this.environmentsByHost.clear();
-			this.pendingEnvironmentsByHost.clear();
-			this.currentCommandRegistry = null;
+			this.currentEnvironment = null;
 			this.currentCwd = null;
 			this.currentProviderId = null;
-			this.currentCommandNames = /* @__PURE__ */ new Set();
 			if (this.currentSessionId) {
 				this.sessions.release(this.currentSessionId, this);
 				this.currentSessionId = null;
@@ -3132,17 +2853,17 @@ var AgentTransportBindingImpl = class {
 		}
 	}
 	async listConversations(cwd) {
-		const host = await this.agent.host({
+		const host = this.agent.host({
 			state: this.agent.initialState(),
 			cwd
 		});
 		const keys = await host.store.list("agent-sessions/");
 		const conversations = [];
 		for (const key of keys) {
-			if (!key.endsWith("/checkpoint.json")) continue;
-			const checkpoint = await host.store.readJson(key);
-			if (!checkpoint || checkpoint.cwd !== cwd) continue;
-			conversations.push(summarizeConversation(key.slice(15, -16), checkpoint));
+			if (!key.endsWith("/snapshot.json")) continue;
+			const snapshot = await host.store.readJson(key);
+			if (!snapshot || snapshot.cwd !== cwd) continue;
+			conversations.push(summarizeConversation(key.slice(15, -14), snapshot));
 		}
 		conversations.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
 		this.send({
@@ -3151,122 +2872,39 @@ var AgentTransportBindingImpl = class {
 		});
 	}
 	async handleShellWrite(frame) {
-		const session = this.sessionFor("shell_write");
-		if (!session || !this.currentCwd) return;
-		const result = await (await this.resolveEnvironment({
-			agentSessionId: session.id(),
-			state: session.state(),
-			cwd: this.currentCwd,
-			metadata: frame.metadata ?? null
-		}, { commandId: frame.commandId })).write({
+		if (!this.sessionFor("shell_write") || !this.currentEnvironment || !this.currentCwd) return;
+		const result = await this.currentEnvironment.write({
 			commandId: frame.commandId,
 			stdin: frame.stdin
 		});
 		this.sendShellWriteResult(frame.commandId, result);
 	}
 	/** Backs `AgentServer.runCommandLine` — see its doc comment for the contract. */
-	async runCommandLine(shellId, name, args, opts) {
-		const environment = this.environmentForShell(shellId);
+	async runCommandLine(name, args, opts) {
+		const environment = this.currentEnvironment;
 		const agentSessionId = this.currentSessionId;
 		if (!environment || !agentSessionId) throw new Error("runCommandLine: session has no active shell environment");
-		if (!this.currentCommandNames.has(name)) throw new RunCommandLineCommandNotRegisteredError(name);
 		const words = [name, ...args].map(shellQuote).join(" ");
 		let script = words;
 		if (opts.stdin.length > 0) {
 			const delimiter = heredocDelimiter(opts.stdin);
-			script = `${words} <<'${delimiter}'\n${opts.stdin.endsWith("\n") ? opts.stdin : `${opts.stdin}\n`}${delimiter}`;
+			script = `${words} <<'${delimiter}'\n${opts.stdin}\n${delimiter}`;
 		}
+		const cdScript = `cd ${shellQuote(opts.cwd)} && ${script}`;
 		const result = await environment.exec({
 			agentSessionId,
-			script,
+			script: cdScript,
 			timeoutMs: MAX_TIMEOUT_MS,
-			signal: opts.signal,
-			ephemeral: true,
-			cwd: opts.cwd
+			signal: opts.signal
 		});
-		try {
-			if (result.status === "exited") {
-				if (result.binaryStdout) {
-					const truncationNote = result.binaryStdout.truncated ? `command bridge: binary stdout truncated at the output limit (${result.binaryStdout.data.length} of ${result.binaryStdout.totalBytes} bytes)\n` : "";
-					return {
-						exitCode: result.exitCode,
-						stdout: bytesToBase64(result.binaryStdout.data),
-						stdoutEncoding: "base64",
-						stderr: `${result.stderr.delta}${truncationNote}`
-					};
-				}
-				return {
-					exitCode: result.exitCode,
-					stdout: result.stdout.delta,
-					stderr: result.stderr.delta
-				};
-			}
-			if (result.status === "aborted") throw new Error(`runCommandLine: call for "${name}" was cancelled before it completed`);
-			const aborted = await environment.abort({ commandId: result.commandId });
-			throw new RunCommandLineTimeoutError(result.commandId, aborted.status === "aborted" ? aborted.stdout.delta : "", aborted.status === "aborted" ? aborted.stderr.delta : "");
-		} finally {
-			await environment.disposeShell(result.shellId).catch(() => {});
-		}
-	}
-	hasShell(shellId) {
-		return this.environmentForShell(shellId) !== null;
-	}
-	async resolveEnvironment(ctx, handle) {
-		const agent = this.currentAgent;
-		const commandRegistry = this.currentCommandRegistry;
-		if (!agent || !commandRegistry) throw new Error("Shell environment is not available before session open");
-		const host = await agent.host({
-			agentSessionId: ctx.agentSessionId,
-			state: ctx.state,
-			cwd: ctx.cwd,
-			metadata: ctx.metadata
-		});
-		const environment = await this.environmentForHost(host, commandRegistry);
-		const owner = handle.shellId ? this.environmentForShell(handle.shellId) : handle.commandId ? this.environmentForCommand(handle.commandId) : null;
-		if (owner && owner !== environment) {
-			const id = handle.shellId ?? handle.commandId;
-			throw new Error(`Shell handle "${id}" belongs to a different Host`);
-		}
-		return environment;
-	}
-	async environmentForHost(host, commands) {
-		const existing = this.environmentsByHost.get(host);
-		if (existing) return existing;
-		const pending = this.pendingEnvironmentsByHost.get(host);
-		if (pending) return pending;
-		const creation = this.createEnvironment(host, commands);
-		this.pendingEnvironmentsByHost.set(host, creation);
-		try {
-			const environment = await creation;
-			this.environmentsByHost.set(host, environment);
-			return environment;
-		} finally {
-			this.pendingEnvironmentsByHost.delete(host);
-		}
-	}
-	async createEnvironment(host, commands) {
-		const agentSessionId = this.currentSessionId;
-		if (!agentSessionId) throw new Error("Shell environment is not available before session open");
-		return new BashEnvironment({
-			...this.prepareShell ? await this.prepareShell({
-				agentSessionId,
-				host,
-				commandNames: commands.list().map((command) => command.name),
-				shell: this.shellOptions
-			}) : this.shellOptions,
-			host,
-			commands
-		});
-	}
-	environmentForShell(shellId) {
-		const matches = [...this.environmentsByHost.values()].filter((environment) => environment.getShell(shellId));
-		if (matches.length > 1) throw new Error(`Shell id "${shellId}" is not unique in this session`);
-		return matches[0] ?? null;
-	}
-	environmentForCommand(commandId) {
-		const matches = [...this.environmentsByHost.values()].filter((environment) => environment.hasCommand(commandId));
-		if (matches.length > 1) throw new Error(`Command id "${commandId}" is not unique in this session`);
-		return matches[0] ?? null;
+		if (result.status === "exited") return {
+			exitCode: result.exitCode,
+			stdout: result.stdout.delta,
+			stderr: result.stderr.delta
+		};
+		if (result.status === "aborted") throw new Error(`runCommandLine: call for "${name}" was cancelled before it completed`);
+		const aborted = await environment.abort({ commandId: result.commandId });
+		throw new RunCommandLineTimeoutError(result.commandId, aborted.status === "aborted" ? aborted.stdout.delta : "", aborted.status === "aborted" ? aborted.stderr.delta : "");
 	}
 	sessionFor(command) {
 		if (!this.session) {
@@ -3301,7 +2939,7 @@ var AgentTransportBindingImpl = class {
 			type: "shell_output",
 			shellId: shell.shellId,
 			commandId: shell.commandId,
-			status: shell.status
+			snapshot: shell.snapshot
 		});
 		const audit = progressToAudit(progress);
 		if (audit.length > 0) this.send({
@@ -3315,7 +2953,7 @@ var AgentTransportBindingImpl = class {
 			type: "shell_output",
 			shellId: shell.shellId,
 			commandId: shell.commandId,
-			status: shell.status
+			snapshot: shell.snapshot
 		});
 		const audit = progressToAudit(progress);
 		if (audit.length > 0) this.send({
@@ -3337,12 +2975,13 @@ var AgentTransportBindingImpl = class {
 	sendError(error) {
 		const normalized = error instanceof Error ? error : new Error(String(error));
 		const code = errorCode(error);
-		const diagnostics = errorDiagnostics(error);
-		this.send({
+		this.send(code ? {
 			type: "error",
 			message: normalized.message,
-			...code ? { code } : {},
-			...diagnostics ? { diagnostics } : {}
+			code
+		} : {
+			type: "error",
+			message: normalized.message
 		});
 	}
 };
@@ -3353,15 +2992,15 @@ var HostAgentSessionStore = class {
 		this.store = store;
 		this.agentSessionId = agentSessionId;
 	}
-	saveCheckpoint(checkpoint) {
-		return this.store.writeJson(`agent-sessions/${this.agentSessionId}/checkpoint.json`, checkpoint);
+	saveSnapshot(snapshot) {
+		return this.store.writeJson(`agent-sessions/${this.agentSessionId}/snapshot.json`, snapshot);
 	}
-	loadCheckpoint() {
-		return this.store.readJson(`agent-sessions/${this.agentSessionId}/checkpoint.json`);
+	loadSnapshot() {
+		return this.store.readJson(`agent-sessions/${this.agentSessionId}/snapshot.json`);
 	}
 };
-function summarizeConversation(id, checkpoint) {
-	const blocks = checkpoint.transcript.blocks;
+function summarizeConversation(id, snapshot) {
+	const blocks = snapshot.transcript.blocks;
 	const first = blocks[0];
 	const last = blocks[blocks.length - 1];
 	return {
@@ -3395,14 +3034,14 @@ function progressToShellOutput(progress) {
 	if (!isRecord(progress.stdout) || !isRecord(progress.stderr)) return null;
 	const stdout = progress.stdout;
 	const stderr = progress.stderr;
-	if (!isShellStreamView(stdout) || !isShellStreamView(stderr) || typeof progress.runningMs !== "number" || typeof progress.idleMs !== "number") return null;
+	if (!isStreamArtifact(stdout) || !isStreamArtifact(stderr) || typeof progress.runningMs !== "number" || typeof progress.idleMs !== "number") return null;
 	return {
 		shellId: progress.shellId,
 		commandId: progress.commandId,
-		status: progress
+		snapshot: progress
 	};
 }
-function isShellStreamView(value) {
+function isStreamArtifact(value) {
 	return typeof value.path === "string" && typeof value.offset === "number" && typeof value.delta === "string" && typeof value.tail === "string" && typeof value.bytes === "number" && typeof value.truncated === "boolean";
 }
 function progressToAudit(progress) {
@@ -3423,10 +3062,6 @@ function errorCode(error) {
 	if (!isRecord(error) || typeof error.code !== "string") return void 0;
 	return error.code;
 }
-function errorDiagnostics(error) {
-	if (!(error instanceof ProviderStreamError)) return void 0;
-	return error.diagnostics;
-}
 function createProviderMap(providers) {
 	const map = /* @__PURE__ */ new Map();
 	for (const provider of providers) {
@@ -3436,4 +3071,4 @@ function createProviderMap(providers) {
 	return map;
 }
 //#endregion
-export { AgentClient, AgentServer, AgentSession, DEFAULT_MAX_MEDIA_BYTES, DEFAULT_TURN_RETRY_POLICY, ProviderStreamError, RunCommandLineCommandNotRegisteredError, RunCommandLineShellNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, TranscriptLog, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, findResumePoint, finishShellToolResult, isContextLengthExceeded, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };
+export { AgentClient, AgentServer, AgentSession, DEFAULT_TURN_RETRY_POLICY, RunCommandLineSessionNotFoundError, RunCommandLineTimeoutError, Transcript, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, finishShellToolResult, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };