@demicodes/shell 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1757 @@
+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 { 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";
+import { LexerError } from "@demicodes/just-bash/parser/lexer";
+import { resolveLimits } from "@demicodes/just-bash/limits";
+//#region src/portable-commands.ts
+/**
+* Fork portable commands BashEnvironment registers in every shell, so
+* cat/ls/grep-class tools work without local coreutils on any Host backend.
+*/
+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"
+];
+/** Shell language words and builtins the interpreter itself owns. */
+const SHELL_BUILTIN_NAMES = [
+	".",
+	"bash",
+	"break",
+	"cd",
+	"command",
+	"continue",
+	"echo",
+	"exit",
+	"export",
+	"jobs",
+	"local",
+	"popd",
+	"printf",
+	"pushd",
+	"read",
+	"return",
+	"set",
+	"sh",
+	"shift",
+	"source",
+	"test",
+	"unset",
+	"wait"
+];
+/** Ecosystem tools the model expects to reach through Host.process.spawn. */
+const SYSTEM_TOOL_NAMES = [
+	"bun",
+	"cargo",
+	"docker",
+	"git",
+	"go",
+	"node",
+	"npm",
+	"pnpm",
+	"python",
+	"python3",
+	"ruby",
+	"rustc",
+	"xargs",
+	"yarn",
+	"yq"
+];
+/**
+* Names registered commands must not shadow, derived from the actual portable
+* command set plus interpreter builtins and pass-through system tools — not a
+* hand-maintained parallel list.
+*/
+const RESERVED_COMMAND_NAMES = /* @__PURE__ */ new Set([
+	...DEMI_PORTABLE_COMMANDS,
+	...SHELL_BUILTIN_NAMES,
+	...SYSTEM_TOOL_NAMES
+]);
+//#endregion
+//#region src/command.ts
+function isCommandGroup(node) {
+	return "subcommands" in node;
+}
+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);
+	}
+	get(name) {
+		return this.commands.get(name) ?? null;
+	}
+	list() {
+		return [...this.commands.values()];
+	}
+	renderPrompt() {
+		const rendered = this.list().map((spec) => renderCommandPrompt(spec)).join("\n\n");
+		if (!rendered) return rendered;
+		return `${COMMAND_PROMPT_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 = [];
+	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,
+			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;
+			continue;
+		}
+		return parseLeafInput(child, [spec.name, ...path].join(" "), path, argv, index, stdin);
+	}
+}
+function parseLeafInput(subcommand, displayPath, path, argv, startIndex, stdin) {
+	const input = subcommand.input ?? {};
+	const values = {};
+	let json = false;
+	let positionalIndex = 0;
+	for (let i = startIndex; i < argv.length; i += 1) {
+		const token = argv[i];
+		if (token === "--json") {
+			json = true;
+			continue;
+		}
+		if (token.startsWith("--")) {
+			const field = token.slice(2);
+			const schema = input[field];
+			if (!schema) throw new Error(`Unknown option "--${field}" for "${displayPath}"`);
+			const next = argv[i + 1];
+			const takesImplicitBoolean = isBooleanSchema(schema) && (next === void 0 || next.startsWith("--"));
+			const rawValue = takesImplicitBoolean ? true : next;
+			if (!takesImplicitBoolean) i += 1;
+			if (rawValue === void 0) throw new Error(`Missing value for "--${field}"`);
+			setParsedValue(values, field, rawValue);
+			continue;
+		}
+		const field = subcommand.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;
+	return {
+		subcommand: subcommand.name,
+		path,
+		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}"`);
+		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`);
+		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 capture = new CapturingIO(ctx.io);
+	const result = await subcommand.run({
+		argv: ctx.argv,
+		parsed,
+		stdin,
+		env: ctx.env,
+		cwd: ctx.cwd,
+		io: parsed.json ? capture : ctx.io,
+		storage: ctx.storage
+	});
+	if (parsed.json && result.exitCode === 0) {
+		const raw = capture.stdoutText();
+		let json;
+		try {
+			json = JSON.parse(raw);
+		} catch (error) {
+			throw new Error(`Invalid JSON output for "${[spec.name, ...parsed.path].join(" ")}": ${asError(error).message}`);
+		}
+		const validation = subcommand.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}`);
+		}
+		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));
+			}
+		}
+	}
+	const blocks = [lines.join("\n")];
+	for (const group of groups) blocks.push(renderCommandPrompt(group, path));
+	return blocks.join("\n\n");
+}
+function validateCommandTree(node, path) {
+	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`);
+		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}`);
+	}
+}
+function setParsedValue(values, field, value) {
+	if (values[field] === void 0) {
+		values[field] = value;
+		return;
+	}
+	if (Array.isArray(values[field])) {
+		values[field].push(value);
+		return;
+	}
+	values[field] = [values[field], value];
+}
+function validateInput(input, values) {
+	const parsed = {};
+	for (const [field, schema] of Object.entries(input)) {
+		const candidate = coerceValue(schema, values[field]);
+		const result = schema.safeParse(candidate);
+		if (!result.success) {
+			const issue = result.error.issues[0];
+			throw new Error(`Invalid value for "${field}": ${issue?.message ?? "validation failed"}`);
+		}
+		parsed[field] = result.data;
+	}
+	return parsed;
+}
+function coerceValue(schema, value) {
+	if (value === void 0) return value;
+	if (isArraySchema(schema)) return Array.isArray(value) ? value : [value];
+	if (isNumberSchema(schema) && typeof value === "string" && value.trim() !== "") return Number(value);
+	if (isBooleanSchema(schema) && typeof value === "string") {
+		if (value === "true") return true;
+		if (value === "false") return false;
+	}
+	return 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";
+}
+function isBooleanSchema(schema) {
+	const unwrapped = unwrapSchema(schema);
+	return zodTypeName(unwrapped) === "boolean" || zodTypeName(unwrapped) === "ZodBoolean";
+}
+function isNumberSchema(schema) {
+	const unwrapped = unwrapSchema(schema);
+	return zodTypeName(unwrapped) === "number" || zodTypeName(unwrapped) === "ZodNumber";
+}
+function zodTypeName(schema) {
+	const internals = schema;
+	return internals.def?.type ?? internals.def?.typeName ?? internals._def?.type ?? internals._def?.typeName;
+}
+function unwrapSchema(schema) {
+	let current = schema;
+	while (true) {
+		const internals = current;
+		const inner = internals.def?.innerType ?? internals._def?.innerType;
+		if (!inner) return current;
+		current = inner;
+	}
+}
+var CapturingIO = class {
+	target;
+	chunks = [];
+	constructor(target) {
+		this.target = target;
+	}
+	async stdout(data) {
+		this.chunks.push(typeof data === "string" ? encodeUtf8(data) : data);
+	}
+	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;
+	if (!statement.background || (statement.operators?.length ?? 0) > 0 || statement.pipelines?.length !== 1) return null;
+	const pipeline = statement.pipelines[0];
+	if (pipeline.commands?.length !== 1) return null;
+	const commandNode = pipeline.commands[0];
+	if (commandNode.type !== "SimpleCommand" || (commandNode.assignments?.length ?? 0) > 0 || (commandNode.redirections?.length ?? 0) > 0) return null;
+	const command = wordToBackgroundText(commandNode.name);
+	if (!command) return null;
+	const args = [];
+	for (const arg of commandNode.args ?? []) {
+		const value = wordToBackgroundText(arg);
+		if (value === null) return null;
+		args.push(value);
+	}
+	return {
+		command,
+		args
+	};
+}
+function formatCommandDisplay(command, args) {
+	return [command, ...args].join(" ");
+}
+function wordToBackgroundText(word) {
+	const node = word;
+	if (node?.type !== "Word" || !node.parts) return null;
+	let text = "";
+	for (const part of node.parts) {
+		const value = wordPartToBackgroundText(part);
+		if (value === null) return null;
+		text += value;
+	}
+	return text;
+}
+function wordPartToBackgroundText(part) {
+	const node = part;
+	switch (node.type) {
+		case "Literal":
+		case "SingleQuoted":
+		case "Escaped": return node.value ?? "";
+		case "Glob": return node.pattern ?? "";
+		case "TildeExpansion": return node.user === null ? "~" : `~${node.user ?? ""}`;
+		case "DoubleQuoted": {
+			let text = "";
+			for (const child of node.parts ?? []) {
+				const value = wordPartToBackgroundText(child);
+				if (value === null) return null;
+				text += value;
+			}
+			return text;
+		}
+		default: return null;
+	}
+}
+//#endregion
+//#region src/environment-output.ts
+function createOutputSinks(fs, cwd, redirections) {
+	const routes = {
+		1: visibleSink(1),
+		2: visibleSink(2)
+	};
+	for (const redirection of redirections ?? []) switch (redirection.operator) {
+		case ">":
+		case ">|":
+			routes[redirection.fd ?? 1] = targetSink(fs, cwd, redirection.target, false);
+			break;
+		case ">>":
+			routes[redirection.fd ?? 1] = targetSink(fs, cwd, redirection.target, true);
+			break;
+		case "&>": {
+			const sink = targetSink(fs, cwd, redirection.target, false);
+			routes[1] = sink;
+			routes[2] = sink;
+			break;
+		}
+		case "&>>": {
+			const sink = targetSink(fs, cwd, redirection.target, true);
+			routes[1] = sink;
+			routes[2] = sink;
+			break;
+		}
+		case ">&": {
+			const fd = redirection.fd ?? 1;
+			if (redirection.target === "-") {
+				routes[fd] = nullSink();
+				break;
+			}
+			const sourceFd = Number.parseInt(redirection.target.replace(/^&/, ""), 10);
+			if (sourceFd === 1 || sourceFd === 2) {
+				routes[fd] = routes[sourceFd];
+				break;
+			}
+			const sink = targetSink(fs, cwd, redirection.target, false);
+			if (redirection.fd === null) {
+				routes[1] = sink;
+				routes[2] = sink;
+			} else routes[fd] = sink;
+			break;
+		}
+	}
+	return routes;
+}
+function recordForegroundChunk(foreground, sourceFd, chunk) {
+	const text = decodeUtf8(chunk);
+	foreground.lastOutputAt = Date.now();
+	if (sourceFd === 1) foreground.rawStdoutBuffer += text;
+	else foreground.rawStderrBuffer += text;
+	const sink = foreground.outputSinks[sourceFd];
+	if (sink.kind === "file" || sink.kind === "null") {
+		sink.bytes.push(chunk);
+		return;
+	}
+	appendVisibleChunk(foreground, sink.fd ?? sourceFd, text, chunk.byteLength);
+}
+async function flushForegroundSinks(session, foreground) {
+	const flushed = /* @__PURE__ */ new Set();
+	for (const sink of [foreground.outputSinks[1], foreground.outputSinks[2]]) {
+		if (sink.kind !== "file" || flushed.has(sink)) continue;
+		flushed.add(sink);
+		const bytes = concatBytes(sink.bytes);
+		if (sink.append) await session.fs.appendFile(sink.path, bytes);
+		else await session.fs.writeFile(sink.path, bytes);
+	}
+}
+function notifyForegroundWaiters(waiters, foreground) {
+	const snapshot = [...waiters];
+	waiters.clear();
+	for (const waiter of snapshot) waiter(foreground);
+}
+async function pumpStream(stream, onChunk) {
+	try {
+		for await (const chunk of stream) onChunk(chunk);
+	} catch {}
+}
+async function pumpOutputStream(stream, onChunk) {
+	try {
+		for await (const chunk of stream) onChunk(chunk);
+	} catch {}
+}
+function buildShellopts(options) {
+	const flags = [];
+	if (options.errexit) flags.push("errexit");
+	if (options.pipefail) flags.push("pipefail");
+	if (options.nounset) flags.push("nounset");
+	if (options.xtrace) flags.push("xtrace");
+	if (options.verbose) flags.push("verbose");
+	if (options.posix) flags.push("posix");
+	if (options.allexport) flags.push("allexport");
+	if (options.noclobber) flags.push("noclobber");
+	if (options.noglob) flags.push("noglob");
+	if (options.noexec) flags.push("noexec");
+	if (options.vi) flags.push("vi");
+	if (options.emacs) flags.push("emacs");
+	return flags.join(":");
+}
+function buildBashopts(options) {
+	const flags = [];
+	if (options.extglob) flags.push("extglob");
+	if (options.dotglob) flags.push("dotglob");
+	if (options.nullglob) flags.push("nullglob");
+	if (options.failglob) flags.push("failglob");
+	if (options.globstar) flags.push("globstar");
+	if (options.globskipdots) flags.push("globskipdots");
+	if (options.nocaseglob) flags.push("nocaseglob");
+	if (options.nocasematch) flags.push("nocasematch");
+	if (options.expand_aliases) flags.push("expand_aliases");
+	if (options.lastpipe) flags.push("lastpipe");
+	if (options.xpg_echo) flags.push("xpg_echo");
+	return flags.join(":");
+}
+function visibleSink(fd) {
+	return {
+		kind: "visible",
+		fd,
+		bytes: []
+	};
+}
+function nullSink() {
+	return {
+		kind: "null",
+		bytes: []
+	};
+}
+function targetSink(fs, cwd, target, append) {
+	if (target === "/dev/stdout") return visibleSink(1);
+	if (target === "/dev/stderr") return visibleSink(2);
+	if (target === "/dev/null") return nullSink();
+	return {
+		kind: "file",
+		path: fs.resolvePath(cwd, target),
+		append,
+		bytes: []
+	};
+}
+function appendVisibleChunk(foreground, targetFd, text, byteLength) {
+	foreground.outputChunks.push({
+		stream: targetFd === 1 ? "stdout" : "stderr",
+		text,
+		offset: foreground.outputBytes,
+		bytes: byteLength
+	});
+	foreground.outputBytes += byteLength;
+	if (targetFd === 1) foreground.stdoutBuffer += text;
+	else foreground.stderrBuffer += text;
+}
+//#endregion
+//#region src/command-artifact-store.ts
+/**
+* Owns persistence of shell command artifacts: a per-scope storage 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();
+	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);
+		if (existing) return existing;
+		const storage = new AgentSessionCommandStorage(this.store, scopeId);
+		this.storageByScope.set(scopeId, storage);
+		return storage;
+	}
+	/** Whether a command's artifact has been released (tombstoned). */
+	isReleased(scopeId, commandId) {
+		return this.released.has(this.key(scopeId, 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(() => {});
+	}
+	/** 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(() => {});
+	}
+	key(scopeId, commandId) {
+		return `${scopeId}\0${commandId}`;
+	}
+};
+//#endregion
+//#region src/registered-command-adapter.ts
+function commandSpecToForkCommand(session, spec, storage) {
+	return {
+		name: spec.name,
+		consumesStdin: treeConsumesStdin(spec),
+		execute: async (args, ctx) => {
+			const stdinText = decodeForkStdin(ctx.stdin);
+			const io = createForwardingIO();
+			const argv = [spec.name, ...args];
+			try {
+				const result = await runRegisteredCommand(spec, {
+					argv,
+					stdin: { text: stdinText },
+					env: mapToRecord(ctx.env),
+					cwd: ctx.cwd,
+					io,
+					storage
+				});
+				session.accumulator.audit.push({
+					kind: "registered-command",
+					name: spec.name,
+					args,
+					exitCode: result.exitCode
+				});
+				if (result.metadata !== void 0) session.accumulator.commandMetadata.push({
+					kind: "registered-command",
+					name: spec.name,
+					args,
+					metadata: result.metadata
+				});
+				return {
+					stdout: io.stdoutText(),
+					stderr: io.stderrText(),
+					exitCode: result.exitCode
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				session.accumulator.audit.push({
+					kind: "registered-command",
+					name: spec.name,
+					args,
+					exitCode: 1
+				});
+				return {
+					stdout: io.stdoutText(),
+					stderr: `${io.stderrText()}${spec.name}: ${message}\n`,
+					exitCode: 1
+				};
+			} finally {
+				if (io.assets().length > 0) session.accumulator.assets.push(...io.assets());
+			}
+		}
+	};
+}
+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));
+	}
+	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 mapToRecord(map) {
+	const record = Object.create(null);
+	for (const [key, value] of map) record[key] = value;
+	return record;
+}
+function decodeForkStdin(stdin) {
+	if (!stdin) return "";
+	if (stdin instanceof Uint8Array) return decodeUtf8(stdin);
+	const latin1 = stdin;
+	if (!latin1) return "";
+	let hasHighByte = 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 (!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);
+}
+//#endregion
+//#region src/environment.ts
+const DEFAULT_TIMEOUT_MS = 1e4;
+const DEFAULT_OUTPUT_LIMIT_BYTES = 1024 * 1024;
+const MAX_TIMEOUT_MS = 6e5;
+var BashEnvironment = class {
+	host;
+	commands;
+	shellIdFactory;
+	commandIdFactory;
+	initialEnv;
+	execEnv;
+	defaultOutputLimitBytes;
+	shells = /* @__PURE__ */ new Map();
+	defaultShellByAgentSessionId = /* @__PURE__ */ new Map();
+	commandsById = /* @__PURE__ */ new Map();
+	artifacts;
+	constructor(options) {
+		this.host = options.host;
+		this.artifacts = new CommandArtifactStore(this.host.store);
+		this.commands = options.commands ?? new CommandRegistry();
+		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;
+	}
+	getShell(shellId) {
+		return this.shells.get(shellId) ?? null;
+	}
+	registerCommand(spec) {
+		if (this.commands.get(spec.name)) return;
+		this.commands.register(spec);
+	}
+	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 (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 (session.pendingExec || session.foreground) {
+			const commandId = session.activeCommandId ?? session.foreground?.commandId ?? "unknown";
+			throw new Error(`Shell session "${session.id}" is already running command "${commandId}"`);
+		}
+		return this.runScript(session, input.script, {
+			...input,
+			timeoutMs
+		});
+	}
+	async status(input) {
+		const record = this.requireCommand(input.commandId);
+		return this.snapshotCommand(record, input);
+	}
+	async write(input) {
+		const record = this.requireCommand(input.commandId);
+		if (record.status !== "running") throw new Error(`Command "${record.id}" is not running`);
+		const session = this.requireShell(record.shellId);
+		const foreground = this.requireForegroundCommand(session, record.id);
+		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);
+	}
+	async abort(input) {
+		const record = this.requireCommand(input.commandId);
+		if (record.status !== "running") return this.snapshotCommand(record, input);
+		const session = this.requireShell(record.shellId);
+		const foreground = this.requireForegroundCommand(session, record.id);
+		foreground.abortController.abort();
+		await foreground.handle.kill("SIGTERM");
+		session.state.lastExitCode = 130;
+		return this.collectAborted(session, record, foreground, input);
+	}
+	async releaseCommand(commandId) {
+		const record = this.commandsById.get(commandId);
+		if (!record || record.status === "running") return false;
+		this.commandsById.delete(commandId);
+		await this.artifacts.release(record.commandScopeId, commandId);
+		return true;
+	}
+	async disposeShell(shellId) {
+		const session = this.shells.get(shellId);
+		if (!session) return false;
+		await this.killShell(session);
+		this.shells.delete(shellId);
+		for (const [agentSessionId, defaultShellId] of this.defaultShellByAgentSessionId) if (defaultShellId === shellId) this.defaultShellByAgentSessionId.delete(agentSessionId);
+		return true;
+	}
+	async disposeAllShells() {
+		for (const shellId of this.shells.keys()) await this.disposeShell(shellId);
+	}
+	async killShell(session) {
+		const foreground = session.foreground;
+		session.foreground = void 0;
+		session.pendingExec = void 0;
+		if (foreground) {
+			foreground.abortController.abort();
+			await foreground.handle.kill("SIGKILL").catch(() => {});
+			await foreground.exitPromise.catch(() => {});
+		}
+		for (const job of session.backgroundJobs.values()) {
+			await job.handle.kill("SIGKILL").catch(() => {});
+			await job.exitPromise.catch(() => {});
+		}
+		session.backgroundJobs.clear();
+		if (session.abortController) session.abortController.abort();
+	}
+	requireShell(shellId) {
+		const session = this.shells.get(shellId);
+		if (!session) throw new Error(`Unknown shell session "${shellId}"`);
+		return session;
+	}
+	requireCommand(commandId) {
+		const record = this.commandsById.get(commandId);
+		if (!record) throw new Error(`Unknown shell command "${commandId}"`);
+		const foreground = this.shells.get(record.shellId)?.foreground;
+		if (record.status === "running" && foreground?.commandId === record.id) {
+			record.stdout = foreground.stdoutBuffer;
+			record.stderr = foreground.stderrBuffer;
+			record.outputChunks = [...foreground.outputChunks];
+			record.lastOutputAt = foreground.lastOutputAt;
+		}
+		return record;
+	}
+	requireForegroundCommand(session, commandId) {
+		const foreground = session.foreground;
+		if (!foreground || foreground.commandId !== commandId) throw new Error(`Command "${commandId}" has no foreground process`);
+		return foreground;
+	}
+	defaultShell(agentSessionId) {
+		if (!agentSessionId) return this.createShell(void 0);
+		const existingShellId = this.defaultShellByAgentSessionId.get(agentSessionId);
+		const existing = existingShellId ? this.shells.get(existingShellId) : void 0;
+		if (existing && !existing.exited) return existing;
+		const shell = this.createShell(agentSessionId);
+		this.defaultShellByAgentSessionId.set(agentSessionId, shell.id);
+		return shell;
+	}
+	availableDefaultShell(agentSessionId) {
+		const shell = this.defaultShell(agentSessionId);
+		if (!agentSessionId || shell.exited || !shell.pendingExec && !shell.foreground) return shell;
+		return this.createShell(agentSessionId);
+	}
+	createShell(agentSessionId) {
+		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 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);
+		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"
+		]);
+		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 = {
+			env,
+			cwd,
+			previousDir: cwd,
+			functions: /* @__PURE__ */ new Map(),
+			localScopes: [],
+			callDepth: 0,
+			sourceDepth: 0,
+			commandCount: 0,
+			lastExitCode: 0,
+			lastArg: "",
+			startTime: Date.now(),
+			lastBackgroundPid: 0,
+			virtualPid: 1,
+			virtualPpid: 0,
+			virtualUid: 1e3,
+			virtualGid: 1e3,
+			bashPid: 1,
+			nextVirtualPid: 2,
+			currentLine: 1,
+			options: {
+				errexit: false,
+				pipefail: false,
+				nounset: false,
+				xtrace: false,
+				verbose: false,
+				posix: false,
+				allexport: false,
+				noclobber: false,
+				noglob: false,
+				noexec: false,
+				vi: false,
+				emacs: false
+			},
+			shoptOptions: {
+				extglob: false,
+				dotglob: false,
+				nullglob: false,
+				failglob: false,
+				globstar: false,
+				globskipdots: true,
+				nocaseglob: false,
+				nocasematch: false,
+				expand_aliases: false,
+				lastpipe: false,
+				xpg_echo: false
+			},
+			inCondition: false,
+			loopDepth: 0,
+			exportedVars,
+			readonlyVars: /* @__PURE__ */ new Set(["SHELLOPTS", "BASHOPTS"]),
+			hashTable: /* @__PURE__ */ new Map()
+		};
+		state.env.set("SHELLOPTS", buildShellopts(state.options));
+		state.env.set("BASHOPTS", buildBashopts(state.shoptOptions));
+		const forkCommands = /* @__PURE__ */ new Map();
+		const session = {
+			id,
+			commandScopeId,
+			state,
+			fs,
+			interpreter: void 0,
+			forkCommands,
+			accumulator: {
+				stdout: "",
+				stderr: "",
+				audit: [],
+				commandMetadata: [],
+				assets: []
+			},
+			foregroundWaiters: /* @__PURE__ */ new Set(),
+			backgroundJobs: /* @__PURE__ */ new Map(),
+			nextBackgroundJobId: 1,
+			exited: false
+		};
+		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));
+		session.abortController = new AbortController();
+		session.interpreter = new Interpreter({
+			fs,
+			commands: forkCommands,
+			limits: resolveLimits({
+				maxOutputSize: 1024 * 1024 * 1024,
+				maxCommandCount: 1e6,
+				maxLoopIterations: 1e6,
+				maxCallDepth: 1e3,
+				maxGlobOperations: 1e6
+			}),
+			exec: async () => ({
+				stdout: "",
+				stderr: "",
+				exitCode: 0
+			}),
+			hostSpawn: (command, args, opts) => this.hostSpawn(session, command, args, opts),
+			rejectTimedPipelines: true,
+			jobControl: {
+				startBackground: (statement) => this.startBackgroundJob(session, statement),
+				jobs: (args) => this.listBackgroundJobs(session, args),
+				wait: (args) => this.waitForBackgroundJob(session, args)
+			}
+		}, state);
+		this.shells.set(id, session);
+		return session;
+	}
+	async runScript(session, script, input) {
+		const record = this.createCommandRecord(session, script);
+		let ast;
+		try {
+			ast = parse(script);
+		} catch (error) {
+			if (error instanceof ParseException || error instanceof LexerError) {
+				record.stderr = `bash: ${error.message}\n`;
+				appendRecordOutput(record, "stderr", record.stderr);
+				record.status = "exited";
+				record.exitCode = 2;
+				session.state.lastExitCode = 2;
+				session.activeCommandId = void 0;
+				return this.snapshotCommand(record, input);
+			}
+			throw error;
+		}
+		session.accumulator = {
+			stdout: "",
+			stderr: "",
+			audit: [],
+			commandMetadata: [],
+			assets: []
+		};
+		session.abortController = new AbortController();
+		session.activeCommandId = record.id;
+		const execPromise = session.interpreter.executeScript(ast).then((result) => result, (error) => error);
+		session.pendingExec = execPromise;
+		execPromise.then((result) => {
+			try {
+				if (record.status === "running" && session.pendingExec === execPromise) this.collectExited(session, record, result, session.foreground, {
+					stdoutOffset: record.stdoutOffset,
+					stderrOffset: record.stderrOffset,
+					outputOffset: record.outputOffset
+				});
+			} catch {}
+		}, () => {});
+		return this.raceForeground(session, record, void 0, execPromise, input);
+	}
+	createCommandRecord(session, script) {
+		const id = this.commandIdFactory();
+		const now = Date.now();
+		const record = {
+			id,
+			shellId: session.id,
+			commandScopeId: session.commandScopeId,
+			script,
+			startedAt: now,
+			lastOutputAt: now,
+			status: "running",
+			stdout: "",
+			stderr: "",
+			stdoutOffset: 0,
+			stderrOffset: 0,
+			outputChunks: [],
+			outputOffset: 0,
+			audit: [],
+			commandMetadata: [],
+			assets: []
+		};
+		this.commandsById.set(id, record);
+		return record;
+	}
+	async startBackgroundJob(session, statement) {
+		const backgroundCommand = extractSimpleBackgroundCommand(statement);
+		if (!backgroundCommand) return null;
+		const id = session.nextBackgroundJobId++;
+		const handle = await this.host.process.spawn({
+			command: backgroundCommand.command,
+			args: backgroundCommand.args,
+			cwd: session.state.cwd,
+			env: this.exportedEnv(session),
+			killProcessGroup: true
+		});
+		await handle.closeStdin().catch(() => {});
+		const job = {
+			id,
+			command: backgroundCommand.command,
+			args: backgroundCommand.args,
+			display: formatCommandDisplay(backgroundCommand.command, backgroundCommand.args),
+			cwd: session.state.cwd,
+			handle,
+			stdoutBuffer: "",
+			stderrBuffer: "",
+			stdoutPump: Promise.resolve(),
+			stderrPump: Promise.resolve(),
+			exitPromise: handle.wait()
+		};
+		job.stdoutPump = pumpStream(handle.stdout, (chunk) => {
+			job.stdoutBuffer += decodeUtf8(chunk);
+		});
+		job.stderrPump = pumpStream(handle.stderr, (chunk) => {
+			job.stderrBuffer += decodeUtf8(chunk);
+		});
+		session.backgroundJobs.set(id, job);
+		session.state.lastBackgroundPid = id;
+		session.state.env.set("!", String(id));
+		return {
+			stdout: `[${id}] ${job.display}\n`,
+			stderr: "",
+			exitCode: 0
+		};
+	}
+	async listBackgroundJobs(session, args) {
+		if (args.length > 0) return {
+			stdout: "",
+			stderr: `bash: jobs: unsupported option or argument: ${args.join(" ")}\n`,
+			exitCode: 2
+		};
+		let stdout = "";
+		for (const job of session.backgroundJobs.values()) stdout += `[${job.id}] Running ${job.display}\n`;
+		return {
+			stdout,
+			stderr: "",
+			exitCode: 0
+		};
+	}
+	async waitForBackgroundJob(session, args) {
+		if (args.length !== 1) return {
+			stdout: "",
+			stderr: "bash: wait: expected a single job spec\n",
+			exitCode: 2
+		};
+		const match = args[0].match(/^%(\d+)$/);
+		if (!match) return {
+			stdout: "",
+			stderr: `bash: wait: ${args[0]}: unsupported job spec\n`,
+			exitCode: 2
+		};
+		const id = Number.parseInt(match[1], 10);
+		const job = session.backgroundJobs.get(id);
+		if (!job) return {
+			stdout: "",
+			stderr: `bash: wait: %${id}: no such job\n`,
+			exitCode: 127
+		};
+		const exit = await job.exitPromise;
+		await Promise.allSettled([job.stdoutPump, job.stderrPump]);
+		session.backgroundJobs.delete(id);
+		const exitCode = exit.exitCode ?? 127;
+		const stderr = exit.exitCode === null && job.stderrBuffer.length === 0 ? `${job.command}: ${exit.signal ?? "command not found"}\n` : job.stderrBuffer;
+		session.accumulator.audit.push({
+			kind: "system-command",
+			name: job.command,
+			args: job.args,
+			cwd: job.cwd,
+			exitCode
+		});
+		return {
+			stdout: job.stdoutBuffer,
+			stderr,
+			exitCode
+		};
+	}
+	exportedEnv(session) {
+		const env = {};
+		for (const name of session.state.exportedVars ?? []) {
+			const value = session.state.env.get(name);
+			if (value !== void 0) env[name] = value;
+		}
+		return env;
+	}
+	async raceForeground(session, record, foreground, execPromise, input) {
+		const timeoutMs = normalizeTimeoutMs(input.timeoutMs);
+		const operationStartedAt = Date.now();
+		while (true) {
+			const foregroundNow = session.foreground;
+			if (foregroundNow && foregroundNow !== foreground) foreground = foregroundNow;
+			const boundary = this.waitForBoundary(session, foreground, operationStartedAt, timeoutMs, input.signal);
+			const outcome = await Promise.race([execPromise.then((r) => ({
+				kind: "done",
+				result: r
+			})), boundary.promise]);
+			boundary.cancel();
+			if (outcome.kind === "done") return this.collectExited(session, record, outcome.result, foreground, input);
+			if (outcome.kind === "foreground_appeared") {
+				foreground = outcome.foreground;
+				continue;
+			}
+			if (outcome.kind === "timeout") return this.snapshotCommand(record, input);
+			if (outcome.kind === "aborted") {
+				const activeForeground = foreground ?? session.foreground;
+				if (!activeForeground) return this.collectAbortedWithoutForeground(session, record, input);
+				return this.collectAborted(session, record, activeForeground, input);
+			}
+		}
+	}
+	waitForBoundary(session, foreground, operationStartedAt, timeoutMs, externalSignal) {
+		const timers = [];
+		const listeners = [];
+		const cancel = () => {
+			for (const clear of timers) clear();
+			for (const remove of listeners) remove();
+		};
+		if (!foreground) if (session.foreground) foreground = session.foreground;
+		else return {
+			promise: new Promise((resolve) => {
+				if (externalSignal?.aborted) {
+					resolve({ kind: "aborted" });
+					return;
+				}
+				const timeoutIn = Math.max(0, timeoutMs - (Date.now() - operationStartedAt));
+				const t = setTimeout(() => resolve({ kind: "timeout" }), timeoutIn);
+				timers.push(() => clearTimeout(t));
+				const onForeground = (nextForeground) => {
+					resolve({
+						kind: "foreground_appeared",
+						foreground: nextForeground
+					});
+				};
+				session.foregroundWaiters.add(onForeground);
+				listeners.push(() => session.foregroundWaiters.delete(onForeground));
+				if (externalSignal) {
+					const onExternal = () => resolve({ kind: "aborted" });
+					externalSignal.addEventListener("abort", onExternal, { once: true });
+					listeners.push(() => externalSignal.removeEventListener("abort", onExternal));
+				}
+			}),
+			cancel
+		};
+		const fg = foreground;
+		return {
+			promise: new Promise((resolve) => {
+				if (fg.abortController.signal.aborted || externalSignal?.aborted) {
+					resolve({ kind: "aborted" });
+					return;
+				}
+				const timeoutIn = Math.max(0, timeoutMs - (Date.now() - operationStartedAt));
+				const t = setTimeout(() => resolve({ kind: "timeout" }), timeoutIn);
+				timers.push(() => clearTimeout(t));
+				const onAbort = () => resolve({ kind: "aborted" });
+				fg.abortController.signal.addEventListener("abort", onAbort, { once: true });
+				listeners.push(() => fg.abortController.signal.removeEventListener("abort", onAbort));
+				if (externalSignal) {
+					const onExternal = () => resolve({ kind: "aborted" });
+					externalSignal.addEventListener("abort", onExternal, { once: true });
+					listeners.push(() => externalSignal.removeEventListener("abort", onExternal));
+				}
+			}),
+			cancel
+		};
+	}
+	async hostSpawn(session, command, args, opts) {
+		if (session.foreground) throw new Error(`hostSpawn: session "${session.id}" already has a foreground process`);
+		const handle = await this.host.process.spawn({
+			command,
+			args,
+			cwd: opts.cwd,
+			env: opts.env,
+			killProcessGroup: true
+		});
+		const startedAt = Date.now();
+		const abortController = new AbortController();
+		const commandId = session.activeCommandId;
+		if (!commandId) throw new Error(`hostSpawn: session "${session.id}" has no active command`);
+		const foreground = {
+			commandId,
+			command,
+			args,
+			cwd: opts.cwd,
+			handle,
+			startedAt,
+			lastOutputAt: startedAt,
+			rawStdoutBuffer: "",
+			rawStderrBuffer: "",
+			stdoutBuffer: "",
+			stderrBuffer: "",
+			outputChunks: [],
+			outputBytes: 0,
+			audit: [{
+				kind: "system-command",
+				name: command,
+				args,
+				cwd: opts.cwd,
+				exitCode: 0
+			}],
+			stdoutPump: Promise.resolve(),
+			stderrPump: Promise.resolve(),
+			exitPromise: handle.wait(),
+			outputSinks: createOutputSinks(session.fs, opts.cwd, opts.redirections),
+			abortController
+		};
+		session.foreground = foreground;
+		notifyForegroundWaiters(session.foregroundWaiters, foreground);
+		if (opts.stdin && opts.stdin.length > 0) await handle.writeStdin(encodeUtf8(opts.stdin));
+		if (opts.stdinProvided) await handle.closeStdin();
+		if (handle.output) {
+			foreground.stdoutPump = pumpOutputStream(handle.output, (chunk) => {
+				recordForegroundChunk(foreground, chunk.stream === "stdout" ? 1 : 2, chunk.chunk);
+			});
+			foreground.stderrPump = Promise.resolve();
+		} else {
+			foreground.stdoutPump = pumpStream(handle.stdout, (chunk) => recordForegroundChunk(foreground, 1, chunk));
+			foreground.stderrPump = pumpStream(handle.stderr, (chunk) => recordForegroundChunk(foreground, 2, chunk));
+		}
+		const exit = await foreground.exitPromise;
+		await Promise.allSettled([foreground.stdoutPump, foreground.stderrPump]);
+		const stdout = foreground.rawStdoutBuffer;
+		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] = {
+			kind: "system-command",
+			name: command,
+			args,
+			cwd: opts.cwd,
+			exitCode
+		};
+		session.accumulator.audit.push(...foreground.audit);
+		const record = this.commandsById.get(commandId);
+		if (record) {
+			record.stdout = foreground.stdoutBuffer;
+			record.stderr = foreground.stderrBuffer;
+			record.outputChunks = [...foreground.outputChunks];
+			record.lastOutputAt = foreground.lastOutputAt;
+		}
+		session.foreground = void 0;
+		return {
+			stdout,
+			stderr,
+			exitCode
+		};
+	}
+	collectExited(session, record, resultOrError, foreground, input = {}) {
+		if (record.status !== "running") return this.snapshotCommand(record, input);
+		if (resultOrError instanceof Error) {
+			if (resultOrError instanceof ExitError) {
+				session.exited = true;
+				const err = resultOrError;
+				const outText = decodeBytesToUtf8(unsafeBytesFromLatin1(err.stdout));
+				const errText = decodeBytesToUtf8(unsafeBytesFromLatin1(err.stderr));
+				session.accumulator.stdout += outText;
+				session.accumulator.stderr += errText;
+				appendRecordOutput(record, "stdout", outText);
+				appendRecordOutput(record, "stderr", errText);
+				return this.finishExited(session, record, err.exitCode, input);
+			}
+			if (resultOrError instanceof ExecutionLimitError) {
+				const text = `bash: execution limit exceeded: ${resultOrError.message}\n`;
+				session.accumulator.stderr += text;
+				appendRecordOutput(record, "stderr", text);
+				return this.finishExited(session, record, ExecutionLimitError.EXIT_CODE, input);
+			}
+			if (resultOrError instanceof ParseException || resultOrError instanceof LexerError) {
+				const text = `bash: ${resultOrError.message}\n`;
+				session.accumulator.stderr += text;
+				appendRecordOutput(record, "stderr", text);
+				return this.finishExited(session, record, 2, input);
+			}
+			if (resultOrError.message.startsWith("Unsupported shell syntax:")) {
+				session.pendingExec = void 0;
+				throw resultOrError;
+			}
+			if (resultOrError instanceof ArithmeticError || resultOrError instanceof BadSubstitutionError) {
+				session.pendingExec = void 0;
+				throw resultOrError;
+			}
+			const text = `bash: ${resultOrError.message}\n`;
+			session.accumulator.stderr += text;
+			appendRecordOutput(record, "stderr", text);
+			return this.finishExited(session, record, 1, input);
+		}
+		const stdoutText = foreground ? resultOrError.stdout : decodeBytesToUtf8(unsafeBytesFromLatin1(resultOrError.stdout));
+		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) {
+			appendRecordOutput(record, "stdout", stdoutText);
+			appendRecordOutput(record, "stderr", stderrText);
+		}
+		return this.finishExited(session, record, resultOrError.exitCode, input);
+	}
+	finishExited(session, record, exitCode, input) {
+		record.stdout = session.accumulator.stdout;
+		record.stderr = session.accumulator.stderr;
+		if (record.outputChunks.length === 0) {
+			appendRecordOutput(record, "stdout", record.stdout);
+			appendRecordOutput(record, "stderr", record.stderr);
+		}
+		ensureRecordOutputCoverage(record);
+		record.lastOutputAt = Date.now();
+		record.status = "exited";
+		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);
+	}
+	async collectAborted(session, record, foreground, input = {}) {
+		if (record.status !== "running") return this.snapshotCommand(record, input);
+		foreground.abortController.abort();
+		foreground.handle.kill("SIGTERM").catch(() => {});
+		await flushForegroundSinks(session, foreground);
+		record.stdout = foreground.stdoutBuffer;
+		record.stderr = foreground.stderrBuffer;
+		record.outputChunks = [...foreground.outputChunks];
+		record.lastOutputAt = Date.now();
+		record.status = "aborted";
+		session.foreground = void 0;
+		session.pendingExec = void 0;
+		if (session.activeCommandId === record.id) session.activeCommandId = void 0;
+		return this.snapshotCommand(record, input);
+	}
+	collectAbortedWithoutForeground(session, record, input = {}) {
+		if (record.status !== "running") return this.snapshotCommand(record, input);
+		session.abortController?.abort();
+		session.pendingExec = void 0;
+		if (session.activeCommandId === record.id) session.activeCommandId = void 0;
+		record.stdout = session.accumulator.stdout;
+		record.stderr = session.accumulator.stderr;
+		if (record.outputChunks.length === 0) {
+			appendRecordOutput(record, "stdout", record.stdout);
+			appendRecordOutput(record, "stderr", record.stderr);
+		}
+		record.lastOutputAt = Date.now();
+		record.status = "aborted";
+		return this.snapshotCommand(record, input);
+	}
+	snapshotCommand(record, input = {}) {
+		const foreground = this.shells.get(record.shellId)?.foreground;
+		if (record.status === "running" && foreground?.commandId === record.id) {
+			record.stdout = foreground.stdoutBuffer;
+			record.stderr = foreground.stderrBuffer;
+			record.outputChunks = [...foreground.outputChunks];
+			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 base = {
+			shellId: record.shellId,
+			commandId: record.id,
+			stdout,
+			stderr,
+			output,
+			runningMs: Date.now() - record.startedAt,
+			idleMs: Date.now() - record.lastOutputAt
+		};
+		this.persistCommandArtifact(record);
+		if (record.status === "exited") {
+			const result = {
+				...base,
+				status: "exited",
+				exitCode: record.exitCode ?? 0,
+				audit: record.audit
+			};
+			if (record.commandMetadata.length > 0) result.commandMetadata = record.commandMetadata;
+			if (record.assets.length > 0) result.assets = record.assets;
+			return result;
+		}
+		if (record.status === "aborted") return {
+			...base,
+			status: "aborted"
+		};
+		return {
+			...base,
+			status: "running"
+		};
+	}
+	async lookupVirtualArtifact(scopeId, 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 === 3 && parts[0] === "@" && parts[1] === "commands") {
+			if (!await this.commandArtifact(scopeId, parts[2])) return null;
+			return virtualDirectory([
+				"meta.json",
+				"stderr.txt",
+				"stdout.txt"
+			]);
+		}
+		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 === "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) {
+		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 key of keys) {
+			const match = /^commands\/([^/]+)\/artifact\.json$/.exec(key);
+			if (match && !this.artifacts.isReleased(scopeId, match[1])) ids.add(match[1]);
+		}
+		return [...ids];
+	}
+	async commandArtifact(scopeId, commandId) {
+		if (this.artifacts.isReleased(scopeId, commandId)) return null;
+		const record = this.commandsById.get(commandId);
+		if (record?.commandScopeId === scopeId) {
+			this.syncRunningRecord(record);
+			return persistedArtifactFromRecord(record);
+		}
+		const value = await this.artifacts.storageFor(scopeId).readJson(`commands/${commandId}/artifact.json`).catch(() => null);
+		return isPersistedShellCommandArtifact(value) ? value : null;
+	}
+	persistCommandArtifact(record) {
+		const fingerprint = `${record.status}:${record.exitCode ?? ""}:${record.stdout.length}:${record.stderr.length}`;
+		if (record.persistedFingerprint === fingerprint) return;
+		record.persistedFingerprint = fingerprint;
+		this.artifacts.persist(record.commandScopeId, record.id, persistedArtifactFromRecord(record));
+	}
+	syncRunningRecord(record) {
+		const foreground = this.shells.get(record.shellId)?.foreground;
+		if (record.status === "running" && foreground?.commandId === record.id) {
+			record.stdout = foreground.stdoutBuffer;
+			record.stderr = foreground.stderrBuffer;
+			record.outputChunks = [...foreground.outputChunks];
+			record.lastOutputAt = foreground.lastOutputAt;
+		}
+	}
+};
+function createPortableCommands(session) {
+	return createLazyCommands([...DEMI_PORTABLE_COMMANDS]).map((command) => ({
+		...command,
+		execute: async (args, ctx) => {
+			const result = await command.execute(args, ctx);
+			session.accumulator.audit.push({
+				kind: "portable-command",
+				name: command.name,
+				args,
+				cwd: ctx.cwd,
+				exitCode: result.exitCode
+			});
+			return result;
+		}
+	}));
+}
+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}`);
+	return Math.floor(value);
+}
+function streamArtifact(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);
+	const available = Math.max(0, totalBytes - boundedOffset);
+	const byteLimit = Math.max(0, Math.floor(maxOutputBytes));
+	const delta = utf8Slice(text, boundedOffset, boundedOffset + (byteLimit === 0 ? available : Math.min(available, byteLimit)));
+	const nextOffset = boundedOffset + utf8Bytes(delta);
+	const truncated = nextOffset < totalBytes;
+	if (explicitOffset === void 0) if (stream === "stdout") record.stdoutOffset = nextOffset;
+	else record.stderrOffset = nextOffset;
+	return {
+		path: `/@/commands/${record.id}/${stream}.txt`,
+		offset: nextOffset,
+		delta,
+		tail: tailString(text),
+		bytes: totalBytes,
+		truncated
+	};
+}
+function streamOutputArtifact(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));
+	const available = Math.max(0, totalBytes - offset);
+	let remaining = byteLimit === 0 ? available : Math.min(available, byteLimit);
+	const chunks = [];
+	for (const chunk of record.outputChunks) {
+		if (remaining <= 0) break;
+		const chunkStart = chunk.offset;
+		if (chunk.offset + chunk.bytes <= offset) continue;
+		const start = Math.max(0, offset - chunkStart);
+		const take = Math.min(chunk.bytes - start, remaining);
+		const text = utf8Slice(chunk.text, start, start + take);
+		if (text.length > 0) {
+			chunks.push({
+				stream: chunk.stream,
+				text
+			});
+			remaining -= utf8Bytes(text);
+		} else remaining -= take;
+	}
+	const text = chunks.map((chunk) => chunk.text).join("");
+	const nextOffset = offset + utf8Bytes(text);
+	const truncated = nextOffset < totalBytes;
+	if (explicitOffset === void 0) record.outputOffset = nextOffset;
+	return {
+		path: `demi://shell/${record.shellId}/commands/${record.id}/output`,
+		offset: nextOffset,
+		text,
+		tail: tailOutputText(record.outputChunks),
+		chunks,
+		bytes: totalBytes,
+		truncated
+	};
+}
+function appendRecordOutput(record, stream, text) {
+	if (text.length === 0) return;
+	const offset = record.outputChunks.reduce((total, chunk) => total + chunk.bytes, 0);
+	record.outputChunks.push({
+		stream,
+		text,
+		offset,
+		bytes: utf8Bytes(text)
+	});
+}
+function ensureRecordOutputCoverage(record) {
+	const stdoutBytes = record.outputChunks.filter((chunk) => chunk.stream === "stdout").reduce((total, chunk) => total + chunk.bytes, 0);
+	const stderrBytes = record.outputChunks.filter((chunk) => chunk.stream === "stderr").reduce((total, chunk) => total + chunk.bytes, 0);
+	if (stdoutBytes === utf8Bytes(record.stdout) && stderrBytes === utf8Bytes(record.stderr)) return;
+	record.outputChunks = [];
+	appendRecordOutput(record, "stdout", record.stdout);
+	appendRecordOutput(record, "stderr", record.stderr);
+}
+function persistedArtifactFromRecord(record) {
+	return {
+		status: record.status,
+		shellId: record.shellId,
+		commandId: record.id,
+		startedAt: record.startedAt,
+		lastOutputAt: record.lastOutputAt,
+		exitCode: record.exitCode ?? null,
+		stdout: record.stdout,
+		stderr: record.stderr
+	};
+}
+function commandArtifactMeta(artifact) {
+	const stdoutPath = `/@/commands/${artifact.commandId}/stdout.txt`;
+	const stderrPath = `/@/commands/${artifact.commandId}/stderr.txt`;
+	return {
+		status: artifact.status,
+		shellId: artifact.shellId,
+		commandId: artifact.commandId,
+		startedAt: artifact.startedAt,
+		lastOutputAt: artifact.lastOutputAt,
+		runningMs: Date.now() - artifact.startedAt,
+		idleMs: Date.now() - artifact.lastOutputAt,
+		exitCode: artifact.exitCode,
+		stdout: {
+			path: stdoutPath,
+			bytes: utf8Bytes(artifact.stdout)
+		},
+		stderr: {
+			path: stderrPath,
+			bytes: utf8Bytes(artifact.stderr)
+		}
+	};
+}
+function isPersistedShellCommandArtifact(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";
+}
+function tailOutputText(chunks) {
+	const maxChars = 4096;
+	let text = "";
+	for (let i = chunks.length - 1; i >= 0 && text.length < maxChars; i -= 1) text = `${chunks[i].text}${text}`;
+	return tailString(text);
+}
+function clampOffset(value, max) {
+	if (!Number.isFinite(value) || value <= 0) return 0;
+	return Math.min(Math.floor(value), max);
+}
+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 };