@elyracode/web-ui 0.9.9 → 0.9.11

package/src/components/sandbox/ArtifactsRuntimeProvider.ts

@@ -3,13 +3,14 @@ import {
 	ARTIFACTS_RUNTIME_PROVIDER_DESCRIPTION_RO,
 	ARTIFACTS_RUNTIME_PROVIDER_DESCRIPTION_RW,
 } from "../../prompts/prompts.js";
+import type { RuntimeMessage, RuntimeResponse, SandboxRuntimeWindow } from "./runtime-messages.js";
 import type { SandboxRuntimeProvider } from "./SandboxRuntimeProvider.js";
 
 // Define minimal interface for ArtifactsPanel to avoid circular dependencies
 interface ArtifactsPanelLike {
 	artifacts: Map<string, { content: string }>;
 	tool: {
-		execute(toolCallId: string, args: { command: string; filename: string; content?: string }): Promise<any>;
+		execute(toolCallId: string, args: { command: string; filename: string; content?: string }): Promise<unknown>;
 	};
 }
 
@@ -41,7 +42,7 @@ export class ArtifactsRuntimeProvider implements SandboxRuntimeProvider {
 		}
 	}
 
-	getData(): Record<string, any> {
+	getData(): Record<string, unknown> {
 		// Inject artifact snapshot for offline mode
 		const snapshot: Record<string, string> = {};
 		this.artifactsPanel.artifacts.forEach((artifact, filename) => {
@@ -53,44 +54,45 @@ export class ArtifactsRuntimeProvider implements SandboxRuntimeProvider {
 	getRuntime(): (sandboxId: string) => void {
 		// This function will be stringified, so no external references!
 		return (_sandboxId: string) => {
+			const win = window as unknown as SandboxRuntimeWindow;
 			// Auto-parse/stringify for .json files
 			const isJsonFile = (filename: string) => filename.endsWith(".json");
 
-			(window as any).listArtifacts = async (): Promise<string[]> => {
+			win.listArtifacts = async (): Promise<string[]> => {
 				// Online: ask extension
-				if ((window as any).sendRuntimeMessage) {
-					const response = await (window as any).sendRuntimeMessage({
+				if (win.sendRuntimeMessage) {
+					const response = await win.sendRuntimeMessage({
 						type: "artifact-operation",
 						action: "list",
 					});
 					if (!response.success) throw new Error(response.error);
-					return response.result;
+					return response.result as string[];
 				}
 				// Offline: return snapshot keys
 				else {
-					return Object.keys((window as any).artifacts || {});
+					return Object.keys(win.artifacts || {});
 				}
 			};
 
-			(window as any).getArtifact = async (filename: string): Promise<any> => {
+			win.getArtifact = async (filename: string): Promise<unknown> => {
 				let content: string;
 
 				// Online: ask extension
-				if ((window as any).sendRuntimeMessage) {
-					const response = await (window as any).sendRuntimeMessage({
+				if (win.sendRuntimeMessage) {
+					const response = await win.sendRuntimeMessage({
 						type: "artifact-operation",
 						action: "get",
 						filename,
 					});
 					if (!response.success) throw new Error(response.error);
-					content = response.result;
+					content = response.result as string;
 				}
 				// Offline: read snapshot
 				else {
-					if (!(window as any).artifacts?.[filename]) {
+					if (!win.artifacts?.[filename]) {
 						throw new Error(`Artifact not found (offline mode): ${filename}`);
 					}
-					content = (window as any).artifacts[filename];
+					content = win.artifacts[filename];
 				}
 
 				// Auto-parse .json files
@@ -104,12 +106,8 @@ export class ArtifactsRuntimeProvider implements SandboxRuntimeProvider {
 				return content;
 			};
 
-			(window as any).createOrUpdateArtifact = async (
-				filename: string,
-				content: any,
-				mimeType?: string,
-			): Promise<void> => {
-				if (!(window as any).sendRuntimeMessage) {
+			win.createOrUpdateArtifact = async (filename: string, content: unknown, mimeType?: string): Promise<void> => {
+				if (!win.sendRuntimeMessage) {
 					throw new Error("Cannot create/update artifacts in offline mode (read-only)");
 				}
 
@@ -121,7 +119,7 @@ export class ArtifactsRuntimeProvider implements SandboxRuntimeProvider {
 					finalContent = JSON.stringify(content, null, 2);
 				}
 
-				const response = await (window as any).sendRuntimeMessage({
+				const response = await win.sendRuntimeMessage({
 					type: "artifact-operation",
 					action: "createOrUpdate",
 					filename,
@@ -131,12 +129,12 @@ export class ArtifactsRuntimeProvider implements SandboxRuntimeProvider {
 				if (!response.success) throw new Error(response.error);
 			};
 
-			(window as any).deleteArtifact = async (filename: string): Promise<void> => {
-				if (!(window as any).sendRuntimeMessage) {
+			win.deleteArtifact = async (filename: string): Promise<void> => {
+				if (!win.sendRuntimeMessage) {
 					throw new Error("Cannot delete artifacts in offline mode (read-only)");
 				}
 
-				const response = await (window as any).sendRuntimeMessage({
+				const response = await win.sendRuntimeMessage({
 					type: "artifact-operation",
 					action: "delete",
 					filename,
@@ -146,15 +144,13 @@ export class ArtifactsRuntimeProvider implements SandboxRuntimeProvider {
 		};
 	}
 
-	async handleMessage(message: any, respond: (response: any) => void): Promise<void> {
+	async handleMessage(message: RuntimeMessage, respond: (response: RuntimeResponse) => void): Promise<void> {
 		if (message.type !== "artifact-operation") {
 			return;
 		}
 
-		const { action, filename, content } = message;
-
 		try {
-			switch (action) {
+			switch (message.action) {
 				case "list": {
 					const filenames = Array.from(this.artifactsPanel.artifacts.keys());
 					respond({ success: true, result: filenames });
@@ -162,9 +158,9 @@ export class ArtifactsRuntimeProvider implements SandboxRuntimeProvider {
 				}
 
 				case "get": {
-					const artifact = this.artifactsPanel.artifacts.get(filename);
+					const artifact = this.artifactsPanel.artifacts.get(message.filename);
 					if (!artifact) {
-						respond({ success: false, error: `Artifact not found: ${filename}` });
+						respond({ success: false, error: `Artifact not found: ${message.filename}` });
 					} else {
 						respond({ success: true, result: artifact.content });
 					}
@@ -173,26 +169,26 @@ export class ArtifactsRuntimeProvider implements SandboxRuntimeProvider {
 
 				case "createOrUpdate": {
 					try {
-						const exists = this.artifactsPanel.artifacts.has(filename);
+						const exists = this.artifactsPanel.artifacts.has(message.filename);
 						const command = exists ? "rewrite" : "create";
 						const action = exists ? "update" : "create";
 
 						await this.artifactsPanel.tool.execute("", {
 							command,
-							filename,
-							content,
+							filename: message.filename,
+							content: message.content,
 						});
 						this.pushAgentMessage({
 							role: "artifact",
 							action,
-							filename,
-							content,
-							...(action === "create" && { title: filename }),
+							filename: message.filename,
+							content: message.content,
+							...(action === "create" && { title: message.filename }),
 							timestamp: new Date().toISOString(),
 						});
 						respond({ success: true });
-					} catch (err: any) {
-						respond({ success: false, error: err.message });
+					} catch (err) {
+						respond({ success: false, error: err instanceof Error ? err.message : String(err) });
 					}
 					break;
 				}
@@ -201,26 +197,26 @@ export class ArtifactsRuntimeProvider implements SandboxRuntimeProvider {
 					try {
 						await this.artifactsPanel.tool.execute("", {
 							command: "delete",
-							filename,
+							filename: message.filename,
 						});
 						this.pushAgentMessage({
 							role: "artifact",
 							action: "delete",
-							filename,
+							filename: message.filename,
 							timestamp: new Date().toISOString(),
 						});
 						respond({ success: true });
-					} catch (err: any) {
-						respond({ success: false, error: err.message });
+					} catch (err) {
+						respond({ success: false, error: err instanceof Error ? err.message : String(err) });
 					}
 					break;
 				}
 
 				default:
-					respond({ success: false, error: `Unknown artifact action: ${action}` });
+					respond({ success: false, error: "Unknown artifact action" });
 			}
-		} catch (error: any) {
-			respond({ success: false, error: error.message });
+		} catch (error) {
+			respond({ success: false, error: error instanceof Error ? error.message : String(error) });
 		}
 	}
 

package/src/components/sandbox/AttachmentsRuntimeProvider.ts

@@ -1,5 +1,6 @@
 import { ATTACHMENTS_RUNTIME_DESCRIPTION } from "../../prompts/prompts.js";
 import type { Attachment } from "../../utils/attachment-utils.js";
+import type { SandboxAttachment, SandboxRuntimeWindow } from "./runtime-messages.js";
 import type { SandboxRuntimeProvider } from "./SandboxRuntimeProvider.js";
 
 /**
@@ -12,7 +13,7 @@ import type { SandboxRuntimeProvider } from "./SandboxRuntimeProvider.js";
 export class AttachmentsRuntimeProvider implements SandboxRuntimeProvider {
 	constructor(private attachments: Attachment[]) {}
 
-	getData(): Record<string, any> {
+	getData(): Record<string, unknown> {
 		const attachmentsData = this.attachments.map((a) => ({
 			id: a.id,
 			fileName: a.fileName,
@@ -30,16 +31,17 @@ export class AttachmentsRuntimeProvider implements SandboxRuntimeProvider {
 		// These functions read directly from window.attachments
 		// Works both online AND offline (no messaging needed!)
 		return (_sandboxId: string) => {
-			(window as any).listAttachments = () =>
-				((window as any).attachments || []).map((a: any) => ({
+			const win = window as unknown as SandboxRuntimeWindow;
+			win.listAttachments = () =>
+				(win.attachments || []).map((a: SandboxAttachment) => ({
 					id: a.id,
 					fileName: a.fileName,
 					mimeType: a.mimeType,
 					size: a.size,
 				}));
 
-			(window as any).readTextAttachment = (attachmentId: string) => {
-				const a = ((window as any).attachments || []).find((x: any) => x.id === attachmentId);
+			win.readTextAttachment = (attachmentId: string) => {
+				const a = (win.attachments || []).find((x: SandboxAttachment) => x.id === attachmentId);
 				if (!a) throw new Error(`Attachment not found: ${attachmentId}`);
 				if (a.extractedText) return a.extractedText;
 				try {
@@ -49,8 +51,8 @@ export class AttachmentsRuntimeProvider implements SandboxRuntimeProvider {
 				}
 			};
 
-			(window as any).readBinaryAttachment = (attachmentId: string) => {
-				const a = ((window as any).attachments || []).find((x: any) => x.id === attachmentId);
+			win.readBinaryAttachment = (attachmentId: string) => {
+				const a = (win.attachments || []).find((x: SandboxAttachment) => x.id === attachmentId);
 				if (!a) throw new Error(`Attachment not found: ${attachmentId}`);
 				const bin = atob(a.content);
 				const bytes = new Uint8Array(bin.length);

package/src/components/sandbox/ConsoleRuntimeProvider.ts

@@ -1,3 +1,4 @@
+import type { RuntimeMessage, RuntimeResponse, SandboxRuntimeWindow } from "./runtime-messages.js";
 import type { SandboxRuntimeProvider } from "./SandboxRuntimeProvider.js";
 
 export interface ConsoleLog {
@@ -18,7 +19,7 @@ export class ConsoleRuntimeProvider implements SandboxRuntimeProvider {
 	private completionError: { message: string; stack: string } | null = null;
 	private completed = false;
 
-	getData(): Record<string, any> {
+	getData(): Record<string, unknown> {
 		// No data needed
 		return {};
 	}
@@ -29,10 +30,11 @@ export class ConsoleRuntimeProvider implements SandboxRuntimeProvider {
 
 	getRuntime(): (sandboxId: string) => void {
 		return (_sandboxId: string) => {
+			const win = window as unknown as SandboxRuntimeWindow;
 			// Store truly original console methods on first wrap only
 			// This prevents accumulation of wrapper functions across multiple executions
-			if (!(window as any).__originalConsole) {
-				(window as any).__originalConsole = {
+			if (!win.__originalConsole) {
+				win.__originalConsole = {
 					log: console.log.bind(console),
 					error: console.error.bind(console),
 					warn: console.warn.bind(console),
@@ -41,13 +43,13 @@ export class ConsoleRuntimeProvider implements SandboxRuntimeProvider {
 			}
 
 			// Always use the truly original console, not the current (possibly wrapped) one
-			const originalConsole = (window as any).__originalConsole;
+			const originalConsole = win.__originalConsole;
 
 			// Track pending send promises to wait for them in onCompleted
-			const pendingSends: Promise<any>[] = [];
+			const pendingSends: Promise<unknown>[] = [];
 
-			["log", "error", "warn", "info"].forEach((method) => {
-				(console as any)[method] = (...args: any[]) => {
+			(["log", "error", "warn", "info"] as const).forEach((method) => {
+				console[method] = (...args: unknown[]) => {
 					const text = args
 						.map((arg) => {
 							try {
@@ -59,11 +61,11 @@ export class ConsoleRuntimeProvider implements SandboxRuntimeProvider {
 						.join(" ");
 
 					// Always log locally too (using truly original console)
-					(originalConsole as any)[method].apply(console, args);
+					originalConsole[method].apply(console, args);
 
 					// Send immediately and track the promise (only in extension context)
-					if ((window as any).sendRuntimeMessage) {
-						const sendPromise = (window as any)
+					if (win.sendRuntimeMessage) {
+						const sendPromise = win
 							.sendRuntimeMessage({
 								type: "console",
 								method,
@@ -77,8 +79,8 @@ export class ConsoleRuntimeProvider implements SandboxRuntimeProvider {
 			});
 
 			// Register completion callback to wait for all pending sends
-			if ((window as any).onCompleted) {
-				(window as any).onCompleted(async (_success: boolean) => {
+			if (win.onCompleted) {
+				win.onCompleted(async (_success: boolean) => {
 					// Wait for all pending console sends to complete
 					if (pendingSends.length > 0) {
 						await Promise.all(pendingSends);
@@ -111,20 +113,20 @@ export class ConsoleRuntimeProvider implements SandboxRuntimeProvider {
 
 			// Expose complete() method for user code to call
 			let completionSent = false;
-			(window as any).complete = async (error?: { message: string; stack: string }, returnValue?: any) => {
+			win.complete = async (error?: { message: string; stack: string } | null, returnValue?: unknown) => {
 				if (completionSent) return;
 				completionSent = true;
 
 				const finalError = error || lastError;
 
-				if ((window as any).sendRuntimeMessage) {
+				if (win.sendRuntimeMessage) {
 					if (finalError) {
-						await (window as any).sendRuntimeMessage({
+						await win.sendRuntimeMessage({
 							type: "execution-error",
 							error: finalError,
 						});
 					} else {
-						await (window as any).sendRuntimeMessage({
+						await win.sendRuntimeMessage({
 							type: "execution-complete",
 							returnValue,
 						});
@@ -134,7 +136,7 @@ export class ConsoleRuntimeProvider implements SandboxRuntimeProvider {
 		};
 	}
 
-	async handleMessage(message: any, respond: (response: any) => void): Promise<void> {
+	async handleMessage(message: RuntimeMessage, respond: (response: RuntimeResponse) => void): Promise<void> {
 		if (message.type === "console") {
 			// Collect console output
 			this.logs.push({

package/src/components/sandbox/FileDownloadRuntimeProvider.ts

@@ -1,3 +1,4 @@
+import type { RuntimeMessage, RuntimeResponse, SandboxRuntimeWindow } from "./runtime-messages.js";
 import type { SandboxRuntimeProvider } from "./SandboxRuntimeProvider.js";
 
 export interface DownloadableFile {
@@ -17,15 +18,16 @@ export interface DownloadableFile {
 export class FileDownloadRuntimeProvider implements SandboxRuntimeProvider {
 	private files: DownloadableFile[] = [];
 
-	getData(): Record<string, any> {
+	getData(): Record<string, unknown> {
 		// No data needed
 		return {};
 	}
 
 	getRuntime(): (sandboxId: string) => void {
 		return (_sandboxId: string) => {
-			(window as any).returnDownloadableFile = async (fileName: string, content: any, mimeType?: string) => {
-				let finalContent: any, finalMimeType: string;
+			const win = window as unknown as SandboxRuntimeWindow;
+			win.returnDownloadableFile = async (fileName: string, content: unknown, mimeType?: string) => {
+				let finalContent: string | Uint8Array, finalMimeType: string;
 
 				if (content instanceof Blob) {
 					const arrayBuffer = await content.arrayBuffer();
@@ -53,8 +55,8 @@ export class FileDownloadRuntimeProvider implements SandboxRuntimeProvider {
 				}
 
 				// Send to extension if in extension context (online mode)
-				if ((window as any).sendRuntimeMessage) {
-					const response = await (window as any).sendRuntimeMessage({
+				if (win.sendRuntimeMessage) {
+					const response = await win.sendRuntimeMessage({
 						type: "file-returned",
 						fileName,
 						content: finalContent,
@@ -63,7 +65,9 @@ export class FileDownloadRuntimeProvider implements SandboxRuntimeProvider {
 					if (response.error) throw new Error(response.error);
 				} else {
 					// Offline mode: trigger browser download directly
-					const blob = new Blob([finalContent instanceof Uint8Array ? finalContent : finalContent], {
+					const blobPart: BlobPart =
+						typeof finalContent === "string" ? finalContent : new Uint8Array(finalContent);
+					const blob = new Blob([blobPart], {
 						type: finalMimeType,
 					});
 					const url = URL.createObjectURL(blob);
@@ -77,7 +81,7 @@ export class FileDownloadRuntimeProvider implements SandboxRuntimeProvider {
 		};
 	}
 
-	async handleMessage(message: any, respond: (response: any) => void): Promise<void> {
+	async handleMessage(message: RuntimeMessage, respond: (response: RuntimeResponse) => void): Promise<void> {
 		if (message.type === "file-returned") {
 			// Collect file for caller
 			this.files.push({

package/src/components/sandbox/RuntimeMessageRouter.ts

@@ -1,7 +1,8 @@
+import type { ChromeApi, RuntimeMessage, RuntimeResponse, UserScriptMessageListener } from "./runtime-messages.js";
 import type { SandboxRuntimeProvider } from "./SandboxRuntimeProvider.js";
 
 // Type declaration for chrome extension API (when available)
-declare const chrome: any;
+declare const chrome: ChromeApi | undefined;
 
 /**
  * Message consumer interface - components that want to receive messages from sandboxes
@@ -11,7 +12,7 @@ export interface MessageConsumer {
 	 * Handle a message from a sandbox.
 	 * All consumers receive all messages - decide internally what to handle.
 	 */
-	handleMessage(message: any): Promise<void>;
+	handleMessage(message: RuntimeMessage): Promise<void>;
 }
 
 /**
@@ -41,9 +42,7 @@ interface SandboxContext {
 export class RuntimeMessageRouter {
 	private sandboxes = new Map<string, SandboxContext>();
 	private messageListener: ((e: MessageEvent) => void) | null = null;
-	private userScriptMessageListener:
-		| ((message: any, sender: any, sendResponse: (response: any) => void) => boolean)
-		| null = null;
+	private userScriptMessageListener: UserScriptMessageListener | null = null;
 
 	/**
 	 * Register a new sandbox with its runtime providers.
@@ -133,7 +132,7 @@ export class RuntimeMessageRouter {
 				}
 
 				// Create respond() function for bidirectional communication
-				const respond = (response: any) => {
+				const respond = (response: RuntimeResponse) => {
 					context.iframe?.contentWindow?.postMessage(
 						{
 							type: "runtime-response",
@@ -170,14 +169,14 @@ export class RuntimeMessageRouter {
 				return;
 			}
 
-			this.userScriptMessageListener = (message: any, _sender: any, sendResponse: (response: any) => void) => {
+			this.userScriptMessageListener = (message, _sender, sendResponse) => {
 				const { sandboxId } = message;
 				if (!sandboxId) return false;
 
 				const context = this.sandboxes.get(sandboxId);
 				if (!context) return false;
 
-				const respond = (response: any) => {
+				const respond = (response: RuntimeResponse) => {
 					sendResponse({
 						...response,
 						sandboxId,

package/src/components/sandbox/SandboxRuntimeProvider.ts

@@ -1,3 +1,5 @@
+import type { RuntimeMessage, RuntimeResponse } from "./runtime-messages.js";
+
 /**
  * Interface for providing runtime capabilities to sandboxed iframes.
  * Each provider injects data and runtime functions into the sandbox context.
@@ -7,7 +9,7 @@ export interface SandboxRuntimeProvider {
 	 * Returns data to inject into window scope.
 	 * Keys become window properties (e.g., { attachments: [...] } -> window.attachments)
 	 */
-	getData(): Record<string, any>;
+	getData(): Record<string, unknown>;
 
 	/**
 	 * Returns a runtime function that will be stringified and executed in the sandbox.
@@ -25,7 +27,7 @@ export interface SandboxRuntimeProvider {
 	 * @param message - The message from the sandbox
 	 * @param respond - Function to send a response back to the sandbox
 	 */
-	handleMessage?(message: any, respond: (response: any) => void): Promise<void>;
+	handleMessage?(message: RuntimeMessage, respond: (response: RuntimeResponse) => void): Promise<void>;
 
 	/**
 	 * Optional documentation describing what globals/functions this provider injects.

package/src/components/sandbox/runtime-messages.ts

@@ -0,0 +1,146 @@
+/**
+ * Shared types for the sandbox runtime messaging protocol.
+ *
+ * These describe the message envelopes exchanged between the host page
+ * (SandboxedIframe / RuntimeMessageRouter / *RuntimeProvider classes) and the
+ * sandboxed execution context (iframe or user script).
+ */
+
+/** Fields attached to every message routed through the runtime bridge. */
+export interface RuntimeMessageEnvelope {
+	sandboxId?: string;
+	messageId?: string;
+}
+
+/** Artifact CRUD request issued from sandboxed code. */
+export type ArtifactOperationMessage =
+	| { type: "artifact-operation"; action: "list" }
+	| { type: "artifact-operation"; action: "get"; filename: string }
+	| { type: "artifact-operation"; action: "delete"; filename: string }
+	| {
+			type: "artifact-operation";
+			action: "createOrUpdate";
+			filename: string;
+			content: string;
+			mimeType?: string;
+	  };
+
+/** Captured console output forwarded from sandboxed code. */
+export interface ConsoleRuntimeMessage {
+	type: "console";
+	method: string;
+	text: string;
+	args?: unknown[];
+}
+
+/** A one-time downloadable file returned from sandboxed code. */
+export interface FileReturnedMessage {
+	type: "file-returned";
+	fileName: string;
+	content: string | Uint8Array;
+	mimeType: string;
+}
+
+/** Successful execution lifecycle completion. */
+export interface ExecutionCompleteMessage {
+	type: "execution-complete";
+	returnValue?: unknown;
+}
+
+/** Failed execution lifecycle completion. */
+export interface ExecutionErrorMessage {
+	type: "execution-error";
+	error: { message: string; stack: string };
+}
+
+/** Discriminated union of all messages a provider/consumer can receive. */
+export type RuntimeMessage = RuntimeMessageEnvelope &
+	(
+		| ArtifactOperationMessage
+		| ConsoleRuntimeMessage
+		| FileReturnedMessage
+		| ExecutionCompleteMessage
+		| ExecutionErrorMessage
+	);
+
+/** Response sent back to sandboxed code via the bridge. */
+export interface RuntimeResponse {
+	success?: boolean;
+	error?: string;
+	result?: unknown;
+}
+
+/**
+ * Shape of the resolved value of `window.sendRuntimeMessage` inside the sandbox.
+ * Mirrors the `runtime-response` payload posted back by the router.
+ */
+export interface SendRuntimeMessageResponse extends RuntimeResponse, RuntimeMessageEnvelope {
+	type?: string;
+}
+
+/** A single attachment record injected into the sandbox via `window.attachments`. */
+export interface SandboxAttachment {
+	id: string;
+	fileName: string;
+	mimeType: string;
+	size: number;
+	content: string;
+	extractedText?: string;
+}
+
+/**
+ * Window surface exposed inside the sandbox by the injected runtime functions.
+ *
+ * The runtime functions are stringified and injected, so this interface only
+ * exists to type-check the function bodies at build time; the assertions are
+ * erased from the emitted JavaScript.
+ */
+export interface SandboxRuntimeWindow extends Window {
+	sandboxId?: string;
+	sendRuntimeMessage?: (message: Record<string, unknown>) => Promise<SendRuntimeMessageResponse>;
+	onCompleted?: (callback: (success: boolean) => void | Promise<void>) => void;
+	complete?: (error?: { message: string; stack: string } | null, returnValue?: unknown) => Promise<void>;
+	__completionCallbacks?: Array<(success: boolean) => void | Promise<void>>;
+	__originalConsole?: Record<"log" | "error" | "warn" | "info", (...args: unknown[]) => void>;
+	artifacts?: Record<string, string>;
+	attachments?: SandboxAttachment[];
+	listArtifacts?: () => Promise<string[]>;
+	getArtifact?: (filename: string) => Promise<unknown>;
+	createOrUpdateArtifact?: (filename: string, content: unknown, mimeType?: string) => Promise<void>;
+	deleteArtifact?: (filename: string) => Promise<void>;
+	listAttachments?: () => Array<{ id: string; fileName: string; mimeType: string; size: number }>;
+	readTextAttachment?: (attachmentId: string) => string;
+	readBinaryAttachment?: (attachmentId: string) => Uint8Array;
+	returnDownloadableFile?: (fileName: string, content: unknown, mimeType?: string) => Promise<void>;
+}
+
+/** Listener registered with `chrome.runtime.onUserScriptMessage`. */
+export type UserScriptMessageListener = (
+	message: RuntimeMessage,
+	sender: unknown,
+	sendResponse: (response: RuntimeResponse & RuntimeMessageEnvelope) => void,
+) => boolean;
+
+/** Minimal subset of the `chrome.runtime.onUserScriptMessage` event API. */
+export interface ChromeUserScriptMessageEvent {
+	addListener(listener: UserScriptMessageListener): void;
+	removeListener(listener: UserScriptMessageListener): void;
+}
+
+/** Minimal subset of `chrome.runtime` used by the runtime router/bridge. */
+export interface ChromeRuntime {
+	onUserScriptMessage?: ChromeUserScriptMessageEvent;
+	sendMessage?(message: unknown): Promise<unknown>;
+	getURL?(path: string): string;
+}
+
+/** Minimal subset of `chrome.tabs` used to open external URLs. */
+export interface ChromeTabs {
+	create(createProperties: { url: string }): void;
+}
+
+/** Minimal subset of the chrome extension API surface used by the sandbox. */
+export interface ChromeApi {
+	runtime?: ChromeRuntime;
+	tabs?: ChromeTabs;
+}