@code-yeongyu/senpi 2026.7.11 → 2026.7.13

package/node_modules/@code-yeongyu/senpi-codemode/src/tool/eval-tool.ts

@@ -1,15 +1,20 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
 import type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext, ToolDefinition } from "@code-yeongyu/senpi";
-import type { HostToKernelMessage, KernelToHostMessage } from "../bridge/protocol.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
+import { defaultCodemodeSettings, type ResolvedCodemodeSettings } from "../config/settings.ts";
+import type { EvalExecutionTracker } from "../extension/session-manager.ts";
 import { buildEvalPrompt } from "../prompt/eval-prompt.ts";
+import { TIMEOUT_PAUSE_OP, TIMEOUT_RESUME_OP } from "../timeouts/bridge-timeout.ts";
+import { IdleTimeout } from "../timeouts/idle-timeout.ts";
 import { CellHandler, type CellState } from "./cell-handler.ts";
-import { renderEvalCall, renderEvalResult } from "./render.ts";
+import type { EvalImageResizer } from "./image.ts";
 import {
 	createEvalInputSchema,
 	type EnabledEvalLanguages,
+	type EvalInputSchema,
 	type EvalKernel,
 	type EvalKernelManager,
-	type EvalKernelRunInput,
 	type EvalToolDetails,
 	type EvalToolInput,
 	type ExecuteTool,
@@ -24,111 +29,86 @@ export interface CreateEvalToolOptions {
 	readonly cellTimeoutSeconds: number;
 	readonly executeTool: ExecuteTool;
 	readonly complete?: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>;
+	readonly settings?: ResolvedCodemodeSettings;
+	readonly artifactsDir?: string;
+	readonly imageResizer?: EvalImageResizer;
+	readonly executionTracker?: EvalExecutionTracker;
+	readonly proxyExecutor?: (params: EvalToolInput, signal?: AbortSignal) => Promise<AgentToolResult<EvalToolDetails>>;
+	readonly renderers?: Pick<ToolDefinition<EvalInputSchema, EvalToolDetails>, "renderCall" | "renderResult">;
+	/** Whether the task-tool spawn helpers (agent()/output()/<dag>) are advertised in the prompt. */
+	readonly spawns?: boolean;
+	/** Default agent name surfaced in the agent() helper docs when spawns are enabled. */
+	readonly spawnDefaultAgent?: string;
 }
 
 interface EvalCellInvocation {
 	readonly cellId: string;
 	readonly input: EvalToolInput;
-	readonly signal: AbortSignal | undefined;
+	readonly signal: AbortSignal;
 	readonly onUpdate: AgentToolUpdateCallback<EvalToolDetails> | undefined;
 	readonly ctx: ExtensionContext;
 }
 
-type ToolReply = Extract<HostToKernelMessage, { type: "tool-reply" }>;
+interface CellExecutionOptions {
+	readonly callerSignal: AbortSignal;
+	readonly cellId: string;
+	readonly onAbort: (error: Error) => void;
+	readonly timeoutMs: number;
+}
 
 const INTERRUPT_DELIVERY_GRACE_MS = 100;
 
-class CellKernel implements EvalKernel {
-	readonly #kernel: EvalKernel;
-	readonly #state: CellState;
-
-	constructor(kernel: EvalKernel, state: CellState) {
-		this.#kernel = kernel;
-		this.#state = state;
-	}
-
-	run(input: EvalKernelRunInput): Promise<Extract<KernelToHostMessage, { type: "result" }>> {
-		return this.#kernel.run(input);
-	}
-
-	deliverToolReply(message: ToolReply): void {
-		if (this.#state.active) this.#kernel.deliverToolReply(message);
-	}
-
-	interrupt(reason?: string): Promise<void> {
-		return this.#kernel.interrupt(reason);
-	}
-
-	reset(): Promise<void> {
-		return this.#kernel.reset();
-	}
-
-	close(): Promise<void> {
-		return this.#kernel.close();
-	}
-}
-
 class CellExecution {
-	readonly #callerSignal: AbortSignal | undefined;
-	readonly #timeoutMs: number;
+	readonly #callerSignal: AbortSignal;
 	readonly #onAbort: (error: Error) => void;
 	readonly #abortPromise: Promise<never>;
-	#rejectAbort: (reason?: unknown) => void = () => {};
-	#kernel: CellKernel | undefined;
-	#deadline: ReturnType<typeof setTimeout> | undefined;
-	#abortSettled = false;
+	readonly #watchdog: IdleTimeout;
+	#rejectAbort: ((reason?: unknown) => void) | undefined;
+	#kernel: EvalKernel | undefined;
+	#interruptDeadline: ReturnType<typeof setTimeout> | undefined;
 	#active = true;
 
-	constructor(callerSignal: AbortSignal | undefined, timeoutMs: number, onAbort: (error: Error) => void) {
-		this.#callerSignal = callerSignal;
-		this.#timeoutMs = timeoutMs;
-		this.#onAbort = onAbort;
+	constructor(options: CellExecutionOptions) {
+		this.#callerSignal = options.callerSignal;
+		this.#onAbort = options.onAbort;
 		this.#abortPromise = new Promise<never>((_resolve, reject) => {
 			this.#rejectAbort = reject;
 		});
-		callerSignal?.addEventListener("abort", this.#handleCallerAbort, { once: true });
-		this.startDeadline();
+		this.#watchdog = new IdleTimeout({
+			cellId: options.cellId,
+			timeoutMs: options.timeoutMs,
+			onTimeout: ({ error }) => this.#abort(error),
+		});
+		this.#callerSignal.addEventListener("abort", this.#handleCallerAbort, { once: true });
 	}
 
-	startDeadline(): void {
-		this.clearDeadline();
-		if (!this.#active) return;
-		this.#deadline = setTimeout(() => {
-			const error = new Error(`Cell timed out after ${this.#timeoutMs}ms`);
-			error.name = "TimeoutError";
-			this.#abort(error);
-		}, this.#timeoutMs);
+	pause(): void {
+		this.#watchdog.pause();
 	}
-
-	clearDeadline(): void {
-		if (this.#deadline === undefined) return;
-		clearTimeout(this.#deadline);
-		this.#deadline = undefined;
+	resume(): void {
+		this.#watchdog.resume();
 	}
-
-	setKernel(kernel: CellKernel): void {
+	setKernel(kernel: EvalKernel): void {
 		this.#kernel = kernel;
 	}
-
 	cancel(reason: unknown): void {
 		this.#abort(reason);
 	}
-
-	async wait<T>(operation: Promise<T>): Promise<T> {
-		const guardedOperation = operation.then(
-			(value): T | Promise<never> => (this.#active ? value : this.#abortPromise),
-			(reason: unknown): Promise<never> => (this.#active ? Promise.reject(reason) : this.#abortPromise),
-		);
-		return await Promise.race([guardedOperation, this.#abortPromise]);
-	}
-
 	finish(): void {
 		this.#active = false;
 		this.#cleanup();
 	}
 
+	async wait<Result>(operation: Promise<Result>): Promise<Result> {
+		const guarded = operation.then(
+			(value): Result | Promise<never> => (this.#active ? value : this.#abortPromise),
+			(reason: unknown): Promise<never> => (this.#active ? Promise.reject(reason) : this.#abortPromise),
+		);
+		return await Promise.race([guarded, this.#abortPromise]);
+	}
+
 	readonly #handleCallerAbort = (): void => {
-		this.#abort(this.#callerSignal?.reason);
+		this.#abort(this.#callerSignal.reason);
 	};
 
 	#abort(reason: unknown): void {
@@ -138,11 +118,11 @@ class CellExecution {
 		const error = abortError(reason);
 		this.#onAbort(error);
 		const kernel = this.#kernel;
-		if (!kernel) {
+		if (kernel === undefined) {
 			this.#settleAbort(error);
 			return;
 		}
-		this.#deadline = setTimeout(() => this.#settleAbort(error), INTERRUPT_DELIVERY_GRACE_MS);
+		this.#interruptDeadline = setTimeout(() => this.#settleAbort(error), INTERRUPT_DELIVERY_GRACE_MS);
 		void Promise.resolve()
 			.then(() => kernel.interrupt(error.message))
 			.then(
@@ -152,23 +132,27 @@ class CellExecution {
 	}
 
 	#settleAbort(reason: unknown): void {
-		if (this.#abortSettled) return;
-		this.#abortSettled = true;
-		this.clearDeadline();
-		this.#rejectAbort(reason);
+		const reject = this.#rejectAbort;
+		if (reject === undefined) return;
+		this.#rejectAbort = undefined;
+		if (this.#interruptDeadline !== undefined) clearTimeout(this.#interruptDeadline);
+		reject(reason);
 	}
 
 	#cleanup(): void {
-		this.#callerSignal?.removeEventListener("abort", this.#handleCallerAbort);
-		this.clearDeadline();
+		this.#callerSignal.removeEventListener("abort", this.#handleCallerAbort);
+		this.#watchdog.dispose();
+		if (this.#interruptDeadline !== undefined) clearTimeout(this.#interruptDeadline);
+		this.#interruptDeadline = undefined;
 	}
 }
 
-export function createEvalTool(
-	options: CreateEvalToolOptions,
-): ToolDefinition<ReturnType<typeof createEvalInputSchema>, EvalToolDetails> {
+export function createEvalTool(options: CreateEvalToolOptions): ToolDefinition<EvalInputSchema, EvalToolDetails> {
 	const parameters = createEvalInputSchema(options.enabledLanguages);
-	const prompt = buildEvalPrompt(options.enabledLanguages);
+	const prompt = buildEvalPrompt(options.enabledLanguages, {
+		spawns: options.spawns ?? false,
+		...(options.spawnDefaultAgent === undefined ? {} : { spawnDefaultAgent: options.spawnDefaultAgent }),
+	});
 	const languages = enabledLanguageList(options.enabledLanguages);
 	return {
 		name: "eval",
@@ -178,15 +162,29 @@ export function createEvalTool(
 		promptGuidelines: [...prompt.promptGuidelines],
 		parameters,
 		executionMode: "sequential",
-		renderCall: renderEvalCall,
-		renderResult: renderEvalResult,
+		...(options.renderers?.renderCall === undefined ? {} : { renderCall: options.renderers.renderCall }),
+		...(options.renderers?.renderResult === undefined ? {} : { renderResult: options.renderers.renderResult }),
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			if (!languages.includes(params.language)) {
-				throw new Error(
+			if (options.proxyExecutor) return await options.proxyExecutor(params, signal);
+			if (!languages.includes(params.language))
+				throw new RangeError(
 					`Unsupported eval language "${params.language}". Enabled languages: ${languages.join(", ")}`,
 				);
-			}
-			return await runEvalCell(options, { cellId: toolCallId, input: params, signal, onUpdate, ctx });
+			options.executionTracker?.assertEvalExecutionAllowed();
+			const lifecycleController = new AbortController();
+			const combinedSignal = signal
+				? AbortSignal.any([signal, lifecycleController.signal])
+				: lifecycleController.signal;
+			const execution = runEvalCell(options, {
+				cellId: toolCallId,
+				input: params,
+				signal: combinedSignal,
+				onUpdate,
+				ctx,
+			});
+			return options.executionTracker
+				? await options.executionTracker.trackEvalExecution(execution, lifecycleController)
+				: await execution;
 		},
 	};
 }
@@ -195,75 +193,87 @@ async function runEvalCell(
 	options: CreateEvalToolOptions,
 	invocation: EvalCellInvocation,
 ): Promise<AgentToolResult<EvalToolDetails>> {
-	if (invocation.signal?.aborted) throw abortError(invocation.signal.reason);
-	const timeoutMs = Math.floor((invocation.input.timeout ?? options.cellTimeoutSeconds) * 1000);
+	if (invocation.signal.aborted) throw abortError(invocation.signal.reason);
+	const timeoutMs = Math.floor((invocation.input.timeout ?? options.cellTimeoutSeconds) * 1_000);
 	const bridgeAbortController = new AbortController();
-	const cellSignal = invocation.signal
-		? AbortSignal.any([invocation.signal, bridgeAbortController.signal])
-		: bridgeAbortController.signal;
+	const cellSignal = AbortSignal.any([invocation.signal, bridgeAbortController.signal]);
 	const bridgeContext: ExtensionContext = { ...invocation.ctx, signal: cellSignal };
 	const state: CellState = {
-		cellId: invocation.cellId,
-		language: invocation.input.language,
-		title: invocation.input.title,
+		input: invocation.input,
 		signal: cellSignal,
 		onUpdate: invocation.onUpdate,
 		toolCalls: [],
-		images: [],
 		pendingBridgeCalls: [],
+		statusEvents: [],
 		active: true,
 		output: "",
 		phase: undefined,
 		durationMs: 0,
+		status: "pending",
 	};
-	const execution = new CellExecution(invocation.signal, timeoutMs, (error) => {
-		state.active = false;
-		bridgeAbortController.abort(error);
+	const execution = new CellExecution({
+		callerSignal: invocation.signal,
+		cellId: invocation.cellId,
+		onAbort: (error) => {
+			state.active = false;
+			bridgeAbortController.abort(error);
+		},
+		timeoutMs,
 	});
 	let handler: CellHandler | undefined;
 	try {
 		const acquired = await execution.wait(
 			options.kernelManager.getKernel(invocation.input.language, (message) => {
 				if (!state.active || !handler) return;
+				if (message.type === "status") {
+					if (message.event.op === TIMEOUT_PAUSE_OP) {
+						execution.pause();
+						return;
+					}
+					if (message.event.op === TIMEOUT_RESUME_OP) {
+						execution.resume();
+						return;
+					}
+				}
 				const pending = handler.handle(message);
 				void pending.catch((error: unknown) => execution.cancel(error));
 			}),
 		);
-		const kernel = new CellKernel(acquired, state);
+		const kernel = acquired;
 		execution.setKernel(kernel);
-		execution.clearDeadline();
 		handler = new CellHandler(kernel, state, {
 			executeTool: options.executeTool,
-			complete: options.complete,
+			settings: options.settings ?? defaultCodemodeSettings,
+			...(options.complete === undefined ? {} : { complete: options.complete }),
 			ctx: bridgeContext,
+			...(options.artifactsDir === undefined
+				? {}
+				: { artifactPath: join(options.artifactsDir, `eval-${randomUUID()}.log`) }),
+			...(options.imageResizer === undefined ? {} : { imageResizer: options.imageResizer }),
 		});
 		if ("setContext" in options.kernelManager && typeof options.kernelManager.setContext === "function") {
 			options.kernelManager.setContext(bridgeContext);
 		}
-		if (invocation.input.reset) {
-			execution.startDeadline();
-			await execution.wait(kernel.reset());
-			execution.clearDeadline();
-		}
-		const result = await execution.wait(
-			kernel.run({ cellId: invocation.cellId, code: invocation.input.code, timeoutMs }),
-		);
-		if (result.ok && state.pendingBridgeCalls.length > 0) {
-			execution.startDeadline();
-			await execution.wait(Promise.all(state.pendingBridgeCalls));
-			execution.clearDeadline();
+		if (invocation.input.reset) await execution.wait(kernel.reset());
+		const result = await execution.wait(kernel.run({ cellId: invocation.cellId, code: invocation.input.code }));
+		if (result.ok && state.pendingBridgeCalls.length > 0) await execution.wait(Promise.all(state.pendingBridgeCalls));
+		return await handler.finalize(result);
+	} catch (error) {
+		if (handler && error instanceof Error && error.name === "CodemodeSessionDisposedError") {
+			return await handler.finalizeCancellation(error);
 		}
-		return handler.finalize(result);
+		throw error;
 	} finally {
 		state.active = false;
 		bridgeAbortController.abort();
 		execution.finish();
+		if (handler) await handler.flushOutput();
 	}
 }
 
 function abortError(reason: unknown): Error {
 	if (reason instanceof Error && reason.name !== "AbortError") return reason;
-	const error = new Error(typeof reason === "string" ? reason : "Eval interrupted");
+	const error = new Error(typeof reason === "string" ? reason : "Eval interrupted", { cause: reason });
 	error.name = "AbortError";
 	return error;
 }

package/node_modules/@code-yeongyu/senpi-codemode/src/tool/image.ts

@@ -0,0 +1,274 @@
+import { writeFile } from "node:fs/promises";
+import type { AgentToolResult, ExtensionContext } from "@code-yeongyu/senpi";
+import { convertToPng, formatDimensionNote, resizeImage } from "@code-yeongyu/senpi";
+import type { KernelToHostMessage } from "../bridge/protocol.ts";
+import type { TruncationMeta } from "../output/output-meta.ts";
+import {
+	artifactNotice,
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	OutputSink,
+	type OutputSummary,
+	TailBuffer,
+	truncateTail,
+} from "../output/streaming-output.ts";
+
+const MAX_DISPLAY_TEXT_BYTES = 8_000;
+
+export interface EvalImageContent {
+	readonly type: "image";
+	readonly data: string;
+	readonly mimeType: string;
+}
+
+export interface EvalImageResizeResult {
+	readonly image: EvalImageContent;
+	readonly dimensionNote?: string;
+}
+
+export type EvalImageResizer = (
+	image: EvalImageContent,
+	model: ExtensionContext["model"],
+) => Promise<EvalImageResizeResult>;
+
+export interface EvalOutputOptions {
+	readonly artifactPath?: string;
+	readonly headBytes: number;
+	readonly maxColumns: number;
+	readonly model: ExtensionContext["model"];
+	readonly imageResizer?: EvalImageResizer;
+	readonly onChunk: (aggregateText: string, cellText: string) => void;
+}
+
+export interface EvalOutputResult {
+	readonly output: string;
+	readonly images: readonly EvalImageContent[];
+	readonly jsonOutputs: readonly unknown[];
+	readonly hasMarkdown: boolean;
+	readonly truncated: boolean;
+	readonly notice?: string;
+	readonly meta?: TruncationMeta;
+}
+
+type DisplayMessage = Extract<KernelToHostMessage, { type: "display" }>;
+type WebpModel = { readonly provider: string; readonly api: string } | undefined;
+
+class DisplayPayloadError extends Error {
+	readonly name = "DisplayPayloadError";
+
+	constructor(mimeType: string, cause: SyntaxError) {
+		super(`Invalid ${mimeType} display payload: ${cause.message}`, { cause });
+	}
+}
+
+export class EvalOutputCollector {
+	readonly #options: EvalOutputOptions;
+	readonly #sink: OutputSink;
+	readonly #aggregateTail = new TailBuffer(DEFAULT_MAX_BYTES * 2);
+	readonly #cellTail = new TailBuffer(DEFAULT_MAX_BYTES * 2);
+	readonly #displayImages: EvalImageContent[] = [];
+	readonly #images: EvalImageContent[] = [];
+	readonly #jsonOutputs: unknown[] = [];
+	#hasMarkdown = false;
+	#imagesProcessed = false;
+
+	constructor(options: EvalOutputOptions) {
+		this.#options = options;
+		this.#sink = new OutputSink({
+			artifactPath: options.artifactPath,
+			headBytes: options.headBytes,
+			maxColumns: options.maxColumns,
+			onChunk: (chunk) => {
+				this.#aggregateTail.append(chunk);
+				this.#cellTail.append(chunk);
+				options.onChunk(this.#aggregateTail.text(), this.#cellTail.text());
+			},
+		});
+	}
+
+	push(text: string): void {
+		this.#sink.push(text);
+	}
+
+	display(message: DisplayMessage): void {
+		if (message.mimeType.startsWith("image/")) {
+			this.#displayImages.push({ type: "image", mimeType: message.mimeType, data: message.dataBase64 });
+			return;
+		}
+		const text = Buffer.from(message.dataBase64, "base64").toString("utf8");
+		if (message.mimeType === "application/json") {
+			let value: unknown;
+			try {
+				value = JSON.parse(text);
+			} catch (error) {
+				if (error instanceof SyntaxError) throw new DisplayPayloadError(message.mimeType, error);
+				throw error;
+			}
+			this.#jsonOutputs.push(value);
+			this.#sink.push(`display[${this.#jsonOutputs.length}]:\n${formatDisplayJson(value)}\n`);
+			return;
+		}
+		if (message.mimeType === "text/markdown") this.#hasMarkdown = true;
+		this.#sink.push(text.endsWith("\n") ? text : `${text}\n`);
+	}
+
+	aggregateText(): string {
+		return this.#aggregateTail.text();
+	}
+
+	async finish(): Promise<EvalOutputResult> {
+		await this.#processImages();
+		const summary = await this.#finalSummary();
+		const meta = truncationMetaFromSummary(summary);
+		const notice = summary.artifactId === undefined ? undefined : artifactNotice(summary.artifactId);
+		return {
+			output: summary.output.trimEnd(),
+			images: [...this.#images],
+			jsonOutputs: [...this.#jsonOutputs],
+			hasMarkdown: this.#hasMarkdown,
+			truncated: summary.truncated,
+			...(notice === undefined ? {} : { notice }),
+			...(meta === undefined ? {} : { meta }),
+		};
+	}
+
+	async flush(): Promise<void> {
+		await this.#sink.dump();
+	}
+
+	async #processImages(): Promise<void> {
+		if (this.#imagesProcessed) return;
+		this.#imagesProcessed = true;
+		const resize = this.#options.imageResizer ?? resizeEvalImage;
+		for (const source of this.#displayImages) {
+			const resized = await resize(source, this.#options.model);
+			this.#images.push(resized.image);
+			const description = resized.dimensionNote ?? `[${resized.image.mimeType}]`;
+			this.#sink.push(`display image ${this.#images.length}: ${description}\n`);
+		}
+	}
+
+	async #finalSummary(): Promise<OutputSummary> {
+		const summary = await this.#sink.dump();
+		if (summary.truncated || summary.totalLines <= DEFAULT_MAX_LINES) return summary;
+		const truncated = truncateTail(summary.output, {
+			maxLines: DEFAULT_MAX_LINES,
+			maxBytes: Number.MAX_SAFE_INTEGER,
+		});
+		let artifactId = summary.artifactId;
+		if (artifactId === undefined && this.#options.artifactPath !== undefined) {
+			await writeFile(this.#options.artifactPath, this.#aggregateTail.text(), "utf8");
+			artifactId = this.#options.artifactPath;
+		}
+		return {
+			...summary,
+			output: truncated.content,
+			truncated: true,
+			outputLines: truncated.outputLines,
+			outputBytes: truncated.outputBytes,
+			...(artifactId === undefined ? {} : { artifactId }),
+		};
+	}
+}
+
+export function webpExclusionForModel(model: WebpModel): true | undefined {
+	if (model === undefined) return undefined;
+	return model.provider === "ollama" ||
+		model.provider === "ollama-cloud" ||
+		model.provider === "llama.cpp" ||
+		model.provider === "lm-studio" ||
+		model.provider === "local-server" ||
+		model.api === "ollama-chat"
+		? true
+		: undefined;
+}
+
+export const resizeEvalImage: EvalImageResizer = async (image, model) => {
+	const excludeWebP = webpExclusionForModel(model);
+	const forceWebpConversion = excludeWebP === true && image.mimeType === "image/webp";
+	const resized = await resizeImage(
+		Buffer.from(image.data, "base64"),
+		image.mimeType,
+		forceWebpConversion ? { maxBytes: Buffer.byteLength(image.data, "utf8") } : undefined,
+	);
+	let output: EvalImageContent =
+		resized === null ? image : { type: "image", data: resized.data, mimeType: resized.mimeType };
+	if (excludeWebP === true && output.mimeType === "image/webp") {
+		const converted = await convertToPng(output.data, output.mimeType);
+		if (converted === null)
+			throw new TypeError(`Unable to convert ${output.mimeType} display output for the active model`);
+		output = { type: "image", data: converted.data, mimeType: converted.mimeType };
+	}
+	const dimensionNote = resized === null ? undefined : formatDimensionNote(resized);
+	return { image: output, ...(dimensionNote === undefined ? {} : { dimensionNote }) };
+};
+
+function formatDisplayJson(value: unknown): string {
+	let text: string;
+	try {
+		text = JSON.stringify(value, null, 2) ?? String(value);
+	} catch (error) {
+		if (!(error instanceof TypeError)) throw error;
+		text = String(value);
+	}
+	if (text.length <= MAX_DISPLAY_TEXT_BYTES) return text;
+	return `${text.slice(0, MAX_DISPLAY_TEXT_BYTES)}\n[…${text.length - MAX_DISPLAY_TEXT_BYTES}ch elided…]`;
+}
+
+function truncationMetaFromSummary(summary: OutputSummary): TruncationMeta | undefined {
+	if (!summary.truncated) return undefined;
+	const artifact = summary.artifactId === undefined ? {} : { artifactId: summary.artifactId };
+	if (summary.elidedBytes !== undefined && summary.elidedBytes > 0) {
+		const elidedLines = summary.elidedLines ?? Math.max(0, summary.totalLines - summary.outputLines);
+		const keptLines = Math.max(0, summary.outputLines - 1);
+		const headLines = Math.ceil(keptLines / 2);
+		const tailLines = keptLines - headLines;
+		return {
+			direction: "middle",
+			truncatedBy: "middle",
+			totalLines: summary.totalLines,
+			totalBytes: summary.totalBytes,
+			outputLines: summary.outputLines,
+			outputBytes: summary.outputBytes,
+			...(headLines > 0 ? { headRange: { start: 1, end: headLines } } : {}),
+			...(tailLines > 0
+				? { tailRange: { start: summary.totalLines - tailLines + 1, end: summary.totalLines } }
+				: {}),
+			elidedBytes: summary.elidedBytes,
+			elidedLines,
+			...artifact,
+		};
+	}
+	return {
+		direction: "tail",
+		truncatedBy: summary.outputBytes < summary.totalBytes ? "bytes" : "lines",
+		totalLines: summary.totalLines,
+		totalBytes: summary.totalBytes,
+		outputLines: summary.outputLines,
+		outputBytes: summary.outputBytes,
+		shownRange: { start: Math.max(1, summary.totalLines - summary.outputLines + 1), end: summary.totalLines },
+		...artifact,
+	};
+}
+
+export function marshalToolResult(result: AgentToolResult<unknown>) {
+	const texts = result.content.filter((part) => part.type === "text").map((part) => part.text);
+	const images = result.content
+		.filter((part) => part.type === "image")
+		.map((part) => ({ mimeType: part.mimeType, dataBase64: part.data }));
+	const details =
+		typeof result.details === "object" &&
+		result.details !== null &&
+		!Array.isArray(result.details) &&
+		Object.keys(result.details).length === 0
+			? undefined
+			: result.details;
+	const hasError = toolResultIsError(result);
+	const text = texts.join("\n");
+	return images.length === 0 && details === undefined && !hasError ? { text } : { text, details, images, hasError };
+}
+
+export function toolResultIsError(result: AgentToolResult<unknown>): boolean {
+	const details = result.details;
+	return typeof details === "object" && details !== null && "isError" in details && details.isError === true;
+}