@demicodes/shell 0.1.0 → 0.2.1

package/dist/index.mjs

@@ -1,9 +1,8 @@
 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 { z } from "zod";
+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 { createLazyCommands } from "@demicodes/just-bash/commands";
 import { decodeBytesToUtf8, unsafeBytesFromLatin1 } from "@demicodes/just-bash/encoding";
 import { parse } from "@demicodes/just-bash/parser";
 import { ParseException } from "@demicodes/just-bash/parser/types";
@@ -11,63 +10,42 @@ import { LexerError } from "@demicodes/just-bash/parser/lexer";
 import { resolveLimits } from "@demicodes/just-bash/limits";
 //#region src/portable-commands.ts
 /**
+* 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`: 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",
+	"sh",
+	"sleep"
+]);
+/**
 * Fork portable commands BashEnvironment registers in every shell, so
 * cat/ls/grep-class tools work without local coreutils on any Host backend.
+*
+* Sourced directly from just-bash's own registry instead of a hand-maintained
+* copy: `CommandName` is just-bash's own "safe to run anywhere" set — it
+* already excludes the commands that need real process/network access
+* (curl → NetworkCommandName, python3/python → PythonCommandName, js-exec/node
+* → JavaScriptCommandName all live in separate, non-portable type unions). A
+* hand-picked subset of this list drifts silently as just-bash adds commands
+* (this one was missing echo, pwd, printf, date, env, hostname, whoami, gzip,
+* tar, split, sqlite3, xan, and more — all already categorized as safe
+* upstream, just never backported here). Deriving it removes that drift
+* entirely: everything just-bash calls portable (minus the exceptions above),
+* we call portable.
 */
