@demicodes/shell 0.14.0 → 0.14.2

package/dist/host-fs.d.mts

@@ -15,14 +15,27 @@ type VirtualFileSystemNode = {
 interface VirtualFileSystemProvider {
   lookup(path: string): Promise<VirtualFileSystemNode | null> | VirtualFileSystemNode | null;
 }
+interface HostBackedFileSystemOptions {
+  lookup?: VirtualFileSystemProvider['lookup'];
+  /**
+   * Ceiling for a single file read through this filesystem. Portable commands
+   * (cat/grep/rg/head/...) run in-process and load files whole, so one read of
+   * an oversized file becomes resident memory in the embedding host — a broad
+   * scan over a large tree can balloon the process by gigabytes. Oversized
+   * files fail loudly instead; real-process routes (`bash -c`) stay available
+   * for genuinely large files.
+   */
+  maxFileReadBytes?: number;
+}
 /** Builds a virtual directory node; entry names containing a dot are treated as files. */
 declare function virtualDirectory(names: string[]): VirtualFileSystemNode;
 /** Builds a virtual file node from raw bytes. */
 declare function virtualFile(content: Uint8Array): VirtualFileSystemNode;
 declare class HostBackedFileSystem implements IFileSystem {
   private readonly host;
-  private readonly virtualProvider?;
-  constructor(host: Host, virtualProvider?: VirtualFileSystemProvider | undefined);
+  private readonly options;
+  private readonly maxFileReadBytes;
+  constructor(host: Host, options?: HostBackedFileSystemOptions);
   readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
   readFileBuffer(path: string): Promise<Uint8Array>;
   writeFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
@@ -48,4 +61,4 @@ declare class HostBackedFileSystem implements IFileSystem {
   private assertWritablePath;
 }
 //#endregion
-export { HostBackedFileSystem, VirtualFileSystemNode, VirtualFileSystemProvider, virtualDirectory, virtualFile };
+export { HostBackedFileSystem, HostBackedFileSystemOptions, VirtualFileSystemNode, VirtualFileSystemProvider, virtualDirectory, virtualFile };

package/dist/host-fs.mjs

@@ -1,5 +1,6 @@
 import { decodeUtf8, encodeUtf8, isAbsolutePath, normalizePath } from "@demicodes/utils";
 //#region src/host-fs.ts
+const DEFAULT_FILE_READ_LIMIT_BYTES = 67108864;
 /** Builds a virtual directory node; entry names containing a dot are treated as files. */
 function virtualDirectory(names) {
 	return {
@@ -21,10 +22,12 @@ function virtualFile(content) {
 }
 var HostBackedFileSystem = class {
 	host;
-	virtualProvider;
-	constructor(host, virtualProvider) {
+	options;
+	maxFileReadBytes;
+	constructor(host, options = {}) {
 		this.host = host;
-		this.virtualProvider = virtualProvider;
+		this.options = options;
+		this.maxFileReadBytes = options.maxFileReadBytes ?? DEFAULT_FILE_READ_LIMIT_BYTES;
 	}
 	async readFile(path, options) {
 		return decodeBytes(await this.readFileBuffer(path), encodingFrom(options));
@@ -35,6 +38,8 @@ var HostBackedFileSystem = class {
 			if (virtual.kind !== "file") throw new Error(`EISDIR: illegal operation on a directory, read '${path}'`);
 			return virtual.content;
 		}
+		const stat = await this.host.fs.stat(path, { cwd: this.host.defaultCwd });
+		if (stat.isFile && stat.size > this.maxFileReadBytes) throw new Error(`EFBIG: file exceeds the ${this.maxFileReadBytes}-byte in-shell read limit (${stat.size} bytes), read '${path}'; read a slice instead, or process it with a real process via 'bash -c'`);
 		return this.host.fs.readFile(path, { cwd: this.host.defaultCwd });
 	}
 	async writeFile(path, content, options) {
@@ -151,8 +156,8 @@ var HostBackedFileSystem = class {
 		await this.host.fs.utimes(path, atime, mtime, { cwd: this.host.defaultCwd });
 	}
 	async lookupVirtual(path) {
-		if (!this.virtualProvider || !isVirtualPath(path)) return null;
-		return await this.virtualProvider.lookup(normalizePath(path)) ?? null;
+		if (!this.options.lookup || !isVirtualPath(path)) return null;
+		return await this.options.lookup(normalizePath(path)) ?? null;
 	}
 	assertWritablePath(path) {
 		if (isVirtualPath(path)) throw new Error(`EROFS: read-only virtual filesystem, '${path}'`);

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { a as HostProcess, c as HostSpawnHandle, i as HostFileSystem, l as HostSpawnParams, n as HostDirent, o as HostProcessOutputChunk, r as HostFileStat, s as HostSpawnExit, t as Host, u as HostStore } from "./host-DIg4RxcL.mjs";
-import { HostBackedFileSystem, VirtualFileSystemNode, VirtualFileSystemProvider, virtualDirectory, virtualFile } from "./host-fs.mjs";
+import { HostBackedFileSystem, HostBackedFileSystemOptions, VirtualFileSystemNode, VirtualFileSystemProvider, virtualDirectory, virtualFile } from "./host-fs.mjs";
 import { _ as runRegisteredCommand, a as CommandIO, c as CommandRegistry, d as CommandStdin, f as CommandStorage, g as renderCommandHelp, h as parseCommandInput, i as CommandExecutionContext, l as CommandRunContext, m as emptyStdin, n as COMMAND_HELP_DEFAULTS, o as CommandInputSpec, p as ParsedCommandInput, r as Command, s as CommandOutputSpec, t as AgentSessionCommandStorage, u as CommandRunResult } from "./storage-CNMBL9_j.mjs";
 import { CommandName } from "@demicodes/just-bash/commands";
 import { Interpreter, InterpreterState } from "@demicodes/just-bash/interpreter";
@@ -38,6 +38,9 @@ interface BackgroundJob {
   handle: HostSpawnHandle;
   stdoutBuffer: string;
   stderrBuffer: string;
+  /** Chars discarded from the head of each buffer once it outgrew the capture limit. */
+  droppedStdoutChars: number;
+  droppedStderrChars: number;
   stdoutPump: Promise<void>;
   stderrPump: Promise<void>;
   exitPromise: Promise<{
@@ -66,6 +69,10 @@ interface ForegroundProcess {
   /** Interleaved visible chunks with running byte offsets, for merged replay. */
   outputChunks: ShellOutputRecordChunk[];
   outputBytes: number;
+  /** Total bytes ingested across both streams; the capture limit judges this. */
+  capturedBytes: number;
+  /** Set when the capture limit was breached: the process is killed and further chunks dropped. */
+  captureOverflowed: boolean;
   audit: BashAuditEvent[];
   stdoutPump: Promise<void>;
   stderrPump: Promise<void>;
@@ -106,6 +113,19 @@ interface BashEnvironmentOptions {
    * above, where models are known.
    */
   maxBinaryBytes?: number;
+  /**
+   * Ceiling for the bytes a single command's output capture may ingest.
+   *
+   * Distinct from `maxOutputBytes`, which sizes the rendered view: capture is
+   * what the environment holds in memory while a command runs, and it holds
+   * several copies (raw bytes for the pipe, text renders, replay chunks). A
+   * foreground process that produces more than this is SIGKILLed and the
+   * command fails with an explicit error; a background job keeps only the most
+   * recent bytes within the ceiling. Without this ceiling one stray
+   * `rg`/`cat` over a large tree balloons the embedding process by tens of
+   * gigabytes until the kernel OOM-kills it.
+   */
+  maxCaptureBytes?: number;
 }
 interface ShellExecInput {
   script: string;
@@ -246,6 +266,7 @@ declare class BashEnvironment {
   private readonly initialEnv;
   private readonly defaultOutputLimitBytes;
   private readonly defaultBinaryLimitBytes;
+  private readonly captureLimitBytes;
   private readonly shells;
   private readonly defaultShellByAgentSessionId;
   private readonly commandsById;
@@ -321,4 +342,4 @@ declare function shellQuote(value: string): string;
 /** Picks a heredoc delimiter that does not collide with any line already in `body`. */
 declare function heredocDelimiter(body: string): string;
 //#endregion
-export { AgentSessionCommandStorage, BashAuditEvent, BashEnvironment, BashEnvironmentOptions, BinaryStdout, COMMAND_HELP_DEFAULTS, Command, CommandExecutionContext, CommandIO, CommandInputSpec, CommandMetadataRecord, CommandOutputSpec, CommandRegistry, CommandRunContext, CommandRunResult, CommandStdin, CommandStorage, DEMI_PORTABLE_COMMANDS, Host, HostBackedFileSystem, HostDirent, HostFileStat, HostFileSystem, HostProcess, HostProcessOutputChunk, HostSpawnExit, HostSpawnHandle, HostSpawnParams, HostStore, MAX_TIMEOUT_MS, ParsedCommandInput, RESERVED_COMMAND_NAMES, ShellAbortInput, ShellCommandStatus, ShellExecInput, ShellOutputChunk, ShellOutputRecordChunk, ShellOutputView, ShellStatusInput, ShellStreamView, ShellWriteInput, VirtualFileSystemNode, VirtualFileSystemProvider, emptyStdin, heredocDelimiter, parseCommandInput, renderCommandHelp, runRegisteredCommand, shellQuote, virtualDirectory, virtualFile };
+export { AgentSessionCommandStorage, BashAuditEvent, BashEnvironment, BashEnvironmentOptions, BinaryStdout, COMMAND_HELP_DEFAULTS, Command, CommandExecutionContext, CommandIO, CommandInputSpec, CommandMetadataRecord, CommandOutputSpec, CommandRegistry, CommandRunContext, CommandRunResult, CommandStdin, CommandStorage, DEMI_PORTABLE_COMMANDS, Host, HostBackedFileSystem, HostBackedFileSystemOptions, HostDirent, HostFileStat, HostFileSystem, HostProcess, HostProcessOutputChunk, HostSpawnExit, HostSpawnHandle, HostSpawnParams, HostStore, MAX_TIMEOUT_MS, ParsedCommandInput, RESERVED_COMMAND_NAMES, ShellAbortInput, ShellCommandStatus, ShellExecInput, ShellOutputChunk, ShellOutputRecordChunk, ShellOutputView, ShellStatusInput, ShellStreamView, ShellWriteInput, VirtualFileSystemNode, VirtualFileSystemProvider, emptyStdin, heredocDelimiter, parseCommandInput, renderCommandHelp, runRegisteredCommand, shellQuote, virtualDirectory, virtualFile };

package/dist/index.mjs

@@ -501,7 +501,16 @@ function createOutputSinks(fs, cwd, redirections) {
 	}
 	return routes;
 }
-function recordForegroundChunk(foreground, sourceFd, chunk) {
+function recordForegroundChunk(foreground, sourceFd, chunk, captureLimitBytes) {
+	if (foreground.captureOverflowed) return;
+	if (foreground.capturedBytes + chunk.byteLength > captureLimitBytes) {
+		foreground.captureOverflowed = true;
+		foreground.rawStdoutBuffer = "";
+		foreground.rawStdoutBytes = [];
+		foreground.handle.kill("SIGKILL").catch(() => {});
+		return;
+	}
+	foreground.capturedBytes += chunk.byteLength;
 	const text = decodeUtf8(chunk);
 	foreground.lastOutputAt = Date.now();
 	if (sourceFd === 1) {
@@ -778,6 +787,13 @@ const DEFAULT_OUTPUT_LIMIT_BYTES = 1048576;
 * while still bounding a runaway producer.
 */
 const DEFAULT_BINARY_LIMIT_BYTES = 16777216;
+/**
+* Ceiling for a single command's in-memory output capture. Sized to the same
+* order as the in-shell file read limit: the execution model buffers whole
+* command outputs (in several copies), so this is a hard memory-safety bound
+* on the embedding process, not a view budget.
+*/
+const DEFAULT_CAPTURE_LIMIT_BYTES = 67108864;
 /** Upper bound for a single exec observation window (also the command-bridge wait ceiling). */
 const MAX_TIMEOUT_MS = 6e5;
 var BashEnvironment = class {
@@ -788,6 +804,7 @@ var BashEnvironment = class {
 	initialEnv;
 	defaultOutputLimitBytes;
 	defaultBinaryLimitBytes;
+	captureLimitBytes;
 	shells = /* @__PURE__ */ new Map();
 	defaultShellByAgentSessionId = /* @__PURE__ */ new Map();
 	commandsById = /* @__PURE__ */ new Map();
@@ -801,6 +818,7 @@ var BashEnvironment = class {
 		this.initialEnv = options.initialEnv ?? {};
 		this.defaultOutputLimitBytes = options.maxOutputBytes ?? DEFAULT_OUTPUT_LIMIT_BYTES;
 		this.defaultBinaryLimitBytes = options.maxBinaryBytes ?? DEFAULT_BINARY_LIMIT_BYTES;
+		this.captureLimitBytes = options.maxCaptureBytes ?? DEFAULT_CAPTURE_LIMIT_BYTES;
 	}
 	getShell(shellId) {
 		return this.shells.get(shellId) ?? null;
@@ -1025,7 +1043,7 @@ var BashEnvironment = class {
 		for (const command of this.commands.list()) forkCommands.set(command.name, commandToForkCommand(session, command, storage, this.host));
 		session.abortController = new AbortController();
 		const limits = resolveLimits({
-			maxOutputSize: 1073741824,
+			maxOutputSize: this.captureLimitBytes,
 			maxCommandCount: 1e6,
 			maxLoopIterations: 1e6,
 			maxCallDepth: 1e3,
@@ -1135,15 +1153,26 @@ var BashEnvironment = class {
 			handle,
 			stdoutBuffer: "",
 			stderrBuffer: "",
+			droppedStdoutChars: 0,
+			droppedStderrChars: 0,
 			stdoutPump: Promise.resolve(),
 			stderrPump: Promise.resolve(),
 			exitPromise: handle.wait()
 		};
+		const retainLimit = this.defaultOutputLimitBytes;
 		job.stdoutPump = pumpStream(handle.stdout, (chunk) => {
 			job.stdoutBuffer += decodeUtf8(chunk);
+			if (job.stdoutBuffer.length > retainLimit) {
+				job.droppedStdoutChars += job.stdoutBuffer.length - retainLimit;
+				job.stdoutBuffer = job.stdoutBuffer.slice(-retainLimit);
+			}
 		});
 		job.stderrPump = pumpStream(handle.stderr, (chunk) => {
 			job.stderrBuffer += decodeUtf8(chunk);
+			if (job.stderrBuffer.length > retainLimit) {
+				job.droppedStderrChars += job.stderrBuffer.length - retainLimit;
+				job.stderrBuffer = job.stderrBuffer.slice(-retainLimit);
+			}
 		});
 		session.backgroundJobs.set(id, job);
 		session.state.lastBackgroundPid = id;
@@ -1191,7 +1220,8 @@ var BashEnvironment = class {
 		await Promise.allSettled([job.stdoutPump, job.stderrPump]);
 		session.backgroundJobs.delete(id);
 		const exitCode = exit.exitCode ?? 127;
-		const stderr = exit.exitCode === null && job.stderrBuffer.length === 0 ? `${job.command}: ${exit.signal ?? "command not found"}\n` : job.stderrBuffer;
+		const stdout = job.droppedStdoutChars > 0 ? `[... dropped ${job.droppedStdoutChars} chars of earlier stdout over the capture limit ...]\n${job.stdoutBuffer}` : job.stdoutBuffer;
+		const stderr = exit.exitCode === null && job.stderrBuffer.length === 0 ? `${job.command}: ${exit.signal ?? "command not found"}\n` : job.droppedStderrChars > 0 ? `[... dropped ${job.droppedStderrChars} chars of earlier stderr over the capture limit ...]\n${job.stderrBuffer}` : job.stderrBuffer;
 		session.accumulator.audit.push({
 			kind: "system-command",
 			name: job.command,
@@ -1200,7 +1230,7 @@ var BashEnvironment = class {
 			exitCode
 		});
 		return {
-			stdout: job.stdoutBuffer,
+			stdout,
 			stderr,
 			exitCode
 		};
@@ -1321,6 +1351,8 @@ var BashEnvironment = class {
 			stderrBuffer: "",
 			outputChunks: [],
 			outputBytes: 0,
+			capturedBytes: 0,
+			captureOverflowed: false,
 			audit: [{
 				kind: "system-command",
 				name: command,
@@ -1340,18 +1372,18 @@ var BashEnvironment = class {
 		if (opts.stdinProvided) await handle.closeStdin();
 		if (handle.output) {
 			foreground.stdoutPump = pumpOutputStream(handle.output, (chunk) => {
-				recordForegroundChunk(foreground, chunk.stream === "stdout" ? 1 : 2, chunk.chunk);
+				recordForegroundChunk(foreground, chunk.stream === "stdout" ? 1 : 2, chunk.chunk, this.captureLimitBytes);
 			});
 			foreground.stderrPump = Promise.resolve();
 		} else {
-			foreground.stdoutPump = pumpStream(handle.stdout, (chunk) => recordForegroundChunk(foreground, 1, chunk));
-			foreground.stderrPump = pumpStream(handle.stderr, (chunk) => recordForegroundChunk(foreground, 2, chunk));
+			foreground.stdoutPump = pumpStream(handle.stdout, (chunk) => recordForegroundChunk(foreground, 1, chunk, this.captureLimitBytes));
+			foreground.stderrPump = pumpStream(handle.stderr, (chunk) => recordForegroundChunk(foreground, 2, chunk, this.captureLimitBytes));
 		}
 		const exit = await foreground.exitPromise;
 		await Promise.allSettled([foreground.stdoutPump, foreground.stderrPump]);
-		const stdout = decodeLatin1(concatBytes(foreground.rawStdoutBytes));
-		const exitCode = exit.exitCode ?? 127;
-		const stderr = exit.exitCode === null && foreground.rawStderrBuffer.length === 0 ? `${command}: ${exit.signal ?? "command not found"}\n` : foreground.rawStderrBuffer;
+		const stdout = foreground.captureOverflowed ? "" : decodeLatin1(concatBytes(foreground.rawStdoutBytes));
+		const exitCode = foreground.captureOverflowed ? 137 : exit.exitCode ?? 127;
+		const stderr = foreground.captureOverflowed ? `${command}: output exceeded the ${this.captureLimitBytes}-byte capture limit and the process was killed; the shell buffers whole command outputs in memory — narrow the output at the source (filters, head, tighter paths)\n` : exit.exitCode === null && foreground.rawStderrBuffer.length === 0 ? `${command}: ${exit.signal ?? "command not found"}\n` : foreground.rawStderrBuffer;
 		foreground.audit[0] = {
 			kind: "system-command",
 			name: command,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/shell",
   "description": "Sandboxable bash engine and Host contract for Demi.",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "private": false,
   "type": "module",
   "exports": {
@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@demicodes/just-bash": "^3.0.1-demi.5",
-    "@demicodes/utils": "^0.14.0",
+    "@demicodes/utils": "^0.14.2",
     "zod": "^4.0.0"
   },
   "license": "Apache-2.0",