just-bash-mcp 2.9.0 → 2.9.1

package/README.md

@@ -7,11 +7,11 @@ An MCP (Model Context Protocol) server that provides a sandboxed bash environmen
 
 Execute bash commands in a secure, isolated environment with an in-memory virtual filesystem.
 
-Built on top of [`just-bash`](https://github.com/vercel-labs/just-bash) v2.9.6.
+Built on top of [`just-bash`](https://github.com/vercel-labs/just-bash) v2.10.2.
 
-## What's New in v2.8.0
+## What's New in v2.9.0
 
-- **Synced with upstream `just-bash` v2.9.6** - Latest security hardening, defense-in-depth, fuzzing, jq fixes, and large file support
+- **Synced with upstream `just-bash` v2.10.2** - Latest upstream commands, APIs, and type exports
 - **Defense-in-depth mode** - Opt-in monkey-patching of dangerous JS globals (`JUST_BASH_DEFENSE_IN_DEPTH=true`)
 - **Python support** - Python3 via Pyodide (`JUST_BASH_ENABLE_PYTHON=true`)
 - **Vercel Sandbox API** - Compatible `bash_sandbox_*` tools for isolated execution
@@ -275,7 +275,7 @@ Compatible with the Vercel Sandbox API:
 
 ## Upstream API Coverage
 
-This wrapper integrates the full public API surface of `just-bash` v2.9.6:
+This wrapper integrates the full public API surface of `just-bash` v2.10.2:
 
 | Category | Exports Used |
 |----------|-------------|

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "just-bash-mcp",
-	"version": "2.9.0",
+	"version": "2.9.1",
 	"description": "MCP server providing a sandboxed bash environment using just-bash",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -61,13 +61,13 @@
 	"packageManager": "bun@1.3.8",
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.26.0",
-		"just-bash": "^2.9.6",
+		"just-bash": "^2.10.2",
 		"zod": "^4.3.6"
 	},
 	"devDependencies": {
-		"@types/node": "^25.2.2",
+		"@types/node": "^25.2.3",
 		"oxfmt": "^0.28.0",
-		"oxlint": "^1.43.0",
+		"oxlint": "^1.48.0",
 		"oxlint-tsgolint": "^0.11.5"
 	}
 }

package/src/config/index.ts