-const DEMI_PORTABLE_COMMANDS = [
-	"cat",
-	"ls",
-	"mkdir",
-	"rmdir",
-	"touch",
-	"rm",
-	"cp",
-	"mv",
-	"ln",
-	"chmod",
-	"readlink",
-	"head",
-	"tail",
-	"wc",
-	"stat",
-	"grep",
-	"fgrep",
-	"egrep",
-	"rg",
-	"sed",
-	"awk",
-	"sort",
-	"uniq",
-	"comm",
-	"cut",
-	"paste",
-	"tr",
-	"rev",
-	"nl",
-	"fold",
-	"expand",
-	"unexpand",
-	"strings",
-	"column",
-	"join",
-	"tee",
-	"find",
-	"basename",
-	"dirname",
-	"tree",
-	"du",
-	"jq",
-	"base64",
-	"diff",
-	"seq",
-	"expr",
-	"md5sum",
-	"sha1sum",
-	"sha256sum",
-	"file",
-	"tac",
-	"od"
-];
+const DEMI_PORTABLE_COMMANDS = getCommandNames().filter((name) => !REAL_SPAWN_DEPENDENT_COMMANDS.has(name));
 /** Shell language words and builtins the interpreter itself owns. */
 const SHELL_BUILTIN_NAMES = [
 	".",
@@ -94,7 +72,15 @@ const SHELL_BUILTIN_NAMES = [
 	"unset",
 	"wait"
 ];
-/** Ecosystem tools the model expects to reach through Host.process.spawn. */
+/**
+* Ecosystem tools the model expects to reach through Host.process.spawn.
+*
+* xargs and yq are deliberately absent even though real versions exist: both
+* now have a real (non-simulated-elsewhere) implementation in just-bash's own
+* portable set above, which registers and dispatches before Host.process.spawn
+* is ever consulted — listing them here too would claim they fall through to
+* a real spawn, which no longer happens.
+*/
 const SYSTEM_TOOL_NAMES = [
 	"bun",
 	"cargo",
@@ -108,9 +94,7 @@ const SYSTEM_TOOL_NAMES = [
 	"python3",
 	"ruby",
 	"rustc",
-	"xargs",
-	"yarn",
-	"yq"
+	"yarn"
 ];
 /**
 * Names registered commands must not shadow, derived from the actual portable
@@ -124,16 +108,30 @@ const RESERVED_COMMAND_NAMES = /* @__PURE__ */ new Set([
 ]);
 //#endregion
 //#region src/command.ts
-function isCommandGroup(node) {
-	return "subcommands" in node;
+function emptyStdin() {
+	return {
+		text: "",
+		bytes: /* @__PURE__ */ new Uint8Array(0)
+	};
 }
+const EXECUTION_ONLY_FIELDS = [
+	"effects",
+	"successOutput",
+	"failureOutput",
+	"input",
+	"positionals",
+	"stdinField",
+	"output",
+	"examples"
+];
+const COMMAND_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 var CommandRegistry = class {
 	commands = /* @__PURE__ */ new Map();
-	register(spec) {
-		if (RESERVED_COMMAND_NAMES.has(spec.name)) throw new Error(`CommandRegistry: command "${spec.name}" is reserved for shell/system commands`);
-		if (this.commands.has(spec.name)) throw new Error(`CommandRegistry: command "${spec.name}" is already registered`);
-		validateCommandTree(spec, spec.name);
-		this.commands.set(spec.name, spec);
+	register(command) {
+		if (RESERVED_COMMAND_NAMES.has(command.name)) throw new Error(`CommandRegistry: command "${command.name}" is reserved for shell/system commands`);
+		if (this.commands.has(command.name)) throw new Error(`CommandRegistry: command "${command.name}" is already registered`);
+		validateCommandTree(command, command.name);
+		this.commands.set(command.name, command);
 	}
 	get(name) {
 		return this.commands.get(name) ?? null;
@@ -141,49 +139,55 @@ var CommandRegistry = class {
 	list() {
 		return [...this.commands.values()];
 	}
-	renderPrompt() {
-		const rendered = this.list().map((spec) => renderCommandPrompt(spec)).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 subcommand states otherwise: success prints raw text on stdout, failure writes an error message to stderr and exits non-zero.";
-function parseCommandInput(spec, argv, stdin = { text: "" }) {
-	if (argv[0] !== spec.name) throw new Error(`Expected command "${spec.name}", received "${argv[0] ?? ""}"`);
-	let group = spec;
-	const path = [];
+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];
 	let index = 1;
 	while (true) {
-		const segment = argv[index];
-		if (!segment) throw new Error(`Command "${[spec.name, ...path].join(" ")}" requires a subcommand`);
-		if (segment === "prompt") return {
-			subcommand: "prompt",
-			path,
+		if (index >= argv.length) {
+			if (node.run) return parseArgs(node, path, argv, index, stdin);
+			throw new Error(`Command "${path.join(" ")}" requires a subcommand`);
+		}
+		const token = argv[index];
+		if (token === "--help") return {
+			path: [...path],
+			help: true,
 			values: {},
 			json: false
 		};
-		const child = group.subcommands.find((candidate) => candidate.name === segment);
-		if (!child) throw new Error(`Unknown subcommand "${[
-			spec.name,
-			...path,
-			segment
-		].join(" ")}"`);
-		path.push(child.name);
-		index += 1;
-		if (isCommandGroup(child)) {
-			group = child;
+		const child = node.subcommands?.find((candidate) => candidate.name === token);
+		if (child) {
+			node = child;
+			path.push(child.name);
+			index += 1;
 			continue;
 		}
-		return parseLeafInput(child, [spec.name, ...path].join(" "), path, argv, index, stdin);
+		if (!node.run) throw new Error(`Unknown subcommand "${[...path, token].join(" ")}"`);
+		return parseArgs(node, path, argv, index, stdin);
 	}
 }
-function parseLeafInput(subcommand, displayPath, path, argv, startIndex, stdin) {
-	const input = subcommand.input ?? {};
+function parseArgs(command, path, argv, startIndex, stdin) {
+	const displayPath = path.join(" ");
+	const input = command.input ?? {};
 	const values = {};
 	let json = false;
 	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;
@@ -200,43 +204,45 @@ function parseLeafInput(subcommand, displayPath, path, argv, startIndex, stdin)
 			setParsedValue(values, field, rawValue);
 			continue;
 		}
-		const field = subcommand.positionals?.[positionalIndex];
+		const field = command.positionals?.[positionalIndex];
 		if (!field) throw new Error(`Unexpected positional argument "${token}"`);
 		setParsedValue(values, field, token);
 		positionalIndex += 1;
 	}
-	if (subcommand.stdinField) values[subcommand.stdinField] = stdin.text;
+	if (command.stdinField) values[command.stdinField] = stdin.text;
 	return {
-		subcommand: subcommand.name,
-		path,
+		path: [...path],
+		help: false,
 		values: validateInput(input, values),
 		json
 	};
 }
-function resolveCommandNode(spec, path) {
-	let node = spec;
-	for (const segment of path) {
-		if (!isCommandGroup(node)) throw new Error(`"${node.name}" has no subcommand "${segment}"`);
-		const child = node.subcommands.find((candidate) => candidate.name === segment);
-		if (!child) throw new Error(`Unknown subcommand "${segment}" under "${node.name}"`);
+function resolveCommand(root, path) {
+	if (path[0] !== root.name) throw new Error(`Path root "${path[0] ?? ""}" does not match command "${root.name}"`);
+	let node = root;
+	for (let i = 1; i < path.length; i += 1) {
+		const segment = path[i];
+		const child = node.subcommands?.find((candidate) => candidate.name === segment);
+		if (!child) throw new Error(`Unknown subcommand "${path.slice(0, i + 1).join(" ")}"`);
 		node = child;
 	}
 	return node;
 }
-async function runRegisteredCommand(spec, ctx) {
-	const stdin = ctx.stdin ?? { text: "" };
-	const parsed = parseCommandInput(spec, ctx.argv, stdin);
-	if (parsed.subcommand === "prompt") {
-		const node = resolveCommandNode(spec, parsed.path);
-		const parentPath = [spec.name, ...parsed.path.slice(0, -1)].join(" ");
-		await ctx.io.stdout(`${renderCommandPrompt(node, parsed.path.length > 0 ? parentPath : "")}\n`);
+async function runRegisteredCommand(root, ctx) {
+	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(`${renderCommandHelp(node, parentPath)}\n`);
 		return { exitCode: 0 };
 	}
-	const subcommand = resolveCommandNode(spec, parsed.path);
-	if (isCommandGroup(subcommand)) throw new Error(`"${[spec.name, ...parsed.path].join(" ")}" is not runnable`);
-	if (parsed.json && !subcommand.output?.json) throw new Error(`Subcommand "${[spec.name, ...parsed.path].join(" ")}" does not define JSON output`);
+	const command = resolveCommand(root, parsed.path);
+	if (!command.run) throw new Error(`"${displayPath}" is not runnable`);
+	if (parsed.json && !command.output?.json) throw new Error(`Command "${displayPath}" does not define JSON output`);
 	const capture = new CapturingIO(ctx.io);
-	const result = await subcommand.run({
+	const result = await command.run({
 		argv: ctx.argv,
 		parsed,
 		stdin,
@@ -251,60 +257,73 @@ async function runRegisteredCommand(spec, ctx) {
 		try {
 			json = JSON.parse(raw);
 		} catch (error) {
-			throw new Error(`Invalid JSON output for "${[spec.name, ...parsed.path].join(" ")}": ${asError(error).message}`);
+			throw new Error(`Invalid JSON output for "${displayPath}": ${asError(error).message}`);
 		}
-		const validation = subcommand.output?.json?.safeParse(json);
+		const validation = command.output?.json?.safeParse(json);
 		if (!validation?.success) {
 			const issue = validation?.error.issues[0];
-			throw new Error(`JSON output failed validation for "${[spec.name, ...parsed.path].join(" ")}": ${issue?.message}`);
+			throw new Error(`JSON output failed validation for "${displayPath}": ${issue?.message}`);
 		}
 		await ctx.io.stdout(raw);
 	}
 	return result;
 }
-function renderCommandPrompt(spec, parentPath = "") {
-	const path = parentPath ? `${parentPath} ${spec.name}` : spec.name;
-	const leaves = spec.subcommands.filter((node) => !isCommandGroup(node));
-	const groups = spec.subcommands.filter(isCommandGroup);
-	const lines = [`${path}: ${spec.summary}`];
-	if (leaves.length > 0) {
-		lines.push("", "Subcommands:");
-		for (const subcommand of leaves) {
-			lines.push("", `  ${path} ${subcommand.name}`);
-			lines.push(`    ${subcommand.summary}`);
-			if (subcommand.effects) lines.push(`    Effects: ${subcommand.effects}`);
-			if (subcommand.successOutput) lines.push(`    Success output: ${subcommand.successOutput}`);
-			else if (subcommand.output?.json) lines.push("    Success output: raw text by default; machine-readable JSON when --json is passed");
-			if (subcommand.failureOutput) lines.push(`    Failure output: ${subcommand.failureOutput}`);
-			const fields = Object.entries(subcommand.input ?? {});
-			if (fields.length > 0) {
-				lines.push("    Parameters:");
-				for (const [field, schema] of fields) {
-					const positional = subcommand.positionals?.includes(field) ?? false;
-					const stdin = subcommand.stdinField === field;
-					lines.push(`      ${formatField(field, schema, positional, stdin)}`);
-				}
-			}
-			if (subcommand.stdinField) lines.push(`    stdin/heredoc: ${subcommand.stdinField}`);
-			if (subcommand.output?.json) lines.push("    --json: emits machine-readable JSON for this subcommand");
-			else lines.push("    --json: accepted only when this subcommand defines JSON output");
-			if (subcommand.examples.length > 0) {
-				lines.push("    Examples:");
-				for (const example of subcommand.examples) lines.push(indent(example, 6));
+function renderCommandHelp(command, parentPath = "") {
+	const path = parentPath ? `${parentPath} ${command.name}` : command.name;
+	const blocks = [];
+	const lines = [`${path}: ${command.summary}`];
+	if (command.run) {
+		lines.push("", "Usage:");
+		lines.push("", `  ${path}`);
+		if (command.effects) lines.push(`    Effects: ${command.effects}`);
+		if (command.successOutput) lines.push(`    Success output: ${command.successOutput}`);
+		else if (command.output?.json) lines.push("    Success output: raw text by default; machine-readable JSON when --json is passed");
+		if (command.failureOutput) lines.push(`    Failure output: ${command.failureOutput}`);
+		const fields = Object.entries(command.input ?? {});
+		if (fields.length > 0) {
+			lines.push("    Parameters:");
+			for (const [field, schema] of fields) {
+				const positional = command.positionals?.includes(field) ?? false;
+				const stdin = command.stdinField === field;
+				lines.push(`      ${formatField(field, schema, positional, stdin)}`);
 			}
 		}
+		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 blocks = [lines.join("\n")];
-	for (const group of groups) blocks.push(renderCommandPrompt(group, path));
+	const children = command.subcommands ?? [];
+	if (children.length > 0) {
+		lines.push("", "Subcommands:");
+		for (const child of children) lines.push(`  ${path} ${child.name} — ${child.summary}`);
+	}
+	blocks.push(lines.join("\n"));
+	for (const child of children) blocks.push(renderCommandHelp(child, path));
 	return blocks.join("\n\n");
 }
-function validateCommandTree(node, path) {
+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) {
+		const input = command.input ?? {};
+		if (command.stdinField && !(command.stdinField in input)) throw new Error(`CommandRegistry: "${path}" stdinField "${command.stdinField}" is not in input`);
+		for (const positional of command.positionals ?? []) if (!(positional in input)) throw new Error(`CommandRegistry: "${path}" positional "${positional}" is not in input`);
+	}
 	const seen = /* @__PURE__ */ new Set();
-	for (const child of node.subcommands) {
-		if (child.name === "prompt") throw new Error(`CommandRegistry: "${path} prompt" is reserved for the help pseudo-subcommand`);
+	for (const child of children) {
 		if (seen.has(child.name)) throw new Error(`CommandRegistry: duplicate subcommand "${path} ${child.name}"`);
 		seen.add(child.name);
-		if (isCommandGroup(child)) validateCommandTree(child, `${path} ${child.name}`);
+		validateCommandTree(child, `${path} ${child.name}`);
 	}
 }
 function setParsedValue(values, field, value) {
@@ -385,75 +404,11 @@ 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));
 	}
 };
 //#endregion
-//#region src/command-projection.ts
-function listRegisteredCommandOperations(commands) {
-	const specs = Array.isArray(commands) ? commands : commands.list();
-	const operations = [];
-	for (const spec of specs) collectOperations(spec, [spec.name], operations);
-	return operations;
-}
-function collectOperations(node, path, operations) {
-	for (const child of node.subcommands) {
-		if (isCommandGroup(child)) {
-			collectOperations(child, [...path, child.name], operations);
-			continue;
-		}
-		operations.push(operationFromLeaf(child, [...path, child.name]));
-	}
-}
-function operationFromLeaf(leaf, path) {
-	const parts = [leaf.summary.trim()];
-	if (leaf.effects) parts.push(`Effects: ${leaf.effects}`);
-	return {
-		path,
-		description: parts.join(" "),
-		inputSchema: inputSchemaFromSpec(leaf.input ?? {}),
-		renderScript: (values) => renderInvocationScript(leaf, path, values)
-	};
-}
-function inputSchemaFromSpec(input) {
-	const schema = z.toJSONSchema(z.object(input));
-	delete schema.$schema;
-	return schema;
-}
-function renderInvocationScript(leaf, path, values) {
-	const tokens = [...path];
-	for (const field of Object.keys(leaf.input ?? {})) {
-		if (field === leaf.stdinField) continue;
-		const value = values[field];
-		if (value === void 0 || value === null) continue;
-		for (const item of Array.isArray(value) ? value : [value]) tokens.push(`--${field}`, shellQuote(scalarText(item)));
-	}
-	const script = tokens.join(" ");
-	if (!leaf.stdinField) return script;
-	const stdinValue = values[leaf.stdinField];
-	const body = stdinValue === void 0 || stdinValue === null ? "" : scalarText(stdinValue);
-	const delimiter = heredocDelimiter(body);
-	return `${script} <<'${delimiter}'\n${body}\n${delimiter}`;
-}
-function scalarText(value) {
-	if (typeof value === "string") return value;
-	if (typeof value === "number" || typeof value === "boolean") return String(value);
-	return JSON.stringify(value);
-}
-function shellQuote(value) {
-	return `'${value.replaceAll("'", `'\\''`)}'`;
-}
-function heredocDelimiter(body) {
-	let delimiter = "DEMI_STDIN";
-	const lines = new Set(body.split("\n"));
-	while (lines.has(delimiter)) delimiter += "_X";
-	return delimiter;
-}
-//#endregion
 //#region src/background-command.ts
 function extractSimpleBackgroundCommand(statementInput) {
 	const statement = statementInput;
@@ -560,8 +515,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);
@@ -703,18 +660,18 @@ var CommandArtifactStore = class {
 };
 //#endregion
 //#region src/registered-command-adapter.ts
-function commandSpecToForkCommand(session, spec, storage) {
+function commandToForkCommand(session, command, storage) {
 	return {
-		name: spec.name,
-		consumesStdin: treeConsumesStdin(spec),
+		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 = [spec.name, ...args];
+			const argv = [command.name, ...args];
 			try {
-				const result = await runRegisteredCommand(spec, {
+				const result = await runRegisteredCommand(command, {
 					argv,
-					stdin: { text: stdinText },
+					stdin,
 					env: mapToRecord(ctx.env),
 					cwd: ctx.cwd,
 					io,
@@ -722,18 +679,19 @@ function commandSpecToForkCommand(session, spec, storage) {
 				});
 				session.accumulator.audit.push({
 					kind: "registered-command",
-					name: spec.name,
+					name: command.name,
 					args,
 					exitCode: result.exitCode
 				});
 				if (result.metadata !== void 0) session.accumulator.commandMetadata.push({
 					kind: "registered-command",
-					name: spec.name,
+					name: command.name,
 					args,
 					metadata: result.metadata
 				});
 				return {
-					stdout: io.stdoutText(),
+					stdout: io.stdoutLatin1(),
+					stdoutKind: "bytes",
 					stderr: io.stderrText(),
 					exitCode: result.exitCode
 				};
@@ -741,75 +699,90 @@ function commandSpecToForkCommand(session, spec, storage) {
 				const message = error instanceof Error ? error.message : String(error);
 				session.accumulator.audit.push({
 					kind: "registered-command",
-					name: spec.name,
+					name: command.name,
 					args,
 					exitCode: 1
 				});
 				return {
-					stdout: io.stdoutText(),
-					stderr: `${io.stderrText()}${spec.name}: ${message}\n`,
+					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();
 }
-function treeConsumesStdin(spec) {
-	return spec.subcommands.some((node) => isCommandGroup(node) ? treeConsumesStdin(node) : Boolean(node.stdinField));
+function treeConsumesStdin(command) {
+	if (command.stdinField) return true;
+	return command.subcommands?.some(treeConsumesStdin) ?? false;
 }
 function mapToRecord(map) {
 	const record = Object.create(null);
 	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;
+/** Upper bound for a single exec observation window (also the command-bridge wait ceiling). */
 const MAX_TIMEOUT_MS = 6e5;
 var BashEnvironment = class {
 	host;
@@ -836,19 +809,23 @@ var BashEnvironment = class {
 	getShell(shellId) {
 		return this.shells.get(shellId) ?? null;
 	}
-	registerCommand(spec) {
-		if (this.commands.get(spec.name)) return;
-		this.commands.register(spec);
+	registerCommand(command) {
+		if (this.commands.get(command.name)) return;
+		this.commands.register(command);
 	}
 	registeredCommands() {
 		return this.commands.list();
 	}
 	async exec(input) {
 		const timeoutMs = normalizeTimeoutMs(input.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-		const session = input.shellId ? this.requireShell(input.shellId) : this.availableDefaultShell(input.agentSessionId);
+		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 (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();
@@ -962,10 +939,10 @@ 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 cwd = initialCwd ?? this.host.defaultCwd;
 		const fs = new HostBackedFileSystem(this.host, { lookup: (path) => this.lookupVirtualArtifact(commandScopeId, path) });
 		const env = /* @__PURE__ */ new Map();
 		for (const [key, value] of Object.entries(this.initialEnv)) env.set(key, value);
@@ -1050,8 +1027,7 @@ var BashEnvironment = class {
 				stdout: "",
 				stderr: "",
 				audit: [],
-				commandMetadata: [],
-				assets: []
+				commandMetadata: []
 			},
 			foregroundWaiters: /* @__PURE__ */ new Set(),
 			backgroundJobs: /* @__PURE__ */ new Map(),
@@ -1060,7 +1036,7 @@ var BashEnvironment = class {
 		};
 		for (const command of createPortableCommands(session)) forkCommands.set(command.name, command);
 		const storage = new AgentSessionCommandStorage(this.host.store, commandScopeId);
-		for (const spec of this.commands.list()) forkCommands.set(spec.name, commandSpecToForkCommand(session, spec, storage));
+		for (const command of this.commands.list()) forkCommands.set(command.name, commandToForkCommand(session, command, storage));
 		session.abortController = new AbortController();
 		session.interpreter = new Interpreter({
 			fs,
@@ -1090,6 +1066,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);
@@ -1109,8 +1086,7 @@ var BashEnvironment = class {
 			stdout: "",
 			stderr: "",
 			audit: [],
-			commandMetadata: [],
-			assets: []
+			commandMetadata: []
 		};
 		session.abortController = new AbortController();
 		session.activeCommandId = record.id;
@@ -1146,7 +1122,7 @@ var BashEnvironment = class {
 			outputOffset: 0,
 			audit: [],
 			commandMetadata: [],
-			assets: []
+			outputLimitBytes: this.defaultOutputLimitBytes
 		};
 		this.commandsById.set(id, record);
 		return record;
@@ -1352,6 +1328,7 @@ var BashEnvironment = class {
 			startedAt,
 			lastOutputAt: startedAt,
 			rawStdoutBuffer: "",
+			rawStdoutBytes: [],
 			rawStderrBuffer: "",
 			stdoutBuffer: "",
 			stderrBuffer: "",
@@ -1372,7 +1349,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) => {
@@ -1385,7 +1362,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] = {
@@ -1406,6 +1383,7 @@ var BashEnvironment = class {
 		session.foreground = void 0;
 		return {
 			stdout,
+			stdoutKind: "bytes",
 			stderr,
 			exitCode
 		};
@@ -1449,12 +1427,35 @@ 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 = record.outputLimitBytes;
+				const truncated = bytes.length > cap;
+				binary = {
+					data: truncated ? bytes.slice(0, cap) : bytes,
+					truncated,
+					totalBytes: bytes.length
+				};
+				stdoutText = `<binary stdout: ${bytes.length} bytes${truncated ? `, exceeds the ${cap}-byte output 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);
 		}
@@ -1473,7 +1474,6 @@ 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);
@@ -1538,7 +1538,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 {
@@ -1555,18 +1555,22 @@ var BashEnvironment = class {
 		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 === 3 && parts[0] === "@" && parts[1] === "commands") {
-			if (!await this.commandArtifact(scopeId, parts[2])) return null;
-			return virtualDirectory([
+			const artifact = await this.commandArtifact(scopeId, 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]);
 		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;
@@ -1592,7 +1596,7 @@ var BashEnvironment = class {
 		return isPersistedShellCommandArtifact(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));
@@ -1623,8 +1627,13 @@ 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 > MAX_TIMEOUT_MS) throw new Error(`timeoutMs must be between 1 and ${MAX_TIMEOUT_MS}`);
+	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) {
@@ -1710,7 +1719,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) {
@@ -1732,7 +1746,12 @@ 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) {
@@ -1754,4 +1773,17 @@ function tailString(value) {
 	return tail(value, 4096);
 }
 //#endregion
-export { AgentSessionCommandStorage, BashEnvironment, COMMAND_PROMPT_DEFAULTS, CommandRegistry, DEMI_PORTABLE_COMMANDS, HostBackedFileSystem, RESERVED_COMMAND_NAMES, isCommandGroup, listRegisteredCommandOperations, parseCommandInput, renderCommandPrompt, runRegisteredCommand, virtualDirectory, virtualFile };
+//#region src/shell-quote.ts
+/** Single-quotes a value for safe use as one shell word. */
+function shellQuote(value) {
+	return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+/** Picks a heredoc delimiter that does not collide with any line already in `body`. */
+function heredocDelimiter(body) {
+	let delimiter = "DEMI_STDIN";
+	const lines = new Set(body.split("\n"));
+	while (lines.has(delimiter)) delimiter += "_X";
+	return delimiter;
+}
+//#endregion
+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 };