@demicodes/shell 0.10.3 → 0.12.0

package/dist/host-fs.d.mts

@@ -1,6 +1,5 @@
 import { t as Host } from "./host-DIg4RxcL.mjs";
 import { BufferEncoding, CpOptions, DirentEntry, FileContent, FsStat, IFileSystem, MkdirOptions, ReadFileOptions, RmOptions, WriteFileOptions } from "@demicodes/just-bash/fs/interface";
-
 //#region src/host-fs.d.ts
 type VirtualFileSystemNode = {
   kind: 'file';

package/dist/host-fs.mjs

@@ -166,13 +166,13 @@ function encodingFrom(options) {
 function encodeContent(content, encoding) {
 	if (content instanceof Uint8Array) return content;
 	if (encoding === "binary" || encoding === "latin1") return latin1ToBytes(content);
-	if (encoding === "base64") return base64ToBytes(content);
+	if (encoding === "base64") return base64ToBytes$1(content);
 	if (encoding === "hex") return hexToBytes(content);
 	return encodeUtf8(content);
 }
 function decodeBytes(bytes, encoding) {
 	if (encoding === "binary" || encoding === "latin1") return bytesToLatin1(bytes);
-	if (encoding === "base64") return bytesToBase64(bytes);
+	if (encoding === "base64") return bytesToBase64$1(bytes);
 	if (encoding === "hex") return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 	return decodeUtf8(bytes);
 }
@@ -186,10 +186,10 @@ function bytesToLatin1(bytes) {
 	for (let index = 0; index < bytes.length; index += 8192) result += String.fromCharCode(...bytes.subarray(index, index + 8192));
 	return result;
 }
-function base64ToBytes(content) {
+function base64ToBytes$1(content) {
 	return latin1ToBytes(atob(content));
 }
-function bytesToBase64(bytes) {
+function bytesToBase64$1(bytes) {
 	return btoa(bytesToLatin1(bytes));
 }
 function hexToBytes(content) {

package/dist/index.d.mts

@@ -1,21 +1,20 @@
 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 { _ as runRegisteredCommand, a as CommandExecutionContext, c as CommandOutputSpec, d as CommandRunResult, f as CommandStdin, g as renderCommandPrompt, h as parseCommandInput, i as CommandAsset, l as CommandRegistry, m as ParsedCommandInput, n as COMMAND_PROMPT_DEFAULTS, o as CommandIO, p as CommandStorage, r as Command, s as CommandInputSpec, t as AgentSessionCommandStorage, u as CommandRunContext } from "./storage-D7EhVuLY.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-ylShLr2v.mjs";
 import { CommandName } from "@demicodes/just-bash/commands";
 import { Interpreter, InterpreterState } from "@demicodes/just-bash/interpreter";
 import { CommandRegistry as CommandRegistry$1, ExecResult } from "@demicodes/just-bash/types";
-
 //#region src/environment-state.d.ts
 interface ExecAccumulator {
   stdout: string;
   stderr: string;
   audit: BashAuditEvent[];
   commandMetadata: CommandMetadataRecord[];
-  assets: CommandAsset[];
 }
 interface ShellSession {
   id: string;
-  commandScopeId: string;
+  agentSessionId: string | null;
+  commandStorageId: string;
   state: InterpreterState;
   fs: HostBackedFileSystem;
   interpreter: Interpreter;
@@ -57,6 +56,8 @@ interface ForegroundProcess {
   /** Everything the process wrote, including redirected output — this is what
    * the interpreter observes as the command's stdout/stderr. */
   rawStdoutBuffer: string;
+  /** Raw stdout byte chunks for byte-clean pipeline continuation. */
+  rawStdoutBytes: Uint8Array[];
   rawStderrBuffer: string;
   /** Output routed to the visible sinks only (redirections excluded) — this is
    * what command records and model previews show. */
@@ -90,15 +91,21 @@ interface BashEnvironmentOptions {
   shellIdFactory?: () => string;
   commandIdFactory?: () => string;
   initialEnv?: Record<string, string>;
+  /** Cap on a command's text stdout. Guards against log floods. */
+  maxOutputBytes?: number;
   /**
-   * Per-exec env injection for agent-owned shells. Evaluated on every exec with
-   * the owning agent session id; returned vars are set and exported, so both
-   * registered commands (ctx.env) and spawned external processes observe them.
-   * Lets a product harness expose session-scoped context (identity, routing)
-   * that changes between execs, which static initialEnv cannot express.
+   * Cap on a final stdout stream that is raw bytes rather than text.
+   *
+   * Separate from `maxOutputBytes` because the two guard different risks. Text
+   * costs context roughly in proportion to its bytes, so a tight cap is what
+   * stops a stray `cat` of a log file from flooding a window. Raw bytes are
+   * carried to be looked at — a picture, a clip — and there a megabyte buys far
+   * more than a megabyte of text does, so the same number would forbid the
+   * ordinary case. This layer deliberately stops at that distinction: which
+   * modality the bytes are, and what a given model should be shown, is decided
+   * above, where models are known.
    */
-  execEnv?: (agentSessionId: string) => Record<string, string>;
-  maxOutputBytes?: number;
+  maxBinaryBytes?: number;
 }
 interface ShellExecInput {
   script: string;
@@ -107,6 +114,18 @@ interface ShellExecInput {
   timeoutMs?: number;
   maxOutputBytes?: number;
   signal?: AbortSignal;
+  /**
+   * Run in a dedicated one-shot shell instead of the session default shell, so
+   * cd/env side effects never leak into other execs sharing the session. The
+   * caller owns the shell and should `disposeShell(snapshot.shellId)` when done.
+   * Mutually exclusive with `shellId`.
+   */
+  ephemeral?: boolean;
+  /**
+   * Initial working directory of the shell this exec creates. Requires
+   * `ephemeral` — a persistent shell owns its cwd (that is what `cd` is for).
+   */
+  cwd?: string;
 }
 interface ShellStatusInput {
   commandId: string;
@@ -125,7 +144,7 @@ interface ShellAbortInput {
   commandId: string;
   maxOutputBytes?: number;
 }
-interface StreamArtifact {
+interface ShellStreamView {
   path: string;
   offset: number;
   delta: string;
@@ -141,7 +160,7 @@ interface ShellOutputRecordChunk extends ShellOutputChunk {
   offset: number;
   bytes: number;
 }
-interface ShellOutputArtifact {
+interface ShellOutputView {
   path: string;
   offset: number;
   text: string;
@@ -174,35 +193,46 @@ interface CommandMetadataRecord {
   args: string[];
   metadata: unknown;
 }
-type ShellCommandSnapshot = {
+/** Final stdout stream that is not valid UTF-8: raw bytes for the boundary above. */
+interface BinaryStdout {
+  data: Uint8Array;
+  /** True when the stream exceeded the applicable cap; data is capped. */
+  truncated: boolean;
+  /** Total byte count of the un-capped stream. */
+  totalBytes: number;
+  /** The byte ceiling that applied, so the boundary above can name it. */
+  limitBytes: number;
+}
+type ShellCommandStatus = {
   status: 'exited';
   shellId: string;
   commandId: string;
   exitCode: number;
-  stdout: StreamArtifact;
-  stderr: StreamArtifact;
-  output: ShellOutputArtifact;
+  stdout: ShellStreamView;
+  stderr: ShellStreamView;
+  output: ShellOutputView;
   runningMs: number;
   idleMs: number;
   audit: BashAuditEvent[];
   commandMetadata?: CommandMetadataRecord[];
-  assets?: CommandAsset[];
+  /** Present when the final stream was binary (bytes that are not valid UTF-8). */
+  binaryStdout?: BinaryStdout;
 } | {
   status: 'running';
   shellId: string;
   commandId: string;
-  stdout: StreamArtifact;
-  stderr: StreamArtifact;
-  output: ShellOutputArtifact;
+  stdout: ShellStreamView;
+  stderr: ShellStreamView;
+  output: ShellOutputView;
   runningMs: number;
   idleMs: number;
 } | {
   status: 'aborted';
   shellId: string;
   commandId: string;
-  stdout: StreamArtifact;
-  stderr: StreamArtifact;
-  output: ShellOutputArtifact;
+  stdout: ShellStreamView;
+  stderr: ShellStreamView;
+  output: ShellOutputView;
   runningMs: number;
   idleMs: number;
 };
@@ -214,20 +244,21 @@ declare class BashEnvironment {
   private readonly shellIdFactory;
   private readonly commandIdFactory;
   private readonly initialEnv;
-  private readonly execEnv?;
   private readonly defaultOutputLimitBytes;
+  private readonly defaultBinaryLimitBytes;
   private readonly shells;
   private readonly defaultShellByAgentSessionId;
   private readonly commandsById;
   private readonly artifacts;
   constructor(options: BashEnvironmentOptions);
   getShell(shellId: string): ShellSession | null;
+  hasCommand(commandId: string): boolean;
   registerCommand(command: Command): void;
   registeredCommands(): Command[];
-  exec(input: ShellExecInput): Promise<ShellCommandSnapshot>;
-  status(input: ShellStatusInput): Promise<ShellCommandSnapshot>;
-  write(input: ShellWriteInput): Promise<ShellCommandSnapshot>;
-  abort(input: ShellAbortInput): Promise<ShellCommandSnapshot>;
+  exec(input: ShellExecInput): Promise<ShellCommandStatus>;
+  status(input: ShellStatusInput): Promise<ShellCommandStatus>;
+  write(input: ShellWriteInput): Promise<ShellCommandStatus>;
+  abort(input: ShellAbortInput): Promise<ShellCommandStatus>;
   releaseCommand(commandId: string): Promise<boolean>;
   disposeShell(shellId: string): Promise<boolean>;
   disposeAllShells(): Promise<void>;
@@ -251,7 +282,7 @@ declare class BashEnvironment {
   private finishExited;
   private collectAborted;
   private collectAbortedWithoutForeground;
-  private snapshotCommand;
+  private commandStatus;
   private lookupVirtualArtifact;
   private commandArtifactIds;
   private commandArtifact;
@@ -290,4 +321,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, COMMAND_PROMPT_DEFAULTS, Command, CommandAsset, 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, ShellCommandSnapshot, ShellExecInput, ShellOutputArtifact, ShellOutputChunk, ShellOutputRecordChunk, ShellStatusInput, ShellWriteInput, StreamArtifact, VirtualFileSystemNode, VirtualFileSystemProvider, heredocDelimiter, parseCommandInput, renderCommandPrompt, 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, 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

@@ -1,6 +1,6 @@
 import { HostBackedFileSystem, virtualDirectory, virtualFile } from "./host-fs.mjs";
 import { AgentSessionCommandStorage } from "./storage.mjs";
-import { asError, concatBytes, decodeUtf8, encodeUtf8, tail, utf8Bytes, utf8Slice } from "@demicodes/utils";
+import { asError, base64ToBytes, bytesToBase64, concatBytes, decodeLatin1, decodeUtf8, decodeUtf8Strict, encodeLatin1, encodeUtf8, tail, utf8Bytes, utf8Slice } from "@demicodes/utils";
 import { createLazyCommands, getCommandNames } from "@demicodes/just-bash/commands";
 import { ArithmeticError, BadSubstitutionError, ExecutionLimitError, ExitError, Interpreter } from "@demicodes/just-bash/interpreter";
 import { decodeBytesToUtf8, unsafeBytesFromLatin1 } from "@demicodes/just-bash/encoding";
@@ -10,26 +10,19 @@ import { LexerError } from "@demicodes/just-bash/parser/lexer";
 import { resolveLimits } from "@demicodes/just-bash/limits";
 //#region src/portable-commands.ts
 /**
-* Individually excluded even though just-bash calls them portable: each
-* regresses a real, already-passing test elsewhere in this monorepo when
-* dispatched through this package's fork-command wrapping specifically
-* (isolated just-bash unit tests for these same commands pass fine, so the
-* break is in how @demicodes/shell wraps them, not in just-bash itself):
+* Deliberately routed to real OS processes (Host.process.spawn) even though
+* just-bash ships portable versions. This is a semantics decision, not a
+* missing feature:
 *
-* - `bash`, `sh`: nested "run a script string through the interpreter again".
-*   Their stdout never reaches the caller here — `sh -c "printf hi"` and
-*   `bash -c "echo hi"` both exit 0 with empty output, while the exact same
-*   scripts run un-nested work fine. This package's own `AgentServer` test
-*   spawns `sh -c` for real and asserts on the real output.
-* - `sleep`: just-bash's version is a plain timer, not a real backgroundable,
-*   abortable OS process. This package's own environment tests use `sleep 10`
-*   specifically as a long-running foreground process to exercise abort/
-*   timeout handling (`env.abort()` / status-while-`running`), which needs a
-*   real process to abort.
-*
-* Keeping these three off the list preserves their pre-existing
-* fall-through to Host.process.spawn, same as before this list started
-* tracking just-bash's registry.
+* - `bash`, `sh`: scripts in real repositories expect a real interpreter
+*   (full bash semantics, real coreutils, real subprocess behavior). Routing
+*   them into just-bash's simulated interpreter would silently downgrade
+*   every `bash script.sh` a model runs. (The fork's nested-interpreter
+*   stdout also does not forward through this package's wrapping — but even
+*   with that fixed, real spawn stays the right routing.)
+* - `sleep`: must be a real, abortable OS process so foreground abort and
+*   timeout semantics (`env.abort()` while `running`) genuinely interrupt
+*   it; just-bash's version is a plain in-process timer.
 */
 const REAL_SPAWN_DEPENDENT_COMMANDS = /* @__PURE__ */ new Set([
 	"bash",
@@ -115,6 +108,12 @@ const RESERVED_COMMAND_NAMES = /* @__PURE__ */ new Set([
 ]);
 //#endregion
 //#region src/command.ts
+function emptyStdin() {
+	return {
+		text: "",
+		bytes: /* @__PURE__ */ new Uint8Array(0)
+	};
+}
 const EXECUTION_ONLY_FIELDS = [
 	"effects",
 	"successOutput",
@@ -122,9 +121,9 @@ const EXECUTION_ONLY_FIELDS = [
 	"input",
 	"positionals",
 	"stdinField",
-	"output",
-	"examples"
+	"output"
 ];
+const COMMAND_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 var CommandRegistry = class {
 	commands = /* @__PURE__ */ new Map();
 	register(command) {
@@ -139,14 +138,14 @@ var CommandRegistry = class {
 	list() {
 		return [...this.commands.values()];
 	}
-	renderPrompt() {
-		const rendered = this.list().map((command) => renderCommandPrompt(command)).join("\n\n");
+	renderHelp() {
+		const rendered = this.list().map((command) => renderCommandHelp(command)).join("\n\n");
 		if (!rendered) return rendered;
-		return `${COMMAND_PROMPT_DEFAULTS}\n\n${rendered}`;
+		return `${COMMAND_HELP_DEFAULTS}\n\n${rendered}`;
 	}
 };
-const COMMAND_PROMPT_DEFAULTS = "Unless a command states otherwise: success prints raw text on stdout, failure writes an error message to stderr and exits non-zero.";
-function parseCommandInput(root, argv, stdin = { text: "" }) {
+const COMMAND_HELP_DEFAULTS = "Unless a command states otherwise: success prints raw text on stdout, failure writes an error message to stderr and exits non-zero. Pass --help at any level to print a command's documentation.";
+function parseCommandInput(root, argv, stdin = emptyStdin()) {
 	if (argv[0] !== root.name) throw new Error(`Expected command "${root.name}", received "${argv[0] ?? ""}"`);
 	let node = root;
 	const path = [root.name];
@@ -157,7 +156,7 @@ function parseCommandInput(root, argv, stdin = { text: "" }) {
 			throw new Error(`Command "${path.join(" ")}" requires a subcommand`);
 		}
 		const token = argv[index];
-		if (token === "prompt") return {
+		if (token === "--help") return {
 			path: [...path],
 			help: true,
 			values: {},
@@ -182,6 +181,12 @@ function parseArgs(command, path, argv, startIndex, stdin) {
 	let positionalIndex = 0;
 	for (let i = startIndex; i < argv.length; i += 1) {
 		const token = argv[i];
+		if (token === "--help") return {
+			path: [...path],
+			help: true,
+			values: {},
+			json: false
+		};
 		if (token === "--json") {
 			json = true;
 			continue;
@@ -223,13 +228,13 @@ function resolveCommand(root, path) {
 	return node;
 }
 async function runRegisteredCommand(root, ctx) {
-	const stdin = ctx.stdin ?? { text: "" };
+	const stdin = ctx.stdin ?? emptyStdin();
 	const parsed = parseCommandInput(root, ctx.argv, stdin);
 	const displayPath = parsed.path.join(" ");
 	if (parsed.help) {
 		const node = resolveCommand(root, parsed.path);
 		const parentPath = parsed.path.length > 1 ? parsed.path.slice(0, -1).join(" ") : "";
-		await ctx.io.stdout(`${renderCommandPrompt(node, parentPath)}\n`);
+		await ctx.io.stdout(`${renderCommandHelp(node, parentPath)}\n`);
 		return { exitCode: 0 };
 	}
 	const command = resolveCommand(root, parsed.path);
@@ -243,7 +248,8 @@ async function runRegisteredCommand(root, ctx) {
 		env: ctx.env,
 		cwd: ctx.cwd,
 		io: parsed.json ? capture : ctx.io,
-		storage: ctx.storage
+		storage: ctx.storage,
+		host: ctx.host
 	});
 	if (parsed.json && result.exitCode === 0) {
 		const raw = capture.stdoutText();
@@ -262,7 +268,7 @@ async function runRegisteredCommand(root, ctx) {
 	}
 	return result;
 }
-function renderCommandPrompt(command, parentPath = "") {
+function renderCommandHelp(command, parentPath = "") {
 	const path = parentPath ? `${parentPath} ${command.name}` : command.name;
 	const blocks = [];
 	const lines = [`${path}: ${command.summary}`];
@@ -285,11 +291,6 @@ function renderCommandPrompt(command, parentPath = "") {
 		if (command.stdinField) lines.push(`    stdin/heredoc: ${command.stdinField}`);
 		if (command.output?.json) lines.push("    --json: emits machine-readable JSON for this command");
 		else lines.push("    --json: accepted only when this command defines JSON output");
-		const examples = command.examples ?? [];
-		if (examples.length > 0) {
-			lines.push("    Examples:");
-			for (const example of examples) lines.push(indent(example, 6));
-		}
 	}
 	const children = command.subcommands ?? [];
 	if (children.length > 0) {
@@ -297,16 +298,17 @@ function renderCommandPrompt(command, parentPath = "") {
 		for (const child of children) lines.push(`  ${path} ${child.name} — ${child.summary}`);
 	}
 	blocks.push(lines.join("\n"));
-	for (const child of children) blocks.push(renderCommandPrompt(child, path));
+	for (const child of children) blocks.push(renderCommandHelp(child, path));
 	return blocks.join("\n\n");
 }
 function validateCommandTree(command, path) {
+	if (!COMMAND_NAME_PATTERN.test(command.name)) throw new Error(`CommandRegistry: "${path}" has invalid name "${command.name}"; use letters, numbers, underscores, and hyphens`);
 	const hasRun = typeof command.run === "function";
 	const children = command.subcommands ?? [];
 	if (!hasRun && children.length === 0) throw new Error(`CommandRegistry: "${path}" must have run() and/or subcommands`);
-	if (hasRun) {
-		if (!Array.isArray(command.examples)) throw new Error(`CommandRegistry: "${path}" defines run() but is missing examples[]`);
-	} else for (const field of EXECUTION_ONLY_FIELDS) if (command[field] !== void 0) throw new Error(`CommandRegistry: "${path}" sets ${field} without run()`);
+	if (!hasRun) {
+		for (const field of EXECUTION_ONLY_FIELDS) if (command[field] !== void 0) throw new Error(`CommandRegistry: "${path}" sets ${field} without run()`);
+	}
 	if (hasRun) {
 		const input = command.input ?? {};
 		if (command.stdinField && !(command.stdinField in input)) throw new Error(`CommandRegistry: "${path}" stdinField "${command.stdinField}" is not in input`);
@@ -314,7 +316,6 @@ function validateCommandTree(command, path) {
 	}
 	const seen = /* @__PURE__ */ new Set();
 	for (const child of children) {
-		if (child.name === "prompt") throw new Error(`CommandRegistry: "${path} prompt" is reserved for the help pseudo-subcommand`);
 		if (seen.has(child.name)) throw new Error(`CommandRegistry: duplicate subcommand "${path} ${child.name}"`);
 		seen.add(child.name);
 		validateCommandTree(child, `${path} ${child.name}`);
@@ -357,10 +358,6 @@ function coerceValue(schema, value) {
 function formatField(field, schema, positional, stdin) {
 	return `${positional ? `<${field}>` : `--${field}`}${stdin ? " (from stdin/heredoc)" : ""}${schema.description ? ` - ${schema.description}` : ""}`;
 }
-function indent(text, spaces) {
-	const prefix = " ".repeat(spaces);
-	return text.split("\n").map((line) => `${prefix}${line}`).join("\n");
-}
 function isArraySchema(schema) {
 	const unwrapped = unwrapSchema(schema);
 	return zodTypeName(unwrapped) === "array" || zodTypeName(unwrapped) === "ZodArray";
@@ -398,9 +395,6 @@ var CapturingIO = class {
 	async stderr(data) {
 		await this.target.stderr(data);
 	}
-	async asset(asset) {
-		await this.target.asset(asset);
-	}
 	stdoutText() {
 		return decodeUtf8(concatBytes(this.chunks));
 	}
@@ -512,8 +506,10 @@ function createOutputSinks(fs, cwd, redirections) {
 function recordForegroundChunk(foreground, sourceFd, chunk) {
 	const text = decodeUtf8(chunk);
 	foreground.lastOutputAt = Date.now();
-	if (sourceFd === 1) foreground.rawStdoutBuffer += text;
-	else foreground.rawStderrBuffer += text;
+	if (sourceFd === 1) {
+		foreground.rawStdoutBuffer += text;
+		foreground.rawStdoutBytes.push(chunk);
+	} else foreground.rawStderrBuffer += text;
 	const sink = foreground.outputSinks[sourceFd];
 	if (sink.kind === "file" || sink.kind === "null") {
 		sink.bytes.push(chunk);
@@ -615,62 +611,63 @@ function appendVisibleChunk(foreground, targetFd, text, byteLength) {
 //#endregion
 //#region src/command-artifact-store.ts
 /**
-* Owns persistence of shell command artifacts: a per-scope storage cache plus the
+* Owns persistence of shell command artifacts: a per-storage-id cache plus the
 * set of released (tombstoned) commands. `BashEnvironment` delegates the storage
 * and release-tracking side of the `/@` virtual filesystem here, keeping only the
 * in-memory record lookups that need live command state.
 */
 var CommandArtifactStore = class {
 	store;
-	storageByScope = /* @__PURE__ */ new Map();
+	storageById = /* @__PURE__ */ new Map();
 	released = /* @__PURE__ */ new Set();
 	constructor(store) {
 		this.store = store;
 	}
-	/** The artifact storage for a command scope, created (and cached) on first use. */
-	storageFor(scopeId) {
-		const existing = this.storageByScope.get(scopeId);
+	/** The artifact storage for one agent session or anonymous shell. */
+	storageFor(commandStorageId) {
+		const existing = this.storageById.get(commandStorageId);
 		if (existing) return existing;
-		const storage = new AgentSessionCommandStorage(this.store, scopeId);
-		this.storageByScope.set(scopeId, storage);
+		const storage = new AgentSessionCommandStorage(this.store, commandStorageId);
+		this.storageById.set(commandStorageId, storage);
 		return storage;
 	}
 	/** Whether a command's artifact has been released (tombstoned). */
-	isReleased(scopeId, commandId) {
-		return this.released.has(this.key(scopeId, commandId));
+	isReleased(commandStorageId, commandId) {
+		return this.released.has(this.key(commandStorageId, commandId));
 	}
 	/** Persists an artifact unless its command has already been released. */
-	persist(scopeId, commandId, artifact) {
-		if (this.isReleased(scopeId, commandId)) return;
-		this.storageFor(scopeId).writeJson(`commands/${commandId}/artifact.json`, artifact).catch(() => {});
+	persist(commandStorageId, commandId, artifact) {
+		if (this.isReleased(commandStorageId, commandId)) return;
+		this.storageFor(commandStorageId).writeJson(`commands/${commandId}/artifact.json`, artifact).catch(() => {});
 	}
 	/** Tombstones a command and removes its persisted artifact. */
-	async release(scopeId, commandId) {
-		this.released.add(this.key(scopeId, commandId));
-		await this.storageFor(scopeId).delete(`commands/${commandId}/artifact.json`).catch(() => {});
+	async release(commandStorageId, commandId) {
+		this.released.add(this.key(commandStorageId, commandId));
+		await this.storageFor(commandStorageId).delete(`commands/${commandId}/artifact.json`).catch(() => {});
 	}
-	key(scopeId, commandId) {
-		return `${scopeId}\0${commandId}`;
+	key(commandStorageId, commandId) {
+		return `${commandStorageId}\0${commandId}`;
 	}
 };
 //#endregion
 //#region src/registered-command-adapter.ts
-function commandToForkCommand(session, command, storage) {
+function commandToForkCommand(session, command, storage, host) {
 	return {
 		name: command.name,
 		consumesStdin: treeConsumesStdin(command),
 		execute: async (args, ctx) => {
-			const stdinText = decodeForkStdin(ctx.stdin);
+			const stdin = decodeForkStdin(ctx.stdin);
 			const io = createForwardingIO();
 			const argv = [command.name, ...args];
 			try {
 				const result = await runRegisteredCommand(command, {
 					argv,
-					stdin: { text: stdinText },
+					stdin,
 					env: mapToRecord(ctx.env),
 					cwd: ctx.cwd,
 					io,
-					storage
+					storage,
+					host
 				});
 				session.accumulator.audit.push({
 					kind: "registered-command",
@@ -685,7 +682,8 @@ function commandToForkCommand(session, command, storage) {
 					metadata: result.metadata
 				});
 				return {
-					stdout: io.stdoutText(),
+					stdout: io.stdoutLatin1(),
+					stdoutKind: "bytes",
 					stderr: io.stderrText(),
 					exitCode: result.exitCode
 				};
@@ -698,38 +696,31 @@ function commandToForkCommand(session, command, storage) {
 					exitCode: 1
 				});
 				return {
-					stdout: io.stdoutText(),
+					stdout: io.stdoutLatin1(),
+					stdoutKind: "bytes",
 					stderr: `${io.stderrText()}${command.name}: ${message}\n`,
 					exitCode: 1
 				};
-			} finally {
-				if (io.assets().length > 0) session.accumulator.assets.push(...io.assets());
 			}
 		}
 	};
 }
+/** Collects command output as raw bytes; stdout stays byte-clean for the pipe. */
 var ForwardingIO = class {
 	stdoutChunks = [];
 	stderrChunks = [];
-	assetItems = [];
 	async stdout(data) {
 		this.stdoutChunks.push(typeof data === "string" ? encodeUtf8(data) : data);
 	}
 	async stderr(data) {
 		this.stderrChunks.push(typeof data === "string" ? encodeUtf8(data) : data);
 	}
-	asset(asset) {
-		this.assetItems.push(asset);
-	}
-	stdoutText() {
-		return decodeUtf8(concatBytes(this.stdoutChunks));
+	stdoutLatin1() {
+		return decodeLatin1(concatBytes(this.stdoutChunks));
 	}
 	stderrText() {
 		return decodeUtf8(concatBytes(this.stderrChunks));
 	}
-	assets() {
-		return this.assetItems;
-	}
 };
 function createForwardingIO() {
 	return new ForwardingIO();
@@ -743,26 +734,52 @@ function mapToRecord(map) {
 	for (const [key, value] of map) record[key] = value;
 	return record;
 }
+/** Pipes hand stdin over as a latin1-packed byte string; expose bytes and a UTF-8 text view. */
 function decodeForkStdin(stdin) {
-	if (!stdin) return "";
-	if (stdin instanceof Uint8Array) return decodeUtf8(stdin);
+	if (!stdin) return {
+		text: "",
+		bytes: /* @__PURE__ */ new Uint8Array(0)
+	};
+	if (stdin instanceof Uint8Array) return {
+		text: decodeUtf8(stdin),
+		bytes: stdin
+	};
 	const latin1 = stdin;
-	if (!latin1) return "";
+	if (!latin1) return {
+		text: "",
+		bytes: /* @__PURE__ */ new Uint8Array(0)
+	};
+	const bytes = encodeLatin1(latin1);
 	let hasHighByte = false;
+	let hasWideChar = false;
 	for (let i = 0; i < latin1.length; i += 1) {
 		const code = latin1.charCodeAt(i);
-		if (code > 255) return latin1;
-		if (code > 127) hasHighByte = true;
+		if (code > 255) hasWideChar = true;
+		else if (code > 127) hasHighByte = true;
 	}
-	if (!hasHighByte) return latin1;
-	const bytes = new Uint8Array(latin1.length);
-	for (let i = 0; i < latin1.length; i += 1) bytes[i] = latin1.charCodeAt(i);
-	return decodeUtf8(bytes);
+	if (hasWideChar) return {
+		text: latin1,
+		bytes: encodeUtf8(latin1)
+	};
+	if (!hasHighByte) return {
+		text: latin1,
+		bytes
+	};
+	return {
+		text: decodeUtf8(bytes),
+		bytes
+	};
 }
 //#endregion
 //#region src/environment.ts
 const DEFAULT_TIMEOUT_MS = 1e4;
-const DEFAULT_OUTPUT_LIMIT_BYTES = 1024 * 1024;
+const DEFAULT_OUTPUT_LIMIT_BYTES = 1048576;
+/**
+* Ceiling for a raw-byte final stream. Sized so an ordinary viewing-grade clip
+* survives the shell and reaches the layer that decides what to do with it,
+* while still bounding a runaway producer.
+*/
+const DEFAULT_BINARY_LIMIT_BYTES = 16777216;
 /** Upper bound for a single exec observation window (also the command-bridge wait ceiling). */
 const MAX_TIMEOUT_MS = 6e5;
 var BashEnvironment = class {
@@ -771,8 +788,8 @@ var BashEnvironment = class {
 	shellIdFactory;
 	commandIdFactory;
 	initialEnv;
-	execEnv;
 	defaultOutputLimitBytes;
+	defaultBinaryLimitBytes;
 	shells = /* @__PURE__ */ new Map();
 	defaultShellByAgentSessionId = /* @__PURE__ */ new Map();
 	commandsById = /* @__PURE__ */ new Map();
@@ -784,12 +801,15 @@ var BashEnvironment = class {
 		this.shellIdFactory = options.shellIdFactory ?? (() => globalThis.crypto.randomUUID());
 		this.commandIdFactory = options.commandIdFactory ?? (() => globalThis.crypto.randomUUID());
 		this.initialEnv = options.initialEnv ?? {};
-		this.execEnv = options.execEnv;
 		this.defaultOutputLimitBytes = options.maxOutputBytes ?? DEFAULT_OUTPUT_LIMIT_BYTES;
+		this.defaultBinaryLimitBytes = options.maxBinaryBytes ?? DEFAULT_BINARY_LIMIT_BYTES;
 	}
 	getShell(shellId) {
 		return this.shells.get(shellId) ?? null;
 	}
+	hasCommand(commandId) {
+		return this.commandsById.has(commandId);
+	}
 	registerCommand(command) {
 		if (this.commands.get(command.name)) return;
 		this.commands.register(command);
@@ -799,20 +819,13 @@ var BashEnvironment = class {
 	}
 	async exec(input) {
 		const timeoutMs = normalizeTimeoutMs(input.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-		const session = input.shellId ? this.requireShell(input.shellId) : this.availableDefaultShell(input.agentSessionId);
-		if (session.exited) throw new Error(`Shell session "${session.id}" has exited`);
-		if (input.agentSessionId) {
-			session.state.env.set("DEMI_AGENT_SESSION_ID", input.agentSessionId);
-			const extraEnv = this.execEnv?.(input.agentSessionId);
-			if (extraEnv) {
-				const exported = session.state.exportedVars ?? /* @__PURE__ */ new Set();
-				session.state.exportedVars = exported;
-				for (const [key, value] of Object.entries(extraEnv)) {
-					session.state.env.set(key, value);
-					exported.add(key);
-				}
-			}
+		if (input.shellId && input.ephemeral) throw new Error("ShellExecInput: \"shellId\" and \"ephemeral\" are mutually exclusive");
+		if (input.cwd !== void 0 && !input.ephemeral) throw new Error("ShellExecInput: \"cwd\" requires \"ephemeral\"; a persistent shell owns its cwd");
+		if (input.cwd !== void 0) {
+			if (!(await this.host.fs.stat(input.cwd).catch(() => null))?.isDirectory) throw new Error(`Shell exec cwd is not a directory: ${input.cwd}`);
 		}
+		const session = input.shellId ? this.requireShell(input.shellId) : input.ephemeral ? this.createShell(input.agentSessionId, input.cwd) : this.availableDefaultShell(input.agentSessionId);
+		if (session.exited) throw new Error(`Shell session "${session.id}" has exited`);
 		if (session.pendingExec || session.foreground) {
 			const commandId = session.activeCommandId ?? session.foreground?.commandId ?? "unknown";
 			throw new Error(`Shell session "${session.id}" is already running command "${commandId}"`);
@@ -824,7 +837,7 @@ var BashEnvironment = class {
 	}
 	async status(input) {
 		const record = this.requireCommand(input.commandId);
-		return this.snapshotCommand(record, input);
+		return this.commandStatus(record, input);
 	}
 	async write(input) {
 		const record = this.requireCommand(input.commandId);
@@ -834,11 +847,11 @@ var BashEnvironment = class {
 		const data = typeof input.stdin === "string" ? encodeUtf8(input.stdin) : input.stdin;
 		if (data.byteLength === 0) throw new Error("shell_write field \"stdin\" must not be empty; use shell_status to poll");
 		await foreground.handle.writeStdin(data);
-		return this.snapshotCommand(record, input);
+		return this.commandStatus(record, input);
 	}
 	async abort(input) {
 		const record = this.requireCommand(input.commandId);
-		if (record.status !== "running") return this.snapshotCommand(record, input);
+		if (record.status !== "running") return this.commandStatus(record, input);
 		const session = this.requireShell(record.shellId);
 		const foreground = this.requireForegroundCommand(session, record.id);
 		foreground.abortController.abort();
@@ -850,7 +863,7 @@ var BashEnvironment = class {
 		const record = this.commandsById.get(commandId);
 		if (!record || record.status === "running") return false;
 		this.commandsById.delete(commandId);
-		await this.artifacts.release(record.commandScopeId, commandId);
+		await this.artifacts.release(record.commandStorageId, commandId);
 		return true;
 	}
 	async disposeShell(shellId) {
@@ -916,25 +929,22 @@ var BashEnvironment = class {
 		if (!agentSessionId || shell.exited || !shell.pendingExec && !shell.foreground) return shell;
 		return this.createShell(agentSessionId);
 	}
-	createShell(agentSessionId) {
+	createShell(agentSessionId, initialCwd) {
 		const id = this.shellIdFactory();
-		const commandScopeId = agentSessionId ?? id;
-		const cwd = this.host.defaultCwd;
-		const fs = new HostBackedFileSystem(this.host, { lookup: (path) => this.lookupVirtualArtifact(commandScopeId, path) });
+		const commandStorageId = agentSessionId ?? id;
+		const cwd = initialCwd ?? this.host.defaultCwd;
+		const fs = new HostBackedFileSystem(this.host, { lookup: (path) => this.lookupVirtualArtifact(commandStorageId, path) });
 		const env = /* @__PURE__ */ new Map();
 		for (const [key, value] of Object.entries(this.initialEnv)) env.set(key, value);
 		env.set("PWD", cwd);
-		env.set("DEMI_SESSION_ID", commandScopeId);
+		if (agentSessionId) env.set("DEMI_SESSION_ID", agentSessionId);
 		env.set("DEMI_SHELL_ID", id);
 		if (!env.has("IFS")) env.set("IFS", " 	\n");
 		if (!env.has("PS1")) env.set("PS1", "");
 		if (!env.has("PS2")) env.set("PS2", "> ");
 		if (!env.has("SHLVL")) env.set("SHLVL", "1");
-		const exportedVars = /* @__PURE__ */ new Set([
-			"PWD",
-			"DEMI_SESSION_ID",
-			"DEMI_SHELL_ID"
-		]);
+		const exportedVars = /* @__PURE__ */ new Set(["PWD", "DEMI_SHELL_ID"]);
+		if (agentSessionId) exportedVars.add("DEMI_SESSION_ID");
 		for (const key of env.keys()) if (key !== key.toLowerCase()) exportedVars.add(key);
 		for (const key of Object.keys(this.initialEnv)) exportedVars.add(key);
 		const state = {
@@ -995,7 +1005,8 @@ var BashEnvironment = class {
 		const forkCommands = /* @__PURE__ */ new Map();
 		const session = {
 			id,
-			commandScopeId,
+			agentSessionId: agentSessionId ?? null,
+			commandStorageId,
 			state,
 			fs,
 			interpreter: void 0,
@@ -1004,8 +1015,7 @@ var BashEnvironment = class {
 				stdout: "",
 				stderr: "",
 				audit: [],
-				commandMetadata: [],
-				assets: []
+				commandMetadata: []
 			},
 			foregroundWaiters: /* @__PURE__ */ new Set(),
 			backgroundJobs: /* @__PURE__ */ new Map(),
@@ -1013,19 +1023,20 @@ var BashEnvironment = class {
 			exited: false
 		};
 		for (const command of createPortableCommands(session)) forkCommands.set(command.name, command);
-		const storage = new AgentSessionCommandStorage(this.host.store, commandScopeId);
-		for (const command of this.commands.list()) forkCommands.set(command.name, commandToForkCommand(session, command, storage));
+		const storage = new AgentSessionCommandStorage(this.host.store, commandStorageId);
+		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,
+			maxCommandCount: 1e6,
+			maxLoopIterations: 1e6,
+			maxCallDepth: 1e3,
+			maxGlobOperations: 1e6
+		});
 		session.interpreter = new Interpreter({
 			fs,
 			commands: forkCommands,
-			limits: resolveLimits({
-				maxOutputSize: 1024 * 1024 * 1024,
-				maxCommandCount: 1e6,
-				maxLoopIterations: 1e6,
-				maxCallDepth: 1e3,
-				maxGlobOperations: 1e6
-			}),
+			limits,
 			exec: async () => ({
 				stdout: "",
 				stderr: "",
@@ -1044,6 +1055,7 @@ var BashEnvironment = class {
 	}
 	async runScript(session, script, input) {
 		const record = this.createCommandRecord(session, script);
+		record.outputLimitBytes = input.maxOutputBytes ?? this.defaultOutputLimitBytes;
 		let ast;
 		try {
 			ast = parse(script);
@@ -1055,7 +1067,7 @@ var BashEnvironment = class {
 				record.exitCode = 2;
 				session.state.lastExitCode = 2;
 				session.activeCommandId = void 0;
-				return this.snapshotCommand(record, input);
+				return this.commandStatus(record, input);
 			}
 			throw error;
 		}
@@ -1063,8 +1075,7 @@ var BashEnvironment = class {
 			stdout: "",
 			stderr: "",
 			audit: [],
-			commandMetadata: [],
-			assets: []
+			commandMetadata: []
 		};
 		session.abortController = new AbortController();
 		session.activeCommandId = record.id;
@@ -1087,7 +1098,7 @@ var BashEnvironment = class {
 		const record = {
 			id,
 			shellId: session.id,
-			commandScopeId: session.commandScopeId,
+			commandStorageId: session.commandStorageId,
 			script,
 			startedAt: now,
 			lastOutputAt: now,
@@ -1100,7 +1111,7 @@ var BashEnvironment = class {
 			outputOffset: 0,
 			audit: [],
 			commandMetadata: [],
-			assets: []
+			outputLimitBytes: this.defaultOutputLimitBytes
 		};
 		this.commandsById.set(id, record);
 		return record;
@@ -1221,7 +1232,7 @@ var BashEnvironment = class {
 				foreground = outcome.foreground;
 				continue;
 			}
-			if (outcome.kind === "timeout") return this.snapshotCommand(record, input);
+			if (outcome.kind === "timeout") return this.commandStatus(record, input);
 			if (outcome.kind === "aborted") {
 				const activeForeground = foreground ?? session.foreground;
 				if (!activeForeground) return this.collectAbortedWithoutForeground(session, record, input);
@@ -1306,6 +1317,7 @@ var BashEnvironment = class {
 			startedAt,
 			lastOutputAt: startedAt,
 			rawStdoutBuffer: "",
+			rawStdoutBytes: [],
 			rawStderrBuffer: "",
 			stdoutBuffer: "",
 			stderrBuffer: "",
@@ -1326,7 +1338,7 @@ var BashEnvironment = class {
 		};
 		session.foreground = foreground;
 		notifyForegroundWaiters(session.foregroundWaiters, foreground);
-		if (opts.stdin && opts.stdin.length > 0) await handle.writeStdin(encodeUtf8(opts.stdin));
+		if (opts.stdin && opts.stdin.length > 0) await handle.writeStdin(encodeLatin1(opts.stdin));
 		if (opts.stdinProvided) await handle.closeStdin();
 		if (handle.output) {
 			foreground.stdoutPump = pumpOutputStream(handle.output, (chunk) => {
@@ -1339,7 +1351,7 @@ var BashEnvironment = class {
 		}
 		const exit = await foreground.exitPromise;
 		await Promise.allSettled([foreground.stdoutPump, foreground.stderrPump]);
-		const stdout = foreground.rawStdoutBuffer;
+		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;
 		foreground.audit[0] = {
@@ -1360,12 +1372,13 @@ var BashEnvironment = class {
 		session.foreground = void 0;
 		return {
 			stdout,
+			stdoutKind: "bytes",
 			stderr,
 			exitCode
 		};
 	}
 	collectExited(session, record, resultOrError, foreground, input = {}) {
-		if (record.status !== "running") return this.snapshotCommand(record, input);
+		if (record.status !== "running") return this.commandStatus(record, input);
 		if (resultOrError instanceof Error) {
 			if (resultOrError instanceof ExitError) {
 				session.exited = true;
@@ -1403,12 +1416,36 @@ var BashEnvironment = class {
 			appendRecordOutput(record, "stderr", text);
 			return this.finishExited(session, record, 1, input);
 		}
-		const stdoutText = foreground ? resultOrError.stdout : decodeBytesToUtf8(unsafeBytesFromLatin1(resultOrError.stdout));
+		const raw = resultOrError.stdout;
+		let stdoutText;
+		let binary;
+		if (hasWideChar(raw)) stdoutText = raw;
+		else {
+			const bytes = encodeLatin1(raw);
+			const strict = decodeUtf8Strict(bytes);
+			if (strict !== null) stdoutText = strict;
+			else {
+				const cap = this.defaultBinaryLimitBytes;
+				const truncated = bytes.length > cap;
+				binary = {
+					data: truncated ? bytes.slice(0, cap) : bytes,
+					truncated,
+					totalBytes: bytes.length,
+					limitBytes: cap
+				};
+				stdoutText = `<binary stdout: ${bytes.length} bytes${truncated ? `, exceeds the ${cap}-byte binary limit` : ""}; raw bytes at /@/commands/${record.id}/stdout.bin>\n`;
+			}
+		}
 		const stderrText = foreground ? resultOrError.stderr : decodeBytesToUtf8(unsafeBytesFromLatin1(resultOrError.stderr));
 		session.accumulator.stdout += stdoutText;
 		session.accumulator.stderr += stderrText;
-		if (foreground) record.outputChunks = [...foreground.outputChunks];
-		else if (record.outputChunks.length === 0) {
+		if (binary) record.binaryStdout = binary;
+		if (foreground && !binary) record.outputChunks = [...foreground.outputChunks];
+		else if (binary) {
+			record.outputChunks = [];
+			appendRecordOutput(record, "stdout", stdoutText);
+			appendRecordOutput(record, "stderr", stderrText);
+		} else if (record.outputChunks.length === 0) {
 			appendRecordOutput(record, "stdout", stdoutText);
 			appendRecordOutput(record, "stderr", stderrText);
 		}
@@ -1427,13 +1464,12 @@ var BashEnvironment = class {
 		record.exitCode = exitCode;
 		record.audit = [...session.accumulator.audit];
 		record.commandMetadata = [...session.accumulator.commandMetadata];
-		record.assets = [...session.accumulator.assets];
 		session.pendingExec = void 0;
 		if (session.activeCommandId === record.id) session.activeCommandId = void 0;
-		return this.snapshotCommand(record, input);
+		return this.commandStatus(record, input);
 	}
 	async collectAborted(session, record, foreground, input = {}) {
-		if (record.status !== "running") return this.snapshotCommand(record, input);
+		if (record.status !== "running") return this.commandStatus(record, input);
 		foreground.abortController.abort();
 		foreground.handle.kill("SIGTERM").catch(() => {});
 		await flushForegroundSinks(session, foreground);
@@ -1445,10 +1481,10 @@ var BashEnvironment = class {
 		session.foreground = void 0;
 		session.pendingExec = void 0;
 		if (session.activeCommandId === record.id) session.activeCommandId = void 0;
-		return this.snapshotCommand(record, input);
+		return this.commandStatus(record, input);
 	}
 	collectAbortedWithoutForeground(session, record, input = {}) {
-		if (record.status !== "running") return this.snapshotCommand(record, input);
+		if (record.status !== "running") return this.commandStatus(record, input);
 		session.abortController?.abort();
 		session.pendingExec = void 0;
 		if (session.activeCommandId === record.id) session.activeCommandId = void 0;
@@ -1460,9 +1496,9 @@ var BashEnvironment = class {
 		}
 		record.lastOutputAt = Date.now();
 		record.status = "aborted";
-		return this.snapshotCommand(record, input);
+		return this.commandStatus(record, input);
 	}
-	snapshotCommand(record, input = {}) {
+	commandStatus(record, input = {}) {
 		const foreground = this.shells.get(record.shellId)?.foreground;
 		if (record.status === "running" && foreground?.commandId === record.id) {
 			record.stdout = foreground.stdoutBuffer;
@@ -1471,9 +1507,9 @@ var BashEnvironment = class {
 			record.lastOutputAt = foreground.lastOutputAt;
 		}
 		const maxOutputBytes = input.maxOutputBytes ?? this.defaultOutputLimitBytes;
-		const stdout = streamArtifact(record, "stdout", input.stdoutOffset, maxOutputBytes);
-		const stderr = streamArtifact(record, "stderr", input.stderrOffset, maxOutputBytes);
-		const output = streamOutputArtifact(record, input.outputOffset, maxOutputBytes);
+		const stdout = streamView(record, "stdout", input.stdoutOffset, maxOutputBytes);
+		const stderr = streamView(record, "stderr", input.stderrOffset, maxOutputBytes);
+		const output = mergedOutputView(record, input.outputOffset, maxOutputBytes);
 		const base = {
 			shellId: record.shellId,
 			commandId: record.id,
@@ -1492,7 +1528,7 @@ var BashEnvironment = class {
 				audit: record.audit
 			};
 			if (record.commandMetadata.length > 0) result.commandMetadata = record.commandMetadata;
-			if (record.assets.length > 0) result.assets = record.assets;
+			if (record.binaryStdout) result.binaryStdout = record.binaryStdout;
 			return result;
 		}
 		if (record.status === "aborted") return {
@@ -1504,52 +1540,56 @@ var BashEnvironment = class {
 			status: "running"
 		};
 	}
-	async lookupVirtualArtifact(scopeId, path) {
+	async lookupVirtualArtifact(commandStorageId, path) {
 		const parts = path.split("/").filter(Boolean);
 		if (parts.length === 1 && parts[0] === "@") return virtualDirectory(["commands"]);
-		if (parts.length === 2 && parts[0] === "@" && parts[1] === "commands") return virtualDirectory(await this.commandArtifactIds(scopeId));
+		if (parts.length === 2 && parts[0] === "@" && parts[1] === "commands") return virtualDirectory(await this.commandArtifactIds(commandStorageId));
 		if (parts.length === 3 && parts[0] === "@" && parts[1] === "commands") {
-			if (!await this.commandArtifact(scopeId, parts[2])) return null;
-			return virtualDirectory([
+			const artifact = await this.commandArtifact(commandStorageId, parts[2]);
+			if (!artifact) return null;
+			const entries = [
 				"meta.json",
 				"stderr.txt",
 				"stdout.txt"
-			]);
+			];
+			if (artifact.stdoutBinary) entries.push("stdout.bin");
+			return virtualDirectory(entries);
 		}
 		if (parts.length !== 4 || parts[0] !== "@" || parts[1] !== "commands") return null;
-		const artifact = await this.commandArtifact(scopeId, parts[2]);
+		const artifact = await this.commandArtifact(commandStorageId, parts[2]);
 		if (!artifact) return null;
 		const fileName = parts[3];
 		if (fileName === "stdout.txt") return virtualFile(encodeUtf8(artifact.stdout));
+		if (fileName === "stdout.bin" && artifact.stdoutBinary) return virtualFile(base64ToBytes(artifact.stdoutBinary.base64));
 		if (fileName === "stderr.txt") return virtualFile(encodeUtf8(artifact.stderr));
 		if (fileName === "meta.json") return virtualFile(encodeUtf8(`${JSON.stringify(commandArtifactMeta(artifact), null, 2)}\n`));
 		return null;
 	}
-	async commandArtifactIds(scopeId) {
+	async commandArtifactIds(commandStorageId) {
 		const ids = /* @__PURE__ */ new Set();
-		for (const record of this.commandsById.values()) if (record.commandScopeId === scopeId && !this.artifacts.isReleased(scopeId, record.id)) ids.add(record.id);
-		const keys = await this.artifacts.storageFor(scopeId).list("commands").catch(() => []);
+		for (const record of this.commandsById.values()) if (record.commandStorageId === commandStorageId && !this.artifacts.isReleased(commandStorageId, record.id)) ids.add(record.id);
+		const keys = await this.artifacts.storageFor(commandStorageId).list("commands").catch(() => []);
 		for (const key of keys) {
 			const match = /^commands\/([^/]+)\/artifact\.json$/.exec(key);
-			if (match && !this.artifacts.isReleased(scopeId, match[1])) ids.add(match[1]);
+			if (match && !this.artifacts.isReleased(commandStorageId, match[1])) ids.add(match[1]);
 		}
 		return [...ids];
 	}
-	async commandArtifact(scopeId, commandId) {
-		if (this.artifacts.isReleased(scopeId, commandId)) return null;
+	async commandArtifact(commandStorageId, commandId) {
+		if (this.artifacts.isReleased(commandStorageId, commandId)) return null;
 		const record = this.commandsById.get(commandId);
-		if (record?.commandScopeId === scopeId) {
+		if (record?.commandStorageId === commandStorageId) {
 			this.syncRunningRecord(record);
-			return persistedArtifactFromRecord(record);
+			return commandArtifactFromRecord(record);
 		}
-		const value = await this.artifacts.storageFor(scopeId).readJson(`commands/${commandId}/artifact.json`).catch(() => null);
-		return isPersistedShellCommandArtifact(value) ? value : null;
+		const value = await this.artifacts.storageFor(commandStorageId).readJson(`commands/${commandId}/artifact.json`).catch(() => null);
+		return isCommandArtifact(value) ? value : null;
 	}
 	persistCommandArtifact(record) {
-		const fingerprint = `${record.status}:${record.exitCode ?? ""}:${record.stdout.length}:${record.stderr.length}`;
+		const fingerprint = `${record.status}:${record.exitCode ?? ""}:${record.stdout.length}:${record.stderr.length}:${record.binaryStdout?.totalBytes ?? ""}`;
 		if (record.persistedFingerprint === fingerprint) return;
 		record.persistedFingerprint = fingerprint;
-		this.artifacts.persist(record.commandScopeId, record.id, persistedArtifactFromRecord(record));
+		this.artifacts.persist(record.commandStorageId, record.id, commandArtifactFromRecord(record));
 	}
 	syncRunningRecord(record) {
 		const foreground = this.shells.get(record.shellId)?.foreground;
@@ -1577,11 +1617,16 @@ function createPortableCommands(session) {
 		}
 	}));
 }
+/** True when the string contains a char > 0xFF, i.e. already-decoded Unicode text. */
+function hasWideChar(value) {
+	for (let i = 0; i < value.length; i += 1) if (value.charCodeAt(i) > 255) return true;
+	return false;
+}
 function normalizeTimeoutMs(value) {
 	if (!Number.isFinite(value) || value < 1 || value > 6e5) throw new Error(`timeoutMs must be between 1 and ${MAX_TIMEOUT_MS}`);
 	return Math.floor(value);
 }
-function streamArtifact(record, stream, explicitOffset, maxOutputBytes) {
+function streamView(record, stream, explicitOffset, maxOutputBytes) {
 	const text = stream === "stdout" ? record.stdout : record.stderr;
 	const totalBytes = utf8Bytes(text);
 	const boundedOffset = clampOffset(explicitOffset ?? (stream === "stdout" ? record.stdoutOffset : record.stderrOffset), totalBytes);
@@ -1601,7 +1646,7 @@ function streamArtifact(record, stream, explicitOffset, maxOutputBytes) {
 		truncated
 	};
 }
-function streamOutputArtifact(record, explicitOffset, maxOutputBytes) {
+function mergedOutputView(record, explicitOffset, maxOutputBytes) {
 	const totalBytes = record.outputChunks.reduce((total, chunk) => total + chunk.bytes, 0);
 	const offset = clampOffset(explicitOffset ?? record.outputOffset, totalBytes);
 	const byteLimit = Math.max(0, Math.floor(maxOutputBytes));
@@ -1655,7 +1700,7 @@ function ensureRecordOutputCoverage(record) {
 	appendRecordOutput(record, "stdout", record.stdout);
 	appendRecordOutput(record, "stderr", record.stderr);
 }
-function persistedArtifactFromRecord(record) {
+function commandArtifactFromRecord(record) {
 	return {
 		status: record.status,
 		shellId: record.shellId,
@@ -1664,7 +1709,12 @@ function persistedArtifactFromRecord(record) {
 		lastOutputAt: record.lastOutputAt,
 		exitCode: record.exitCode ?? null,
 		stdout: record.stdout,
-		stderr: record.stderr
+		stderr: record.stderr,
+		...record.binaryStdout ? { stdoutBinary: {
+			base64: bytesToBase64(record.binaryStdout.data),
+			truncated: record.binaryStdout.truncated,
+			totalBytes: record.binaryStdout.totalBytes
+		} } : {}
 	};
 }
 function commandArtifactMeta(artifact) {
@@ -1686,10 +1736,15 @@ function commandArtifactMeta(artifact) {
 		stderr: {
 			path: stderrPath,
 			bytes: utf8Bytes(artifact.stderr)
-		}
+		},
+		...artifact.stdoutBinary ? { stdoutBinary: {
+			path: `/@/commands/${artifact.commandId}/stdout.bin`,
+			bytes: artifact.stdoutBinary.totalBytes,
+			truncated: artifact.stdoutBinary.truncated
+		} } : {}
 	};
 }
-function isPersistedShellCommandArtifact(value) {
+function isCommandArtifact(value) {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
 	const record = value;
 	return (record.status === "running" || record.status === "exited" || record.status === "aborted") && typeof record.shellId === "string" && typeof record.commandId === "string" && typeof record.startedAt === "number" && typeof record.lastOutputAt === "number" && (typeof record.exitCode === "number" || record.exitCode === null) && typeof record.stdout === "string" && typeof record.stderr === "string";
@@ -1721,4 +1776,4 @@ function heredocDelimiter(body) {
 	return delimiter;
 }
 //#endregion
-export { AgentSessionCommandStorage, BashEnvironment, COMMAND_PROMPT_DEFAULTS, CommandRegistry, DEMI_PORTABLE_COMMANDS, HostBackedFileSystem, MAX_TIMEOUT_MS, RESERVED_COMMAND_NAMES, heredocDelimiter, parseCommandInput, renderCommandPrompt, runRegisteredCommand, shellQuote, virtualDirectory, virtualFile };
+export { AgentSessionCommandStorage, BashEnvironment, COMMAND_HELP_DEFAULTS, CommandRegistry, DEMI_PORTABLE_COMMANDS, HostBackedFileSystem, MAX_TIMEOUT_MS, RESERVED_COMMAND_NAMES, emptyStdin, heredocDelimiter, parseCommandInput, renderCommandHelp, runRegisteredCommand, shellQuote, virtualDirectory, virtualFile };

package/dist/{storage-D7EhVuLY.d.mts → storage-ylShLr2v.d.mts}

@@ -1,6 +1,5 @@
-import { u as HostStore } from "./host-DIg4RxcL.mjs";
+import { t as Host, u as HostStore } from "./host-DIg4RxcL.mjs";
 import { z } from "zod";
-
 //#region src/command.d.ts
 type CommandInputSpec = Record<string, z.ZodType>;
 interface CommandOutputSpec {
@@ -27,8 +26,6 @@ interface Command {
   positionals?: string[];
   stdinField?: string;
   output?: CommandOutputSpec;
-  /** Required when `run` is set (may be empty for fixtures). */
-  examples?: string[];
 }
 interface ParsedCommandInput {
   /**
@@ -36,7 +33,7 @@ interface ParsedCommandInput {
    * For help: path of the node help was requested for.
    */
   path: string[];
-  /** True when the invocation was `<path…> prompt`. */
+  /** True when the invocation requested `--help`. */
   help: boolean;
   values: Record<string, unknown>;
   json: boolean;
@@ -49,24 +46,23 @@ interface CommandRunContext {
   cwd: string;
   io: CommandIO;
   storage: CommandStorage;
+  /** Host of the BashEnvironment executing this command. */
+  host: Host;
 }
 interface CommandRunResult {
   exitCode: number;
   metadata?: unknown;
 }
 interface CommandStdin {
+  /** Stdin decoded as UTF-8 text (lossy for non-text input). */
   text: string;
+  /** Raw stdin bytes, byte-identical to what the pipe delivered. */
+  bytes: Uint8Array;
 }
-/** A non-text content item a command emits to the model, peer to stdout text. */
-type CommandAsset = {
-  type: 'image';
-  mediaType: string;
-  data: string;
-};
+declare function emptyStdin(): CommandStdin;
 interface CommandIO {
   stdout(data: string | Uint8Array): Promise<void> | void;
   stderr(data: string | Uint8Array): Promise<void> | void;
-  asset(asset: CommandAsset): Promise<void> | void;
 }
 interface CommandStorage {
   readJson<T>(key: string): Promise<T | null>;
@@ -81,18 +77,19 @@ interface CommandExecutionContext {
   cwd: string;
   io: CommandIO;
   storage: CommandStorage;
+  host: Host;
 }
 declare class CommandRegistry {
   private readonly commands;
   register(command: Command): void;
   get(name: string): Command | null;
   list(): Command[];
-  renderPrompt(): string;
+  renderHelp(): string;
 }
-declare const COMMAND_PROMPT_DEFAULTS = "Unless a command states otherwise: success prints raw text on stdout, failure writes an error message to stderr and exits non-zero.";
+declare const COMMAND_HELP_DEFAULTS = "Unless a command states otherwise: success prints raw text on stdout, failure writes an error message to stderr and exits non-zero. Pass --help at any level to print a command's documentation.";
 declare function parseCommandInput(root: Command, argv: string[], stdin?: CommandStdin): ParsedCommandInput;
 declare function runRegisteredCommand(root: Command, ctx: CommandExecutionContext): Promise<CommandRunResult>;
-declare function renderCommandPrompt(command: Command, parentPath?: string): string;
+declare function renderCommandHelp(command: Command, parentPath?: string): string;
 //#endregion
 //#region src/storage.d.ts
 declare class AgentSessionCommandStorage implements CommandStorage {
@@ -106,4 +103,4 @@ declare class AgentSessionCommandStorage implements CommandStorage {
   private key;
 }
 //#endregion
-export { runRegisteredCommand as _, CommandExecutionContext as a, CommandOutputSpec as c, CommandRunResult as d, CommandStdin as f, renderCommandPrompt as g, parseCommandInput as h, CommandAsset as i, CommandRegistry as l, ParsedCommandInput as m, COMMAND_PROMPT_DEFAULTS as n, CommandIO as o, CommandStorage as p, Command as r, CommandInputSpec as s, AgentSessionCommandStorage as t, CommandRunContext as u };
+export { runRegisteredCommand as _, CommandIO as a, CommandRegistry as c, CommandStdin as d, CommandStorage as f, renderCommandHelp as g, parseCommandInput as h, CommandExecutionContext as i, CommandRunContext as l, emptyStdin as m, COMMAND_HELP_DEFAULTS as n, CommandInputSpec as o, ParsedCommandInput as p, Command as r, CommandOutputSpec as s, AgentSessionCommandStorage as t, CommandRunResult as u };

package/dist/storage.d.mts

@@ -1,2 +1,2 @@
-import { t as AgentSessionCommandStorage } from "./storage-D7EhVuLY.mjs";
+import { t as AgentSessionCommandStorage } from "./storage-ylShLr2v.mjs";
 export { AgentSessionCommandStorage };

package/dist/storage.mjs

@@ -5,7 +5,7 @@ var AgentSessionCommandStorage = class {
 	constructor(store, agentSessionId) {
 		this.store = store;
 		validateAgentSessionId(agentSessionId);
-		this.agentSessionPrefix = `${agentSessionId}/`;
+		this.agentSessionPrefix = `agent-sessions/${agentSessionId}/`;
 	}
 	readJson(key) {
 		return this.store.readJson(this.key(key));

package/package.json

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