@@ -3,6 +3,9 @@
  * Handles environment variable parsing and configuration building
  */
 
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import {
 	type BashLogger,
 	type BashOptions,
@@ -10,8 +13,6 @@ import {
 	type DefenseInDepthConfig,
 	type MountConfig,
 	type NetworkConfig,
-	type TraceCallback,
-	type TraceEvent,
 	OverlayFs,
 	ReadWriteFs,
 	SecurityViolationLogger,
@@ -19,7 +20,16 @@ import {
 } from "just-bash";
 
 // Re-export upstream types used by other modules
-export type { DefenseInDepthConfig, TraceCallback, TraceEvent };
+export type { DefenseInDepthConfig };
+
+export interface TraceEvent {
+	category: string;
+	name: string;
+	durationMs: number;
+	details?: Record<string, unknown>;
+}
+
+export type TraceCallback = (event: TraceEvent) => void;
 
 // ============================================================================
 // Types
@@ -92,6 +102,22 @@ export interface Config {
 	readonly ALLOWED_COMMANDS: CommandName[] | undefined;
 }
 
+function readPackageVersion(relativePath: string): string {
+	try {
+		const __dirname = dirname(fileURLToPath(import.meta.url));
+		const packagePath = join(__dirname, relativePath);
+		const packageJson = JSON.parse(readFileSync(packagePath, "utf-8")) as { version?: string };
+		return packageJson.version || "unknown";
+	} catch {
+		return "unknown";
+	}
+}
+
+export const WRAPPER_VERSION = readPackageVersion("../../package.json");
+export const UPSTREAM_JUST_BASH_VERSION = readPackageVersion(
+	"../../node_modules/just-bash/package.json",
+);
+
 function getAllowedMethods(): HttpMethod[] {
 	const methods = parseEnvStringArray("JUST_BASH_ALLOWED_METHODS");
 	return methods.length > 0 ? (methods as HttpMethod[]) : ["GET", "HEAD"];
@@ -111,7 +137,7 @@ function parseEnvOptionalInt(key: string): number | undefined {
 
 export const config: Config = {
 	// Server info
-	VERSION: "2.8.0",
+	VERSION: WRAPPER_VERSION,
 	SERVER_NAME: "just-bash-mcp",
 
 	// Filesystem configuration
@@ -187,7 +213,7 @@ export const bashLogger: BashLogger | undefined = config.ENABLE_LOGGING
 		}
 	: undefined;
 
-export const traceCallback: TraceCallback | undefined = config.ENABLE_TRACING
+export const traceCallback: BashOptions["trace"] = config.ENABLE_TRACING
 	? (event: TraceEvent) => {
 			if (event.details) {
 				console.error(
@@ -226,7 +252,7 @@ export function buildDefenseInDepthConfig(): DefenseInDepthConfig | false {
 	return {
 		enabled: true,
 		auditMode: config.DEFENSE_IN_DEPTH_AUDIT,
-		onViolation: (violation) => {
+		onViolation: (violation: { type: string; target: string; details: string }) => {
 			violationLogger.record(violation);
 			consoleCallback?.(violation);
 		},

package/src/tools/info-tools.ts

@@ -6,9 +6,6 @@
  * SecurityViolationLogger for defense-in-depth violation reporting.
  */
 
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import {
 	type AllCommandName,
@@ -24,27 +21,12 @@ import {
 	ENVIRONMENT_VARIABLES,
 	FEATURES,
 	parseMountsConfig,
+	UPSTREAM_JUST_BASH_VERSION,
 	violationLogger,
 } from "../config/index.ts";
 import { createErrorResponse, createJsonResponse } from "../utils/index.ts";
 import { getDefenseInDepthBox, getPersistentBash } from "./bash-instance.ts";
 
-function getUpstreamVersion(): string {
-	try {
-		// Resolve the just-bash package directory relative to this module
-		const __dirname = dirname(fileURLToPath(import.meta.url));
-		const pkgPath = join(__dirname, "..", "..", "node_modules", "just-bash", "package.json");
-		const pkg: { version: string } = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
-			version: string;
-		};
-		return pkg.version;
-	} catch {
-		return "unknown";
-	}
-}
-
-const UPSTREAM_VERSION = getUpstreamVersion();
-
 /**
  * Register information tools with the MCP server
  */
@@ -98,7 +80,7 @@ export function registerInfoTools(server: McpServer): void {
 
 			const info = {
 				version: config.VERSION,
-				upstreamVersion: UPSTREAM_VERSION,
+				upstreamVersion: UPSTREAM_JUST_BASH_VERSION,
 				fsMode,
 				fsRoot: config.READ_WRITE_ROOT || config.OVERLAY_ROOT || null,
 				overlayReadOnly: config.OVERLAY_ROOT ? config.OVERLAY_READ_ONLY : null,

package/src/types.ts

@@ -1,111 +1,7 @@
 /**
- * Re-export all upstream just-bash types for downstream consumers.
+ * Exact passthrough of the upstream just-bash public API.
  *
- * This barrel module provides a single import point for all types from
- * the just-bash package, so consumers of just-bash-mcp don't need to
- * depend on just-bash directly.
- *
- * Covers the full upstream API surface:
- * - Core: Bash, BashOptions, ExecOptions, BashExecResult, ExecResult
- * - Commands: CommandName, AllCommandName, NetworkCommandName, PythonCommandName
- * - Custom commands: CustomCommand, LazyCommand, defineCommand, Command, CommandContext
- * - Filesystem: IFileSystem, InMemoryFs, OverlayFs, ReadWriteFs, MountableFs + all types
- * - Network: NetworkConfig, error classes
- * - Sandbox: Sandbox, SandboxCommand, SandboxOptions, OutputMessage, WriteFilesInput
- * - Security: DefenseInDepthBox, SecurityViolationLogger, SecurityViolationError + types
- * - Trace: TraceEvent, TraceCallback
+ * Keeping this as a wildcard export guarantees this wrapper stays 1:1 with
+ * whatever the installed just-bash version exposes.
  */
-
-// ============================================================================
-// Core
-// ============================================================================
-export type { BashLogger, BashOptions, ExecOptions, ExecutionLimits } from "just-bash";
-export { Bash } from "just-bash";
-
-// ============================================================================
-// Result types
-// ============================================================================
-export type { BashExecResult, Command, CommandContext, ExecResult, IFileSystem } from "just-bash";
-
-// ============================================================================
-// Trace types (from upstream, not locally redefined)
-// ============================================================================
-export type { TraceCallback, TraceEvent } from "just-bash";
-
-// ============================================================================
-// Command registry
-// ============================================================================
-export type { AllCommandName, CommandName, NetworkCommandName, PythonCommandName } from "just-bash";
-export { getCommandNames, getNetworkCommandNames, getPythonCommandNames } from "just-bash";
-
-// ============================================================================
-// Custom commands
-// ============================================================================
-export type { CustomCommand, LazyCommand } from "just-bash";
-export { defineCommand } from "just-bash";
-
-// ============================================================================
-// Filesystem types
-// ============================================================================
-export type {
-	BufferEncoding,
-	CpOptions,
-	DirectoryEntry,
-	FileContent,
-	FileEntry,
-	FileInit,
-	FileSystemFactory,
-	FsEntry,
-	FsStat,
-	InitialFiles,
-	MkdirOptions,
-	MountableFsOptions,
-	MountConfig,
-	OverlayFsOptions,
-	ReadWriteFsOptions,
-	RmOptions,
-	SymlinkEntry,
-} from "just-bash";
-
-// ============================================================================
-// Filesystem implementations
-// ============================================================================
-export { InMemoryFs, MountableFs, OverlayFs, ReadWriteFs } from "just-bash";
-
-// ============================================================================
-// Network
-// ============================================================================
-export type { NetworkConfig } from "just-bash";
-export {
-	NetworkAccessDeniedError,
-	RedirectNotAllowedError,
-	TooManyRedirectsError,
-} from "just-bash";
-
-// ============================================================================
-// Sandbox (Vercel Sandbox compatible API)
-// ============================================================================
-export type {
-	OutputMessage,
-	SandboxCommandFinished,
-	SandboxOptions,
-	WriteFilesInput,
-} from "just-bash";
-export { Sandbox, SandboxCommand } from "just-bash";
-
-// ============================================================================
-// Security / Defense-in-Depth
-// ============================================================================
-export type {
-	DefenseInDepthConfig,
-	DefenseInDepthHandle,
-	DefenseInDepthStats,
-	SecurityViolation,
-	SecurityViolationType,
-} from "just-bash";
-export {
-	createConsoleViolationCallback,
-	DefenseInDepthBox,
-	SecurityViolationError,
-	SecurityViolationLogger,
-} from "just-bash";
+export * from "just-bash";

package/src/just-bash-security.d.ts

@@ -1,705 +0,0 @@
-/**
- * Ambient type declarations for just-bash.
- *
- * The upstream just-bash v2.9.6 ships .d.ts files but its internal
- * re-exports use relative .js paths (e.g., "./Bash.js", "./fs/interface.js")
- * that don't resolve under moduleResolution: "nodenext" because the package
- * bundles everything into dist/bundle/index.js. TypeScript can't follow the
- * type chain from the barrel index.d.ts through to the leaf .d.ts files.
- *
- * This ambient module declaration provides complete types for all public
- * exports of just-bash v2.9.6, derived from the upstream .d.ts sources.
- * It should be updated when the upstream package is bumped.
- */
-
-declare module "just-bash" {
-	// ========================================================================
-	// Trace types (from types.d.ts)
-	// ========================================================================
-
-	interface TraceEvent {
-		category: string;
-		name: string;
-		durationMs: number;
-		details?: Record<string, unknown>;
-	}
-
-	type TraceCallback = (event: TraceEvent) => void;
-
-	// ========================================================================
-	// Core result types (from types.d.ts)
-	// ========================================================================
-
-	interface ExecResult {
-		stdout: string;
-		stderr: string;
-		exitCode: number;
-		env?: Record<string, string>;
-	}
-
-	interface BashExecResult extends ExecResult {
-		env: Record<string, string>;
-	}
-
-	interface FeatureCoverageWriter {
-		hit(feature: string): void;
-	}
-
-	// ========================================================================
-	// Filesystem types (from fs/interface.d.ts)
-	// ========================================================================
-
-	type BufferEncoding = "utf8" | "utf-8" | "ascii" | "binary" | "base64" | "hex" | "latin1";
-	type FileContent = string | Uint8Array;
-
-	interface ReadFileOptions {
-		encoding?: BufferEncoding | null;
-	}
-	interface WriteFileOptions {
-		encoding?: BufferEncoding;
-	}
-
-	interface FileEntry {
-		type: "file";
-		content: string | Uint8Array;
-		mode: number;
-		mtime: Date;
-	}
-	interface DirectoryEntry {
-		type: "directory";
-		mode: number;
-		mtime: Date;
-	}
-	interface SymlinkEntry {
-		type: "symlink";
-		target: string;
-		mode: number;
-		mtime: Date;
-	}
-	type FsEntry = FileEntry | DirectoryEntry | SymlinkEntry;
-
-	interface DirentEntry {
-		name: string;
-		isFile: boolean;
-		isDirectory: boolean;
-		isSymbolicLink: boolean;
-	}
-	interface FsStat {
-		isFile: boolean;
-		isDirectory: boolean;
-		isSymbolicLink: boolean;
-		mode: number;
-		size: number;
-		mtime: Date;
-	}
-	interface MkdirOptions {
-		recursive?: boolean;
-	}
-	interface RmOptions {
-		recursive?: boolean;
-		force?: boolean;
-	}
-	interface CpOptions {
-		recursive?: boolean;
-	}
-
-	interface IFileSystem {
-		readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
-		readFileBuffer(path: string): Promise<Uint8Array>;
-		writeFile(
-			path: string,
-			content: FileContent,
-			options?: WriteFileOptions | BufferEncoding,
-		): Promise<void>;
-		appendFile(
-			path: string,
-			content: FileContent,
-			options?: WriteFileOptions | BufferEncoding,
-		): Promise<void>;
-		exists(path: string): Promise<boolean>;
-		stat(path: string): Promise<FsStat>;
-		mkdir(path: string, options?: MkdirOptions): Promise<void>;
-		readdir(path: string): Promise<string[]>;
-		readdirWithFileTypes?(path: string): Promise<DirentEntry[]>;
-		rm(path: string, options?: RmOptions): Promise<void>;
-		cp(src: string, dest: string, options?: CpOptions): Promise<void>;
-		mv(src: string, dest: string): Promise<void>;
-		resolvePath(base: string, path: string): string;
-		getAllPaths(): string[];
-		chmod(path: string, mode: number): Promise<void>;
-		symlink(target: string, linkPath: string): Promise<void>;
-		link(existingPath: string, newPath: string): Promise<void>;
-		readlink(path: string): Promise<string>;
-		lstat(path: string): Promise<FsStat>;
-		realpath(path: string): Promise<string>;
-		utimes(path: string, atime: Date, mtime: Date): Promise<void>;
-	}
-
-	interface FileInit {
-		content: FileContent;
-		mode?: number;
-		mtime?: Date;
-	}
-	type InitialFiles = Record<string, FileContent | FileInit>;
-	type FileSystemFactory = (initialFiles?: InitialFiles) => IFileSystem;
-
-	// ========================================================================
-	// Execution limits (from limits.d.ts)
-	// ========================================================================
-
-	interface ExecutionLimits {
-		maxCallDepth?: number;
-		maxCommandCount?: number;
-		maxLoopIterations?: number;
-		maxAwkIterations?: number;
-		maxSedIterations?: number;
-		maxJqIterations?: number;
-		maxSqliteTimeoutMs?: number;
-		maxPythonTimeoutMs?: number;
-		maxGlobOperations?: number;
-		maxStringLength?: number;
-		maxArrayElements?: number;
-		maxHeredocSize?: number;
-		maxSubstitutionDepth?: number;
-	}
-
-	function resolveLimits(userLimits?: ExecutionLimits): Required<ExecutionLimits>;
-
-	// ========================================================================
-	// Command types (from types.d.ts)
-	// ========================================================================
-
-	interface CommandExecOptions {
-		env?: Record<string, string>;
-		cwd: string;
-	}
-
-	interface CommandContext {
-		fs: IFileSystem;
-		cwd: string;
-		env: Map<string, string>;
-		exportedEnv?: Record<string, string>;
-		stdin: string;
-		limits?: Required<ExecutionLimits>;
-		trace?: TraceCallback;
-		exec?: (command: string, options: CommandExecOptions) => Promise<ExecResult>;
-		fetch?: SecureFetch;
-		getRegisteredCommands?: () => string[];
-		sleep?: (ms: number) => Promise<void>;
-		fileDescriptors?: Map<number, string>;
-		xpgEcho?: boolean;
-		substitutionDepth?: number;
-		coverage?: FeatureCoverageWriter;
-	}
-
-	interface Command {
-		name: string;
-		execute(args: string[], ctx: CommandContext): Promise<ExecResult>;
-	}
-
-	type CommandRegistry = Map<string, Command>;
-
-	// ========================================================================
-	// Command registry (from commands/registry.d.ts)
-	// ========================================================================
-
-	type CommandName =
-		| "echo"
-		| "cat"
-		| "printf"
-		| "ls"
-		| "mkdir"
-		| "rmdir"
-		| "touch"
-		| "rm"
-		| "cp"
-		| "mv"
-		| "ln"
-		| "chmod"
-		| "pwd"
-		| "readlink"
-		| "head"
-		| "tail"
-		| "wc"
-		| "stat"
-		| "grep"
-		| "fgrep"
-		| "egrep"
-		| "rg"
-		| "sed"
-		| "awk"
-		| "sort"
-		| "uniq"
-		| "comm"
-		| "cut"
-		| "paste"
-		| "tr"
-		| "rev"
-		| "nl"
-		| "fold"
-		| "expand"
-		| "unexpand"
-		| "strings"
-		| "split"
-		| "column"
-		| "join"
-		| "tee"
-		| "find"
-		| "basename"
-		| "dirname"
-		| "tree"
-		| "du"
-		| "env"
-		| "printenv"
-		| "alias"
-		| "unalias"
-		| "history"
-		| "xargs"
-		| "true"
-		| "false"
-		| "clear"
-		| "bash"
-		| "sh"
-		| "jq"
-		| "base64"
-		| "diff"
-		| "date"
-		| "sleep"
-		| "timeout"
-		| "seq"
-		| "expr"
-		| "md5sum"
-		| "sha1sum"
-		| "sha256sum"
-		| "file"
-		| "html-to-markdown"
-		| "help"
-		| "which"
-		| "tac"
-		| "hostname"
-		| "od"
-		| "gzip"
-		| "gunzip"
-		| "zcat"
-		| "tar"
-		| "yq"
-		| "xan"
-		| "sqlite3"
-		| "time"
-		| "whoami";
-
-	type NetworkCommandName = "curl";
-	type PythonCommandName = "python3" | "python";
-	type AllCommandName = CommandName | NetworkCommandName | PythonCommandName;
-
-	function getCommandNames(): string[];
-	function getNetworkCommandNames(): string[];
-	function getPythonCommandNames(): string[];
-
-	// ========================================================================
-	// Network types (from network/types.d.ts)
-	// ========================================================================
-
-	type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
-
-	interface NetworkConfig {
-		allowedUrlPrefixes?: string[];
-		allowedMethods?: HttpMethod[];
-		dangerouslyAllowFullInternetAccess?: boolean;
-		maxRedirects?: number;
-		timeoutMs?: number;
-		maxResponseSize?: number;
-	}
-
-	interface FetchResult {
-		status: number;
-		statusText: string;
-		headers: Record<string, string>;
-		body: string;
-		url: string;
-	}
-
-	interface SecureFetchOptions {
-		method?: string;
-		headers?: Record<string, string>;
-		body?: string;
-		followRedirects?: boolean;
-		timeoutMs?: number;
-	}
-
-	type SecureFetch = (url: string, options?: SecureFetchOptions) => Promise<FetchResult>;
-
-	function createSecureFetch(config: NetworkConfig): SecureFetch;
-
-	class NetworkAccessDeniedError extends Error {
-		constructor(url: string);
-	}
-	class TooManyRedirectsError extends Error {
-		constructor(maxRedirects: number);
-	}
-	class RedirectNotAllowedError extends Error {
-		constructor(url: string);
-	}
-
-	// ========================================================================
-	// Custom commands (from custom-commands.d.ts)
-	// ========================================================================
-
-	type CustomCommand = Command | LazyCommand;
-
-	interface LazyCommand {
-		name: string;
-		load: () => Promise<Command>;
-	}
-
-	function isLazyCommand(cmd: CustomCommand): cmd is LazyCommand;
-	function defineCommand(
-		name: string,
-		execute: (args: string[], ctx: CommandContext) => Promise<ExecResult>,
-	): Command;
-	function createLazyCustomCommand(lazy: LazyCommand): Command;
-
-	// ========================================================================
-	// Bash class (from Bash.d.ts)
-	// ========================================================================
-
-	interface BashLogger {
-		info(message: string, data?: Record<string, unknown>): void;
-		debug(message: string, data?: Record<string, unknown>): void;
-	}
-
-	interface BashOptions {
-		files?: InitialFiles;
-		env?: Record<string, string>;
-		cwd?: string;
-		fs?: IFileSystem;
-		executionLimits?: ExecutionLimits;
-		/** @deprecated Use executionLimits.maxCallDepth instead */
-		maxCallDepth?: number;
-		/** @deprecated Use executionLimits.maxCommandCount instead */
-		maxCommandCount?: number;
-		/** @deprecated Use executionLimits.maxLoopIterations instead */
-		maxLoopIterations?: number;
-		network?: NetworkConfig;
-		python?: boolean;
-		commands?: CommandName[];
-		sleep?: (ms: number) => Promise<void>;
-		customCommands?: CustomCommand[];
-		logger?: BashLogger;
-		trace?: TraceCallback;
-		defenseInDepth?: DefenseInDepthConfig | boolean;
-		coverage?: FeatureCoverageWriter;
-	}
-
-	interface ExecOptions {
-		env?: Record<string, string>;
-		cwd?: string;
-		rawScript?: boolean;
-	}
-
-	class Bash {
-		readonly fs: IFileSystem;
-		constructor(options?: BashOptions);
-		registerCommand(command: Command): void;
-		exec(commandLine: string, options?: ExecOptions): Promise<BashExecResult>;
-		readFile(path: string): Promise<string>;
-		writeFile(path: string, content: string): Promise<void>;
-		getCwd(): string;
-		getEnv(): Record<string, string>;
-	}
-
-	// ========================================================================
-	// Filesystem implementations
-	// ========================================================================
-
-	class InMemoryFs implements IFileSystem {
-		constructor(initialFiles?: InitialFiles);
-		writeFileSync(
-			path: string,
-			content: FileContent,
-			options?: WriteFileOptions | BufferEncoding,
-			metadata?: { mode?: number; mtime?: Date },
-		): void;
-		mkdirSync(path: string, options?: MkdirOptions): void;
-		readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
-		readFileBuffer(path: string): Promise<Uint8Array>;
-		writeFile(
-			path: string,
-			content: FileContent,
-			options?: WriteFileOptions | BufferEncoding,
-		): Promise<void>;
-		appendFile(
-			path: string,
-			content: FileContent,
-			options?: WriteFileOptions | BufferEncoding,
-		): Promise<void>;
-		exists(path: string): Promise<boolean>;
-		stat(path: string): Promise<FsStat>;
-		lstat(path: string): Promise<FsStat>;
-		mkdir(path: string, options?: MkdirOptions): Promise<void>;
-		readdir(path: string): Promise<string[]>;
-		readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
-		rm(path: string, options?: RmOptions): Promise<void>;
-		cp(src: string, dest: string, options?: CpOptions): Promise<void>;
-		mv(src: string, dest: string): Promise<void>;
-		getAllPaths(): string[];
-		resolvePath(base: string, path: string): string;
-		chmod(path: string, mode: number): Promise<void>;
-		symlink(target: string, linkPath: string): Promise<void>;
-		link(existingPath: string, newPath: string): Promise<void>;
-		readlink(path: string): Promise<string>;
-		realpath(path: string): Promise<string>;
-		utimes(path: string, atime: Date, mtime: Date): Promise<void>;
-	}
-
-	interface OverlayFsOptions {
-		root: string;
-		mountPoint?: string;
-		readOnly?: boolean;
-		maxFileReadSize?: number;
-	}
-
-	class OverlayFs implements IFileSystem {
-		constructor(options: OverlayFsOptions);
-		getMountPoint(): string;
-		mkdirSync(path: string, options?: MkdirOptions): void;
-		writeFileSync(path: string, content: string | Uint8Array): void;
-		readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
-		readFileBuffer(path: string): Promise<Uint8Array>;
-		writeFile(
-			path: string,
-			content: FileContent,
-			options?: WriteFileOptions | BufferEncoding,
-		): Promise<void>;
-		appendFile(
-			path: string,
-			content: FileContent,
-			options?: WriteFileOptions | BufferEncoding,
-		): Promise<void>;
-		exists(path: string): Promise<boolean>;
-		stat(path: string): Promise<FsStat>;
-		lstat(path: string): Promise<FsStat>;
-		mkdir(path: string, options?: MkdirOptions): Promise<void>;
-		readdir(path: string): Promise<string[]>;
-		readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
-		rm(path: string, options?: RmOptions): Promise<void>;
-		cp(src: string, dest: string, options?: CpOptions): Promise<void>;
-		mv(src: string, dest: string): Promise<void>;
-		resolvePath(base: string, path: string): string;
-		getAllPaths(): string[];
-		chmod(path: string, mode: number): Promise<void>;
-		symlink(target: string, linkPath: string): Promise<void>;
-		link(existingPath: string, newPath: string): Promise<void>;
-		readlink(path: string): Promise<string>;
-		realpath(path: string): Promise<string>;
-		utimes(path: string, atime: Date, mtime: Date): Promise<void>;
-	}
-
-	interface ReadWriteFsOptions {
-		root: string;
-		maxFileReadSize?: number;
-	}
-
-	class ReadWriteFs implements IFileSystem {
-		constructor(options: ReadWriteFsOptions);
-		readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
-		readFileBuffer(path: string): Promise<Uint8Array>;
-		writeFile(
-			path: string,
-			content: FileContent,
-			options?: WriteFileOptions | BufferEncoding,
-		): Promise<void>;
-		appendFile(
-			path: string,
-			content: FileContent,
-			options?: WriteFileOptions | BufferEncoding,
-		): Promise<void>;
-		exists(path: string): Promise<boolean>;
-		stat(path: string): Promise<FsStat>;
-		lstat(path: string): Promise<FsStat>;
-		mkdir(path: string, options?: MkdirOptions): Promise<void>;
-		readdir(path: string): Promise<string[]>;
-		readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
-		rm(path: string, options?: RmOptions): Promise<void>;
-		cp(src: string, dest: string, options?: CpOptions): Promise<void>;
-		mv(src: string, dest: string): Promise<void>;
-		resolvePath(base: string, path: string): string;
-		getAllPaths(): string[];
-		chmod(path: string, mode: number): Promise<void>;
-		symlink(target: string, linkPath: string): Promise<void>;
-		link(existingPath: string, newPath: string): Promise<void>;
-		readlink(path: string): Promise<string>;
-		realpath(path: string): Promise<string>;
-		utimes(path: string, atime: Date, mtime: Date): Promise<void>;
-	}
-
-	interface MountConfig {
-		mountPoint: string;
-		filesystem: IFileSystem;
-	}
-
-	interface MountableFsOptions {
-		base?: IFileSystem;
-		mounts?: MountConfig[];
-	}
-
-	class MountableFs implements IFileSystem {
-		constructor(options?: MountableFsOptions);
-		mount(mountPoint: string, filesystem: IFileSystem): void;
-		unmount(mountPoint: string): void;
-		getMounts(): ReadonlyArray<{ mountPoint: string; filesystem: IFileSystem }>;
-		isMountPoint(path: string): boolean;
-		readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
-		readFileBuffer(path: string): Promise<Uint8Array>;
-		writeFile(
-			path: string,
-			content: FileContent,
-			options?: WriteFileOptions | BufferEncoding,
-		): Promise<void>;
-		appendFile(
-			path: string,
-			content: FileContent,
-			options?: WriteFileOptions | BufferEncoding,
-		): Promise<void>;
-		exists(path: string): Promise<boolean>;
-		stat(path: string): Promise<FsStat>;
-		lstat(path: string): Promise<FsStat>;
-		mkdir(path: string, options?: MkdirOptions): Promise<void>;
-		readdir(path: string): Promise<string[]>;
-		rm(path: string, options?: RmOptions): Promise<void>;
-		cp(src: string, dest: string, options?: CpOptions): Promise<void>;
-		mv(src: string, dest: string): Promise<void>;
-		resolvePath(base: string, path: string): string;
-		getAllPaths(): string[];
-		chmod(path: string, mode: number): Promise<void>;
-		symlink(target: string, linkPath: string): Promise<void>;
-		link(existingPath: string, newPath: string): Promise<void>;
-		readlink(path: string): Promise<string>;
-		realpath(path: string): Promise<string>;
-		utimes(path: string, atime: Date, mtime: Date): Promise<void>;
-	}
-
-	// ========================================================================
-	// Sandbox (from sandbox/)
-	// ========================================================================
-
-	interface OutputMessage {
-		type: "stdout" | "stderr";
-		data: string;
-		timestamp: Date;
-	}
-
-	class SandboxCommand {
-		readonly cmdId: string;
-		readonly cwd: string;
-		readonly startedAt: Date;
-		exitCode: number | undefined;
-		logs(): AsyncGenerator<OutputMessage, void, unknown>;
-		wait(): Promise<SandboxCommandFinished>;
-		output(): Promise<string>;
-		stdout(): Promise<string>;
-		stderr(): Promise<string>;
-		kill(): Promise<void>;
-	}
-
-	interface SandboxCommandFinished extends SandboxCommand {
-		exitCode: number;
-	}
-
-	interface SandboxOptions {
-		cwd?: string;
-		env?: Record<string, string>;
-		timeoutMs?: number;
-		fs?: IFileSystem;
-		overlayRoot?: string;
-		maxCallDepth?: number;
-		maxCommandCount?: number;
-		maxLoopIterations?: number;
-		network?: NetworkConfig;
-	}
-
-	interface WriteFilesInput {
-		[path: string]:
-			| string
-			| {
-					content: string;
-					encoding?: "utf-8" | "base64";
-			  };
-	}
-
-	class Sandbox {
-		static create(opts?: SandboxOptions): Promise<Sandbox>;
-		runCommand(
-			cmd: string,
-			opts?: { cwd?: string; env?: Record<string, string> },
-		): Promise<SandboxCommand>;
-		writeFiles(files: WriteFilesInput): Promise<void>;
-		readFile(path: string, encoding?: "utf-8" | "base64"): Promise<string>;
-		mkDir(path: string, opts?: { recursive?: boolean }): Promise<void>;
-		stop(): Promise<void>;
-		extendTimeout(ms: number): Promise<void>;
-		get domain(): string | undefined;
-		get bashEnvInstance(): Bash;
-	}
-
-	// ========================================================================
-	// Security / Defense-in-Depth
-	// ========================================================================
-
-	type SecurityViolationType = string;
-
-	interface SecurityViolation {
-		type: SecurityViolationType;
-		target: string;
-		details: string;
-	}
-
-	interface DefenseInDepthConfig {
-		enabled?: boolean;
-		auditMode?: boolean;
-		onViolation?: (violation: SecurityViolation) => void;
-	}
-
-	interface DefenseInDepthHandle {
-		run<T>(fn: () => T): T;
-		deactivate(): void;
-		executionId: string;
-	}
-
-	interface DefenseInDepthStats {
-		violationsBlocked: number;
-		violations: SecurityViolation[];
-		activeTimeMs: number;
-		refCount: number;
-	}
-
-	class DefenseInDepthBox {
-		constructor(config: DefenseInDepthConfig);
-		updateConfig(config: DefenseInDepthConfig): void;
-		activate(): DefenseInDepthHandle;
-		forceDeactivate(): void;
-		isActive(): boolean;
-		getStats(): DefenseInDepthStats;
-		clearViolations(): void;
-	}
-
-	class SecurityViolationError extends Error {
-		violation: SecurityViolation;
-		name: "SecurityViolationError";
-		constructor(message: string);
-	}
-
-	class SecurityViolationLogger {
-		constructor();
-		record(violation: SecurityViolation): void;
-		getViolations(): SecurityViolation[];
-		getViolationsByType(type: SecurityViolationType): SecurityViolation[];
-		getSummary(): Array<{ type: string; count: number }>;
-		getTotalCount(): number;
-		hasViolations(): boolean;
-		clear(): void;
-		createCallback(): (violation: SecurityViolation) => void;
-	}
-
-	function createConsoleViolationCallback(): (violation: SecurityViolation) => void;
-}