@demicodes/agent 0.2.1 → 0.3.1

package/dist/client-entry.d.mts

@@ -1,4 +1,4 @@
-import { d as TranscriptPatch, l as ServerFrame, n as AgentServerTransport, o as ClientFrame, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandSnapshotLike } from "./transport-DVa_82EW.mjs";
-import { a as AgentClientListener, i as AgentClient, n as createWebSocketClientTransport, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-Cn_rhIIX.mjs";
+import { d as TranscriptPatch, l as ServerFrame, n as AgentServerTransport, o as ClientFrame, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandStatusLike } from "./transport-0l1a6QD9.mjs";
+import { a as AgentClientListener, i as AgentClient, n as createWebSocketClientTransport, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-C0R8AiHD.mjs";
 import { ProviderSelection } from "@demicodes/provider";
-export { AgentClient, type AgentClientListener, type AgentClientTransport, type AgentServerTransport, type AgentTransport, type ClientFrame, type ClientSessionEvent, type JsonWebSocket, type ProviderSelection, type ServerFrame, type ShellCommandSnapshotLike, type TranscriptPatch, createWebSocketClientTransport, createWebSocketServerTransport };
+export { AgentClient, type AgentClientListener, type AgentClientTransport, type AgentServerTransport, type AgentTransport, type ClientFrame, type ClientSessionEvent, type JsonWebSocket, type ProviderSelection, type ServerFrame, type ShellCommandStatusLike, type TranscriptPatch, createWebSocketClientTransport, createWebSocketServerTransport };

package/dist/client-entry.mjs

@@ -1,2 +1,2 @@
-import { n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-Bod0puog.mjs";
+import { n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-CcSuuo4T.mjs";
 export { AgentClient, createWebSocketClientTransport, createWebSocketServerTransport };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { A as AgentToolInvokeResult, B as DEFAULT_TURN_RETRY_POLICY, C as AgentSessionRestoreParams, D as AgentTool, E as AgentSystemPromptContext, F as CompactionWindow, H as isRetryableCode, I as DrainedTranscriptPatches, L as Transcript, M as SessionEvent, N as SessionEventListener, O as AgentToolContext, P as ToolContinuation, R as TranscriptOptions, S as AgentSessionParams, T as AgentSessionStore, U as resolveRetryPolicy, V as TurnRetryPolicy, W as retryDelayMs, _ as AgentHarnessRuntime, a as createInProcessTransportPair, b as AgentReferenceResolveContext, c as ConversationSummary, d as TranscriptPatch, f as AbortResult, g as AgentHarnessContext, h as AgentHarness, i as InProcessTransportPair, j as ExternalMutationReservation, k as AgentToolInvokeContext, l as ServerFrame, m as AgentDisposeContext, n as AgentServerTransport, o as ClientFrame, p as AbortTarget, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandSnapshotLike, v as AgentLifecycleEvent, w as AgentSessionSnapshot, x as AgentSessionOptions, y as AgentPromptContext, z as estimateTranscriptBlockTokens } from "./transport-DVa_82EW.mjs";
-import { a as AgentClientListener, i as AgentClient, n as createWebSocketClientTransport, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-Cn_rhIIX.mjs";
-import { BashEnvironment, BashEnvironmentOptions, Host, ShellCommandSnapshot } from "@demicodes/shell";
+import { A as AgentToolInvokeResult, B as TurnRetryPolicy, C as AgentSessionParams, D as AgentTool, E as AgentSystemPromptContext, F as DrainedTranscriptPatches, H as resolveRetryPolicy, I as TranscriptLog, L as TranscriptOptions, M as SessionEvent, N as SessionEventListener, O as AgentToolContext, P as CompactionWindow, R as estimateTranscriptBlockTokens, S as AgentSessionOptions, T as AgentSessionStore, U as retryDelayMs, V as isRetryableCode, _ as AgentHarnessRuntime, a as createInProcessTransportPair, b as AgentReferenceResolveContext, c as ConversationSummary, d as TranscriptPatch, f as AbortResult, g as AgentHarnessContext, h as AgentHarness, i as InProcessTransportPair, j as ExternalMutationReservation, k as AgentToolInvokeContext, l as ServerFrame, m as AgentDisposeContext, n as AgentServerTransport, o as ClientFrame, p as AbortTarget, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandStatusLike, v as AgentLifecycleEvent, w as AgentSessionRestoreParams, x as AgentSessionCheckpoint, y as AgentPromptContext, z as DEFAULT_TURN_RETRY_POLICY } from "./transport-0l1a6QD9.mjs";
+import { a as AgentClientListener, i as AgentClient, n as createWebSocketClientTransport, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-C0R8AiHD.mjs";
+import { BashAuditEvent, BashEnvironment, BashEnvironmentOptions, CommandMetadataRecord, Host, ShellCommandStatus, ShellOutputChunk } from "@demicodes/shell";
 import { AgentProvider, Provider } from "@demicodes/provider";
 import { Block, Model, ModelSelection, QueuedMessage, SessionPhase, UserContentBlock } from "@demicodes/core";
 //#region src/session.d.ts
@@ -40,12 +40,12 @@ declare class AgentSession<State> {
   private persistTimer;
   private persistDirty;
   /**
-   * Restores a session from a snapshot. Ownership of the snapshot (including
+   * Restores a session from a checkpoint. Ownership of the checkpoint (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 fromSnapshot<State>(params: AgentSessionRestoreParams<State>, options?: AgentSessionOptions<State>): AgentSession<State>;
+  static fromCheckpoint<State>(params: AgentSessionRestoreParams<State>, options?: AgentSessionOptions<State>): AgentSession<State>;
   constructor(params: AgentSessionParams<State>, options?: AgentSessionOptions<State>);
   send(content: UserContentBlock[], options?: {
     id?: string;
@@ -78,7 +78,7 @@ declare class AgentSession<State> {
    * (e.g. a long-lived CLI subprocess). Called when the owning connection closes.
    */
   dispose(): Promise<void>;
-  transcript(): Transcript;
+  transcript(): TranscriptLog;
   state(): State;
   id(): string;
   phase(): SessionPhase;
@@ -134,11 +134,11 @@ declare class AgentSession<State> {
   /**
    * Publishes transcript changes: drains the mutation journal into a patch
    * event (O(changed content), not O(transcript)) and schedules a throttled
-   * snapshot write. Boundaries (action end, abort, dispose) flush the write.
+   * checkpoint write. Boundaries (action end, abort, dispose) flush the write.
    */
   private commitTranscript;
   private schedulePersist;
-  private persistSnapshot;
+  private persistCheckpoint;
   private flushPersist;
   private emit;
   private resolveIdleWaiters;
@@ -252,8 +252,31 @@ interface ShellToolResultOptions {
   model?: Model;
 }
 declare function shellPreviewBudgetTokens(contextWindow: number): number;
-declare function toShellToolResult(result: ShellCommandSnapshot, toolCallId?: string, options?: ShellToolResultOptions): AgentToolInvokeResult;
-declare function finishShellToolResult<State>(environment: BashEnvironment, result: ShellCommandSnapshot, ctx: AgentToolInvokeContext<State>): Promise<AgentToolInvokeResult>;
-declare function shellCommandHandleRequired(result: ShellCommandSnapshot, budgetTokens: number): boolean;
+declare function toShellToolResult(result: ShellCommandStatus, options?: ShellToolResultOptions): AgentToolInvokeResult;
+/** Character budget for a shell view's render window (tail-biased). */
+declare const SHELL_VIEW_MAX_CHARS = 32768;
+/**
+ * Bounded UI view of a shell command stored on the tool_call block. Full
+ * output lives in the command artifact (`/@/commands/<commandId>/…`), keyed by
+ * `commandId`; the view carries only the tail render window and never embeds
+ * raw or base64 bytes.
+ */
+interface ShellToolView {
+  kind: 'shell';
+  status: 'running' | 'exited' | 'aborted';
+  shellId: string;
+  commandId: string;
+  exitCode?: number;
+  runningMs: number;
+  idleMs: number;
+  /** Tail of the merged output, capped at SHELL_VIEW_MAX_CHARS. */
+  chunks: ShellOutputChunk[];
+  /** True when chunks were capped; the artifact has the full output. */
+  viewTruncated: boolean;
+  audit?: BashAuditEvent[];
+  commandMeta?: CommandMetadataRecord[];
+}
+declare function finishShellToolResult<State>(environment: BashEnvironment, result: ShellCommandStatus, ctx: AgentToolInvokeContext<State>): Promise<AgentToolInvokeResult>;
+declare function shellCommandHandleRequired(result: ShellCommandStatus, budgetTokens: number): boolean;
 //#endregion
-export { AbortResult, AbortTarget, ActiveTurnPhase, AgentClient, AgentClientListener, AgentClientTransport, AgentDisposeContext, AgentHarness, AgentHarnessContext, AgentHarnessRuntime, AgentLifecycleEvent, AgentPromptContext, AgentReferenceResolveContext, AgentServer, AgentServerOptions, AgentServerSessionOptions, AgentServerTransport, AgentSession, AgentSessionOptions, AgentSessionParams, AgentSessionRestoreParams, AgentSessionSnapshot, AgentSessionStore, AgentSystemPromptContext, AgentTool, AgentToolContext, AgentToolInvokeContext, AgentToolInvokeResult, AgentTransport, AgentTransportBinding, ClientFrame, ClientSessionEvent, CompactionWindow, ConversationSummary, DEFAULT_TURN_RETRY_POLICY, DrainedTranscriptPatches, ExternalMutationReservation, InProcessTransportPair, JsonWebSocket, PrepareSessionShell, PrepareSessionShellContext, RunCommandLineCommandNotRegisteredError, RunCommandLineOptions, RunCommandLineResult, RunCommandLineSessionNotFoundError, RunCommandLineTimeoutError, ServerFrame, SessionEvent, SessionEventListener, ShellCommandSnapshotLike, ShellToolResultOptions, StandardAgentToolOptions, ToolContinuation, Transcript, TranscriptOptions, TranscriptPatch, TurnRetryPolicy, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, finishShellToolResult, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };
+export { AbortResult, AbortTarget, ActiveTurnPhase, AgentClient, AgentClientListener, AgentClientTransport, AgentDisposeContext, AgentHarness, AgentHarnessContext, AgentHarnessRuntime, AgentLifecycleEvent, AgentPromptContext, AgentReferenceResolveContext, AgentServer, AgentServerOptions, AgentServerSessionOptions, AgentServerTransport, AgentSession, AgentSessionCheckpoint, AgentSessionOptions, AgentSessionParams, AgentSessionRestoreParams, AgentSessionStore, AgentSystemPromptContext, AgentTool, AgentToolContext, AgentToolInvokeContext, AgentToolInvokeResult, AgentTransport, AgentTransportBinding, ClientFrame, ClientSessionEvent, CompactionWindow, ConversationSummary, DEFAULT_TURN_RETRY_POLICY, DrainedTranscriptPatches, ExternalMutationReservation, InProcessTransportPair, JsonWebSocket, PrepareSessionShell, PrepareSessionShellContext, RunCommandLineCommandNotRegisteredError, RunCommandLineOptions, RunCommandLineResult, RunCommandLineSessionNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, ServerFrame, SessionEvent, SessionEventListener, ShellCommandStatusLike, ShellToolResultOptions, ShellToolView, StandardAgentToolOptions, TranscriptLog, TranscriptOptions, TranscriptPatch, TurnRetryPolicy, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, finishShellToolResult, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as cloneBlocks, i as applyTranscriptPatches, n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-Bod0puog.mjs";
+import { a as cloneBlocks, i as applyTranscriptPatches, n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-CcSuuo4T.mjs";
 import { AbortError, abortable, asError, asRecord, asString, bytesToBase64, 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";
@@ -9,7 +9,7 @@ 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 Transcript = class {
+var TranscriptLog = class {
 	blocks;
 	idFactory;
 	now;
@@ -24,7 +24,7 @@ var Transcript = class {
 		this.replayHeadChars = options.replayTextBounds?.headChars ?? DEFAULT_MODEL_TEXT_HEAD_CHARS;
 		this.replayTailChars = options.replayTextBounds?.tailChars ?? DEFAULT_MODEL_TEXT_TAIL_CHARS;
 	}
-	snapshot() {
+	toJSON() {
 		return { blocks: structuredClone(this.blocks) };
 	}
 	/** Monotonic revision, advanced once per drained patch batch. */
@@ -173,7 +173,7 @@ var Transcript = class {
 				status: "executing",
 				streamingOutput: [],
 				output: [],
-				metadata: null
+				view: null
 			});
 			case "response": return this.appendBlock({
 				type: "response",
@@ -193,14 +193,14 @@ var Transcript = class {
 			case "abort": return this.pushAbort(model);
 		}
 	}
-	completeToolCall(toolUseId, output, isError = false, metadata = null) {
+	completeToolCall(toolUseId, output, isError = false, view = 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.metadata = metadata;
+		block.view = view;
 		this.recordBlockReplace(index);
 		return block;
 	}
@@ -379,9 +379,15 @@ var Transcript = 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() {
-		const anchor = this.usageAnchor();
+	estimateContextTokens(contextWindow) {
+		let anchor = this.usageAnchor();
+		if (anchor !== null && contextWindow !== void 0 && contextWindow > 0 && anchor.tokens > contextWindow) anchor = null;
 		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]);
@@ -823,9 +829,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() < threshold) return;
+		if (this.host.transcript.estimateContextTokens(contextWindow) < threshold) return;
 		await this.host.runWithCompactingPhase(async () => {
-			for (let attempt = 0; attempt < 8 && this.host.transcript.estimateContextTokens() >= threshold; attempt += 1) if (!await this.run()) break;
+			for (let attempt = 0; attempt < 8 && this.host.transcript.estimateContextTokens(contextWindow) >= threshold; attempt += 1) if (!await this.run()) break;
 		});
 	}
 	/** Runs one compaction pass before a turn when the current model is over threshold. */
@@ -833,7 +839,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() < threshold) return;
+		if (this.host.transcript.estimateContextTokens(contextWindow) < threshold) return;
 		await this.host.runWithCompactingPhase(() => this.run());
 	}
 	/** Runs one compaction pass; returns whether it compacted anything. */
@@ -863,7 +869,7 @@ var CompactionController = class {
 		return false;
 	}
 	async generateSummary(blocks) {
-		const rendered = renderItemsForSummary(new Transcript(blocks).collectInferenceItems());
+		const rendered = renderItemsForSummary(new TranscriptLog(blocks).collectInferenceItems());
 		const policy = this.host.retryPolicy;
 		for (let attempt = 1;; attempt += 1) {
 			const request = buildCompactionSummaryRequest(rendered, {
@@ -1026,7 +1032,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.metadata ?? result.continuation ?? null);
+				this.host.transcript.completeToolCall(toolCall.toolUseId, result.output, result.isError ?? false, result.view ?? null);
 				await this.host.runtime.lifecycle?.({
 					type: "after_tool_call",
 					agentSessionId: this.host.agentSessionId,
@@ -1079,7 +1085,10 @@ var ProviderTurnLoop = class {
 					text: `Tool failed: ${normalized.message}`
 				}],
 				isError: true,
-				metadata: { error: normalized.message }
+				view: {
+					kind: "tool_error",
+					error: normalized.message
+				}
 			};
 		}
 	}
@@ -1164,21 +1173,21 @@ var AgentSession = class AgentSession {
 	persistTimer = null;
 	persistDirty = false;
 	/**
-	* Restores a session from a snapshot. Ownership of the snapshot (including
+	* Restores a session from a checkpoint. Ownership of the checkpoint (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 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;
+	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;
 		return new AgentSession({
 			provider: params.provider,
-			model: snapshot.model,
-			cwd: snapshot.cwd,
+			model: checkpoint.model,
+			cwd: checkpoint.cwd,
 			runtime: params.runtime,
-			transcript: snapshot.transcript,
-			state: snapshot.state
+			transcript: checkpoint.transcript,
+			state: checkpoint.state
 		}, options);
 	}
 	constructor(params, options = {}) {
@@ -1201,7 +1210,7 @@ var AgentSession = class AgentSession {
 			idFactory: this.idFactory,
 			now: options.now
 		};
-		this.transcriptLog = params.transcript instanceof Transcript ? params.transcript : new Transcript(params.transcript?.blocks ?? [], transcriptOptions);
+		this.transcriptLog = params.transcript instanceof TranscriptLog ? params.transcript : new TranscriptLog(params.transcript?.blocks ?? [], transcriptOptions);
 		const self = this;
 		const compactionHost = {
 			get transcript() {
@@ -1429,7 +1438,7 @@ var AgentSession = class AgentSession {
 					`durationMs: ${durationMs}`
 				].join("\n")
 			}],
-			metadata: {
+			view: {
 				kind: "yield_wakeup",
 				wakeupId,
 				durationMs
@@ -1948,7 +1957,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
-	* snapshot write. Boundaries (action end, abort, dispose) flush the write.
+	* checkpoint write. Boundaries (action end, abort, dispose) flush the write.
 	*/
 	async commitTranscript() {
 		const drained = this.transcriptLog.takePatches();
@@ -1965,7 +1974,7 @@ var AgentSession = class AgentSession {
 		if (this.persistTimer) return;
 		this.persistTimer = setTimeout(() => {
 			this.persistTimer = null;
-			this.persistSnapshot().catch((error) => {
+			this.persistCheckpoint().catch((error) => {
 				this.emit({
 					type: "error",
 					error: asError(error)
@@ -1973,11 +1982,11 @@ var AgentSession = class AgentSession {
 			});
 		}, this.persistIntervalMs);
 	}
-	async persistSnapshot() {
+	async persistCheckpoint() {
 		if (!this.store || !this.persistDirty) return;
 		this.persistDirty = false;
-		await this.store.saveSnapshot({
-			transcript: this.transcriptLog.snapshot(),
+		await this.store.saveCheckpoint({
+			transcript: this.transcriptLog.toJSON(),
 			state: structuredClone(this.agentState),
 			phase: this.currentPhase,
 			queue: structuredClone(this.queuedMessages()),
@@ -1991,7 +2000,7 @@ var AgentSession = class AgentSession {
 			clearTimeout(this.persistTimer);
 			this.persistTimer = null;
 		}
-		await this.persistSnapshot();
+		await this.persistCheckpoint();
 	}
 	emit(event) {
 		for (const listener of this.listeners) listener(event);
@@ -2212,7 +2221,7 @@ function createStandardAgentTools(options) {
 function shellPreviewBudgetTokens(contextWindow) {
 	return contextWindow >= LARGE_CONTEXT_THRESHOLD_TOKENS ? LARGE_CONTEXT_PREVIEW_TOKENS : SMALL_CONTEXT_PREVIEW_TOKENS;
 }
-function toShellToolResult(result, toolCallId = "", options = {}) {
+function toShellToolResult(result, options = {}) {
 	const output = [{
 		type: "text",
 		text: formatShellToolResult(result, options)
@@ -2228,13 +2237,61 @@ function toShellToolResult(result, toolCallId = "", options = {}) {
 	return {
 		output,
 		isError: false,
-		metadata: result,
-		continuation: result.status === "running" ? {
-			toolCallId,
-			shellId: result.shellId,
-			commandId: result.commandId,
-			status: "running"
-		} : void 0
+		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
 	};
 }
 /**
@@ -2322,8 +2379,8 @@ function repeatedShellExecResult(environment, agentSessionId, script) {
 			].join("\n")
 		}],
 		isError: true,
-		metadata: {
-			kind: "repeated_identical_shell_exec",
+		view: {
+			kind: "repeated_shell_exec",
 			script,
 			count
 		}
@@ -2381,7 +2438,7 @@ 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, ctx.toolCallId, {
+	const toolResult = toShellToolResult(result, {
 		includePreview: true,
 		previewBudgetTokens,
 		exposeCommandHandle,
@@ -2478,8 +2535,8 @@ var AgentServer = class {
 /**
 * 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 snapshot) before the new open
-* proceeds, so two connections never write the same snapshot key concurrently.
+* binding's session is closed (flushing its checkpoint) before the new open
+* proceeds, so two connections never write the same checkpoint key concurrently.
 */
 var SessionOwnershipRegistry = class {
 	holders = /* @__PURE__ */ new Map();
@@ -2683,7 +2740,7 @@ var AgentTransportBindingImpl = class {
 				case "sync_transcript": {
 					const session = this.sessionFor("sync_transcript");
 					if (!session) return;
-					this.sendTranscriptSnapshot(session);
+					this.sendTranscriptReset(session);
 					return;
 				}
 				case "close":
@@ -2715,9 +2772,9 @@ var AgentTransportBindingImpl = class {
 			cwd: frame.cwd
 		});
 		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 checkpoint = await store.loadCheckpoint();
+		const restoring = checkpoint !== null && checkpoint.harnessName === agent.name;
+		const state = restoring ? structuredClone(checkpoint.state) : initialState;
 		const harnessContext = {
 			state,
 			cwd: frame.cwd
@@ -2758,11 +2815,11 @@ var AgentTransportBindingImpl = class {
 			lifecycle: (event) => agent.lifecycle?.(event),
 			tools: () => tools
 		};
-		const session = restoring ? AgentSession.fromSnapshot({
+		const session = restoring ? AgentSession.fromCheckpoint({
 			provider,
 			runtime,
-			snapshot: {
-				...snapshot,
+			checkpoint: {
+				...checkpoint,
 				state
 			}
 		}, {
@@ -2790,7 +2847,7 @@ var AgentTransportBindingImpl = class {
 		if (restoring) session.updateModel(null, frame.provider.model);
 		this.unsubscribeSession = this.session.subscribe((event) => this.handleSessionEvent(event));
 		this.send({ type: "opened" });
-		this.sendTranscriptSnapshot(session);
+		this.sendTranscriptReset(session);
 		this.send({
 			type: "phase",
 			phase: this.session.phase()
@@ -2800,10 +2857,10 @@ var AgentTransportBindingImpl = class {
 			queue: this.session.queuedMessages()
 		});
 	}
-	sendTranscriptSnapshot(session) {
+	sendTranscriptReset(session) {
 		const transcript = session.transcript();
 		this.send({
-			type: "transcript_snapshot",
+			type: "transcript_reset",
 			blocks: cloneBlocks(transcript.blocks),
 			revision: transcript.revision
 		});
@@ -2906,10 +2963,10 @@ var AgentTransportBindingImpl = class {
 		const keys = await host.store.list("agent-sessions/");
 		const conversations = [];
 		for (const key of keys) {
-			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));
+			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));
 		}
 		conversations.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
 		this.send({
@@ -3002,7 +3059,7 @@ var AgentTransportBindingImpl = class {
 			type: "shell_output",
 			shellId: shell.shellId,
 			commandId: shell.commandId,
-			snapshot: shell.snapshot
+			status: shell.status
 		});
 		const audit = progressToAudit(progress);
 		if (audit.length > 0) this.send({
@@ -3016,7 +3073,7 @@ var AgentTransportBindingImpl = class {
 			type: "shell_output",
 			shellId: shell.shellId,
 			commandId: shell.commandId,
-			snapshot: shell.snapshot
+			status: shell.status
 		});
 		const audit = progressToAudit(progress);
 		if (audit.length > 0) this.send({
@@ -3055,15 +3112,15 @@ var HostAgentSessionStore = class {
 		this.store = store;
 		this.agentSessionId = agentSessionId;
 	}
-	saveSnapshot(snapshot) {
-		return this.store.writeJson(`agent-sessions/${this.agentSessionId}/snapshot.json`, snapshot);
+	saveCheckpoint(checkpoint) {
+		return this.store.writeJson(`agent-sessions/${this.agentSessionId}/checkpoint.json`, checkpoint);
 	}
-	loadSnapshot() {
-		return this.store.readJson(`agent-sessions/${this.agentSessionId}/snapshot.json`);
+	loadCheckpoint() {
+		return this.store.readJson(`agent-sessions/${this.agentSessionId}/checkpoint.json`);
 	}
 };
-function summarizeConversation(id, snapshot) {
-	const blocks = snapshot.transcript.blocks;
+function summarizeConversation(id, checkpoint) {
+	const blocks = checkpoint.transcript.blocks;
 	const first = blocks[0];
 	const last = blocks[blocks.length - 1];
 	return {
@@ -3097,14 +3154,14 @@ function progressToShellOutput(progress) {
 	if (!isRecord(progress.stdout) || !isRecord(progress.stderr)) return null;
 	const stdout = progress.stdout;
 	const stderr = progress.stderr;
-	if (!isStreamArtifact(stdout) || !isStreamArtifact(stderr) || typeof progress.runningMs !== "number" || typeof progress.idleMs !== "number") return null;
+	if (!isShellStreamView(stdout) || !isShellStreamView(stderr) || typeof progress.runningMs !== "number" || typeof progress.idleMs !== "number") return null;
 	return {
 		shellId: progress.shellId,
 		commandId: progress.commandId,
-		snapshot: progress
+		status: progress
 	};
 }
-function isStreamArtifact(value) {
+function isShellStreamView(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) {
@@ -3134,4 +3191,4 @@ function createProviderMap(providers) {
 	return map;
 }
 //#endregion
-export { AgentClient, AgentServer, AgentSession, DEFAULT_TURN_RETRY_POLICY, RunCommandLineCommandNotRegisteredError, RunCommandLineSessionNotFoundError, RunCommandLineTimeoutError, Transcript, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, finishShellToolResult, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };
+export { AgentClient, AgentServer, AgentSession, DEFAULT_TURN_RETRY_POLICY, RunCommandLineCommandNotRegisteredError, RunCommandLineSessionNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, TranscriptLog, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, finishShellToolResult, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };

package/dist/stdio-transport.d.mts

@@ -1,4 +1,4 @@
-import { n as AgentServerTransport, t as AgentClientTransport } from "./transport-DVa_82EW.mjs";
+import { n as AgentServerTransport, t as AgentClientTransport } from "./transport-0l1a6QD9.mjs";
 import { Readable, Writable } from "node:stream";
 //#region src/stdio-transport.d.ts
 declare function createStdioClientTransport(readable: Readable, writable: Writable): AgentClientTransport;

package/dist/{transport-DVa_82EW.d.mts → transport-0l1a6QD9.d.mts}

@@ -1,4 +1,4 @@
-import { BashAuditEvent, Command, Host, ShellCommandSnapshot } from "@demicodes/shell";
+import { BashAuditEvent, Command, Host, ShellCommandStatus } from "@demicodes/shell";
 import { AgentProvider, InferenceItem, ProviderEvent, ProviderSelection, ToolDefinition } from "@demicodes/provider";
 import { Block, ModelSelection, QueuedMessage, SessionPhase, ToolResultContentBlock, Transcript, UserContentBlock } from "@demicodes/core";
 //#region src/retry-policy.d.ts
@@ -48,7 +48,7 @@ interface DrainedTranscriptPatches {
   revision: number;
   patches: TranscriptPatch[];
 }
-declare class Transcript$1 implements Transcript {
+declare class TranscriptLog implements Transcript {
   readonly blocks: Block[];
   private readonly idFactory;
   private readonly now;
@@ -57,7 +57,7 @@ declare class Transcript$1 implements Transcript {
   private readonly replayHeadChars;
   private readonly replayTailChars;
   constructor(blocks?: Block[], options?: TranscriptOptions);
-  snapshot(): Transcript;
+  toJSON(): Transcript;
   /** Monotonic revision, advanced once per drained patch batch. */
   get revision(): number;
   /**
@@ -83,7 +83,7 @@ declare class Transcript$1 implements Transcript {
     type: 'user';
   }> | null;
   applyProviderEvent(model: ModelSelection, event: ProviderEvent): Block | null;
-  completeToolCall(toolUseId: string, output: ToolResultContentBlock[], isError?: boolean, metadata?: unknown | null): Block | null;
+  completeToolCall(toolUseId: string, output: ToolResultContentBlock[], isError?: boolean, view?: unknown | null): Block | null;
   findPendingToolUseId(): string | null;
   pendingToolCalls(): Extract<Block, {
     type: 'tool_call';
@@ -106,8 +106,13 @@ declare class Transcript$1 implements Transcript {
    * 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(): number;
+  estimateContextTokens(contextWindow?: number): number;
   /**
    * The latest response block's usage, valid only when no compaction happened
    * after it (compaction shrinks the history the usage was measured against).
@@ -126,7 +131,7 @@ interface AgentPromptContext<State> {
   agentSessionId: string;
   state: State;
   cwd: string;
-  transcript: Transcript$1;
+  transcript: TranscriptLog;
 }
 interface AgentSystemPromptContext<State> extends AgentPromptContext<State> {
   /**
@@ -146,13 +151,13 @@ interface AgentDisposeContext<State> {
   agentSessionId: string;
   state: State;
   cwd: string;
-  transcript: Transcript$1;
+  transcript: TranscriptLog;
 }
 interface AgentReferenceResolveContext<State> {
   agentSessionId: string;
   state: State;
   cwd: string;
-  transcript: Transcript$1;
+  transcript: TranscriptLog;
   signal: AbortSignal;
 }
 interface AgentHarnessContext<State> {
@@ -182,16 +187,10 @@ interface AgentToolInvokeContext<State> {
 interface AgentToolInvokeResult {
   output: ToolResultContentBlock[];
   isError?: boolean;
-  metadata?: unknown | null;
-  continuation?: ToolContinuation;
+  /** Bounded UI-facing view data stored on the tool_call block; see the core Block contract. */
+  view?: unknown | null;
   stopAfterToolResult?: boolean;
 }
-interface ToolContinuation {
-  toolCallId: string;
-  shellId: string;
-  commandId: string;
-  status: 'running';
-}
 type AbortTarget = 'active_provider_stream' | 'active_tool' | 'active_compaction' | 'active_turn' | 'queued_action' | 'queued_message' | 'pending_yield_wakeup';
 interface AbortResult {
   aborted: boolean;
@@ -205,13 +204,13 @@ type AgentLifecycleEvent<State> = {
   type: 'before_round_start';
   agentSessionId: string;
   state: State;
-  transcript: Transcript$1;
+  transcript: TranscriptLog;
   content: UserContentBlock[];
 } | {
   type: 'after_tool_call';
   agentSessionId: string;
   state: State;
-  transcript: Transcript$1;
+  transcript: TranscriptLog;
   toolCallId: string;
   toolName: string;
   result: AgentToolInvokeResult;
@@ -219,7 +218,7 @@ type AgentLifecycleEvent<State> = {
   type: 'after_transcript_rewrite';
   agentSessionId: string;
   state: State;
-  transcript: Transcript$1;
+  transcript: TranscriptLog;
   reason: 'retry';
 };
 interface AgentHarnessRuntime<State> {
@@ -237,10 +236,10 @@ interface AgentSessionParams<State> {
   model: ModelSelection;
   cwd: string;
   runtime: AgentHarnessRuntime<State>;
-  transcript?: Transcript | Transcript$1;
+  transcript?: Transcript | TranscriptLog;
   state?: State;
 }
-interface AgentSessionSnapshot<State> {
+interface AgentSessionCheckpoint<State> {
   transcript: Transcript;
   state: State;
   phase: SessionPhase;
@@ -250,14 +249,14 @@ interface AgentSessionSnapshot<State> {
   harnessName: string;
 }
 interface AgentSessionStore<State = unknown> {
-  saveSnapshot(snapshot: AgentSessionSnapshot<State>): Promise<void> | void;
-  /** Load a previously saved snapshot for this session, or null if none exists. */
-  loadSnapshot(): Promise<AgentSessionSnapshot<State> | null>;
+  saveCheckpoint(checkpoint: AgentSessionCheckpoint<State>): Promise<void> | void;
+  /** Load a previously saved checkpoint for this session, or null if none exists. */
+  loadCheckpoint(): Promise<AgentSessionCheckpoint<State> | null>;
 }
 interface AgentSessionRestoreParams<State> {
   provider: AgentProvider;
   runtime: AgentHarnessRuntime<State>;
-  snapshot: AgentSessionSnapshot<State>;
+  checkpoint: AgentSessionCheckpoint<State>;
 }
 interface AgentSessionOptions<State = unknown> {
   agentSessionId?: string;
@@ -269,7 +268,7 @@ interface AgentSessionOptions<State = unknown> {
     preflightThresholdRatio?: number;
   };
   /**
-   * Maximum interval between snapshot writes while a turn is streaming. Writes
+   * Maximum interval between checkpoint writes while a turn is streaming. Writes
    * always flush at action boundaries (turn end, abort, dispose); this only
    * bounds staleness during streaming. Default 1000ms.
    */
@@ -372,7 +371,7 @@ type ServerFrame = {
   command: string;
   reason: string;
 } | {
-  type: 'transcript_snapshot';
+  type: 'transcript_reset';
   blocks: Block[];
   revision: number;
 } | {
@@ -405,7 +404,7 @@ type ServerFrame = {
   type: 'shell_output';
   shellId: string;
   commandId: string;
-  snapshot: ShellCommandSnapshotLike;
+  status: ShellCommandStatusLike;
 } | {
   type: 'shell_write_result';
   commandId: string;
@@ -429,7 +428,7 @@ type ServerFrame = {
   type: 'closed';
 };
 /**
- * Wire patches for transcript replication. Produced directly by the Transcript's
+ * Wire patches for transcript replication. Produced directly by the TranscriptLog's
  * mutation journal (never diff-derived). `append_text` carries streaming deltas
  * for the `text` field of the block at the index (text/thinking blocks), keeping
  * per-delta cost O(delta) instead of O(block) or O(transcript).
@@ -454,9 +453,9 @@ type TranscriptPatch = {
   path: ['blocks'];
   value: Block[];
 };
-type ShellCommandSnapshotLike = ShellCommandSnapshot;
+type ShellCommandStatusLike = ShellCommandStatus;
 type ClientSessionEvent = {
-  type: 'transcript_snapshot';
+  type: 'transcript_reset';
   blocks: Block[];
 } | {
   type: 'transcript_patch';
@@ -488,7 +487,7 @@ type ClientSessionEvent = {
   type: 'shell_output';
   shellId: string;
   commandId: string;
-  snapshot: ShellCommandSnapshotLike;
+  status: ShellCommandStatusLike;
 } | {
   type: 'shell_write_result';
   commandId: string;
@@ -529,4 +528,4 @@ interface InProcessTransportPair {
 }
 declare function createInProcessTransportPair(): InProcessTransportPair;
 //#endregion
-export { AgentToolInvokeResult as A, DEFAULT_TURN_RETRY_POLICY as B, AgentSessionRestoreParams as C, AgentTool as D, AgentSystemPromptContext as E, CompactionWindow as F, isRetryableCode as H, DrainedTranscriptPatches as I, Transcript$1 as L, SessionEvent as M, SessionEventListener as N, AgentToolContext as O, ToolContinuation as P, TranscriptOptions as R, AgentSessionParams as S, AgentSessionStore as T, resolveRetryPolicy as U, TurnRetryPolicy as V, retryDelayMs as W, AgentHarnessRuntime as _, createInProcessTransportPair as a, AgentReferenceResolveContext as b, ConversationSummary as c, TranscriptPatch as d, AbortResult as f, AgentHarnessContext as g, AgentHarness as h, InProcessTransportPair as i, ExternalMutationReservation as j, AgentToolInvokeContext as k, ServerFrame as l, AgentDisposeContext as m, AgentServerTransport as n, ClientFrame as o, AbortTarget as p, AgentTransport as r, ClientSessionEvent as s, AgentClientTransport as t, ShellCommandSnapshotLike as u, AgentLifecycleEvent as v, AgentSessionSnapshot as w, AgentSessionOptions as x, AgentPromptContext as y, estimateTranscriptBlockTokens as z };
+export { AgentToolInvokeResult as A, TurnRetryPolicy as B, AgentSessionParams as C, AgentTool as D, AgentSystemPromptContext as E, DrainedTranscriptPatches as F, resolveRetryPolicy as H, TranscriptLog as I, TranscriptOptions as L, SessionEvent as M, SessionEventListener as N, AgentToolContext as O, CompactionWindow as P, estimateTranscriptBlockTokens as R, AgentSessionOptions as S, AgentSessionStore as T, retryDelayMs as U, isRetryableCode as V, AgentHarnessRuntime as _, createInProcessTransportPair as a, AgentReferenceResolveContext as b, ConversationSummary as c, TranscriptPatch as d, AbortResult as f, AgentHarnessContext as g, AgentHarness as h, InProcessTransportPair as i, ExternalMutationReservation as j, AgentToolInvokeContext as k, ServerFrame as l, AgentDisposeContext as m, AgentServerTransport as n, ClientFrame as o, AbortTarget as p, AgentTransport as r, ClientSessionEvent as s, AgentClientTransport as t, ShellCommandStatusLike as u, AgentLifecycleEvent as v, AgentSessionRestoreParams as w, AgentSessionCheckpoint as x, AgentPromptContext as y, DEFAULT_TURN_RETRY_POLICY as z };

package/dist/{websocket-transport-Cn_rhIIX.d.mts → websocket-transport-C0R8AiHD.d.mts}

@@ -1,4 +1,4 @@
-import { c as ConversationSummary, f as AbortResult, n as AgentServerTransport, s as ClientSessionEvent, t as AgentClientTransport } from "./transport-DVa_82EW.mjs";
+import { c as ConversationSummary, f as AbortResult, n as AgentServerTransport, s as ClientSessionEvent, t as AgentClientTransport } from "./transport-0l1a6QD9.mjs";
 import { ProviderSelection } from "@demicodes/provider";
 import { Block, UserContentBlock } from "@demicodes/core";
 //#region src/client.d.ts

package/dist/{websocket-transport-Bod0puog.mjs → websocket-transport-CcSuuo4T.mjs}

@@ -198,12 +198,12 @@ var AgentClient = class {
 	}
 	handleServerFrame(frame) {
 		switch (frame.type) {
-			case "transcript_snapshot":
+			case "transcript_reset":
 				this.blocks = [...frame.blocks];
 				this.revision = frame.revision;
 				this.awaitingResync = false;
 				this.emit({
-					type: "transcript_snapshot",
+					type: "transcript_reset",
 					blocks: this.blocks
 				});
 				return;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/agent",
   "description": "Session runtime and transport-neutral client and server protocol for Demi.",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "private": false,
   "type": "module",
   "exports": {
@@ -22,10 +22,10 @@
     }
   },
   "dependencies": {
-    "@demicodes/core": "^0.2.1",
-    "@demicodes/provider": "^0.2.1",
-    "@demicodes/shell": "^0.2.1",
-    "@demicodes/utils": "^0.2.1"
+    "@demicodes/core": "^0.3.1",
+    "@demicodes/provider": "^0.3.1",
+    "@demicodes/shell": "^0.3.1",
+    "@demicodes/utils": "^0.3.1"
   },
   "license": "Apache-2.0",
   "main": "./dist/index.mjs",