@demicodes/shell 0.10.1 → 0.10.3

package/dist/host-fs.d.mts

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

package/dist/host-fs.mjs

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

package/dist/index.d.mts

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

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { HostBackedFileSystem, virtualDirectory, virtualFile } from "./host-fs.mjs";
 import { AgentSessionCommandStorage } from "./storage.mjs";
-import { asError, base64ToBytes, bytesToBase64, concatBytes, decodeLatin1, decodeUtf8, decodeUtf8Strict, encodeLatin1, encodeUtf8, tail, utf8Bytes, utf8Slice } from "@demicodes/utils";
+import { asError, concatBytes, decodeUtf8, encodeUtf8, tail, utf8Bytes, utf8Slice } from "@demicodes/utils";
 import { createLazyCommands, getCommandNames } from "@demicodes/just-bash/commands";
 import { ArithmeticError, BadSubstitutionError, ExecutionLimitError, ExitError, Interpreter } from "@demicodes/just-bash/interpreter";
 import { decodeBytesToUtf8, unsafeBytesFromLatin1 } from "@demicodes/just-bash/encoding";
@@ -10,19 +10,26 @@ 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:
+* Individually excluded even though just-bash calls them portable: each
+* regresses a real, already-passing test elsewhere in this monorepo when
+* dispatched through this package's fork-command wrapping specifically
+* (isolated just-bash unit tests for these same commands pass fine, so the
+* break is in how @demicodes/shell wraps them, not in just-bash itself):
 *
-* - `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.
+* - `bash`, `sh`: nested "run a script string through the interpreter again".
+*   Their stdout never reaches the caller here — `sh -c "printf hi"` and
+*   `bash -c "echo hi"` both exit 0 with empty output, while the exact same
+*   scripts run un-nested work fine. This package's own `AgentServer` test
+*   spawns `sh -c` for real and asserts on the real output.
+* - `sleep`: just-bash's version is a plain timer, not a real backgroundable,
+*   abortable OS process. This package's own environment tests use `sleep 10`
+*   specifically as a long-running foreground process to exercise abort/
+*   timeout handling (`env.abort()` / status-while-`running`), which needs a
+*   real process to abort.
+*
+* Keeping these three off the list preserves their pre-existing
+* fall-through to Host.process.spawn, same as before this list started
+* tracking just-bash's registry.
 */
 const REAL_SPAWN_DEPENDENT_COMMANDS = /* @__PURE__ */ new Set([
 	"bash",
@@ -108,12 +115,6 @@ const RESERVED_COMMAND_NAMES = /* @__PURE__ */ new Set([
 ]);
 //#endregion
 //#region src/command.ts
-function emptyStdin() {
-	return {
-		text: "",
-		bytes: /* @__PURE__ */ new Uint8Array(0)
-	};
-}
 const EXECUTION_ONLY_FIELDS = [
 	"effects",
 	"successOutput",
@@ -124,7 +125,6 @@ const EXECUTION_ONLY_FIELDS = [
 	"output",
 	"examples"
 ];
-const COMMAND_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 var CommandRegistry = class {
 	commands = /* @__PURE__ */ new Map();
 	register(command) {
@@ -139,14 +139,14 @@ var CommandRegistry = class {
 	list() {
 		return [...this.commands.values()];
 	}
-	renderHelp() {
-		const rendered = this.list().map((command) => renderCommandHelp(command)).join("\n\n");
+	renderPrompt() {
+		const rendered = this.list().map((command) => renderCommandPrompt(command)).join("\n\n");
 		if (!rendered) return rendered;
-		return `${COMMAND_HELP_DEFAULTS}\n\n${rendered}`;
+		return `${COMMAND_PROMPT_DEFAULTS}\n\n${rendered}`;
 	}
 };
-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()) {
+const COMMAND_PROMPT_DEFAULTS = "Unless a command states otherwise: success prints raw text on stdout, failure writes an error message to stderr and exits non-zero.";
+function parseCommandInput(root, argv, stdin = { text: "" }) {
 	if (argv[0] !== root.name) throw new Error(`Expected command "${root.name}", received "${argv[0] ?? ""}"`);
 	let node = root;
 	const path = [root.name];
@@ -157,7 +157,7 @@ function parseCommandInput(root, argv, stdin = emptyStdin()) {
 			throw new Error(`Command "${path.join(" ")}" requires a subcommand`);
 		}
 		const token = argv[index];
-		if (token === "--help") return {
+		if (token === "prompt") return {
 			path: [...path],
 			help: true,
 			values: {},
@@ -182,12 +182,6 @@ function parseArgs(command, path, argv, startIndex, stdin) {
 	let positionalIndex = 0;
 	for (let i = startIndex; i < argv.length; i += 1) {
 		const token = argv[i];
-		if (token === "--help") return {
-			path: [...path],
-			help: true,
-			values: {},
-			json: false
-		};
 		if (token === "--json") {
 			json = true;
 			continue;
@@ -229,13 +223,13 @@ function resolveCommand(root, path) {
 	return node;
 }
 async function runRegisteredCommand(root, ctx) {
-	const stdin = ctx.stdin ?? emptyStdin();
+	const stdin = ctx.stdin ?? { text: "" };
 	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`);
+		await ctx.io.stdout(`${renderCommandPrompt(node, parentPath)}\n`);
 		return { exitCode: 0 };
 	}
 	const command = resolveCommand(root, parsed.path);
@@ -249,8 +243,7 @@ async function runRegisteredCommand(root, ctx) {
 		env: ctx.env,
 		cwd: ctx.cwd,
 		io: parsed.json ? capture : ctx.io,
-		storage: ctx.storage,
-		host: ctx.host
+		storage: ctx.storage
 	});
 	if (parsed.json && result.exitCode === 0) {
 		const raw = capture.stdoutText();
@@ -269,7 +262,7 @@ async function runRegisteredCommand(root, ctx) {
 	}
 	return result;
 }
-function renderCommandHelp(command, parentPath = "") {
+function renderCommandPrompt(command, parentPath = "") {
 	const path = parentPath ? `${parentPath} ${command.name}` : command.name;
 	const blocks = [];
 	const lines = [`${path}: ${command.summary}`];
@@ -304,11 +297,10 @@ function renderCommandHelp(command, parentPath = "") {
 		for (const child of children) lines.push(`  ${path} ${child.name} — ${child.summary}`);
 	}
 	blocks.push(lines.join("\n"));
-	for (const child of children) blocks.push(renderCommandHelp(child, path));
+	for (const child of children) blocks.push(renderCommandPrompt(child, path));
 	return blocks.join("\n\n");
 }
 function validateCommandTree(command, path) {
-	if (!COMMAND_NAME_PATTERN.test(command.name)) throw new Error(`CommandRegistry: "${path}" has invalid name "${command.name}"; use letters, numbers, underscores, and hyphens`);
 	const hasRun = typeof command.run === "function";
 	const children = command.subcommands ?? [];
 	if (!hasRun && children.length === 0) throw new Error(`CommandRegistry: "${path}" must have run() and/or subcommands`);
@@ -322,6 +314,7 @@ function validateCommandTree(command, path) {
 	}
 	const seen = /* @__PURE__ */ new Set();
 	for (const child of children) {
+		if (child.name === "prompt") throw new Error(`CommandRegistry: "${path} prompt" is reserved for the help pseudo-subcommand`);
 		if (seen.has(child.name)) throw new Error(`CommandRegistry: duplicate subcommand "${path} ${child.name}"`);
 		seen.add(child.name);
 		validateCommandTree(child, `${path} ${child.name}`);
@@ -405,6 +398,9 @@ 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));
 	}
@@ -516,10 +512,8 @@ function createOutputSinks(fs, cwd, redirections) {
 function recordForegroundChunk(foreground, sourceFd, chunk) {
 	const text = decodeUtf8(chunk);
 	foreground.lastOutputAt = Date.now();
-	if (sourceFd === 1) {
-		foreground.rawStdoutBuffer += text;
-		foreground.rawStdoutBytes.push(chunk);
-	} else foreground.rawStderrBuffer += text;
+	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);
@@ -621,63 +615,62 @@ function appendVisibleChunk(foreground, targetFd, text, byteLength) {
 //#endregion
 //#region src/command-artifact-store.ts
 /**
-* Owns persistence of shell command artifacts: a per-storage-id cache plus the
+* 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;
-	storageById = /* @__PURE__ */ new Map();
+	storageByScope = /* @__PURE__ */ new Map();
 	released = /* @__PURE__ */ new Set();
 	constructor(store) {
 		this.store = store;
 	}
-	/** The artifact storage for one agent session or anonymous shell. */
-	storageFor(commandStorageId) {
-		const existing = this.storageById.get(commandStorageId);
+	/** 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, commandStorageId);
-		this.storageById.set(commandStorageId, storage);
+		const storage = new AgentSessionCommandStorage(this.store, scopeId);
+		this.storageByScope.set(scopeId, storage);
 		return storage;
 	}
 	/** Whether a command's artifact has been released (tombstoned). */
-	isReleased(commandStorageId, commandId) {
-		return this.released.has(this.key(commandStorageId, commandId));
+	isReleased(scopeId, commandId) {
+		return this.released.has(this.key(scopeId, commandId));
 	}
 	/** Persists an artifact unless its command has already been released. */
-	persist(commandStorageId, commandId, artifact) {
-		if (this.isReleased(commandStorageId, commandId)) return;
-		this.storageFor(commandStorageId).writeJson(`commands/${commandId}/artifact.json`, artifact).catch(() => {});
+	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(commandStorageId, commandId) {
-		this.released.add(this.key(commandStorageId, commandId));
-		await this.storageFor(commandStorageId).delete(`commands/${commandId}/artifact.json`).catch(() => {});
+	async release(scopeId, commandId) {
+		this.released.add(this.key(scopeId, commandId));
+		await this.storageFor(scopeId).delete(`commands/${commandId}/artifact.json`).catch(() => {});
 	}
-	key(commandStorageId, commandId) {
-		return `${commandStorageId}\0${commandId}`;
+	key(scopeId, commandId) {
+		return `${scopeId}\0${commandId}`;
 	}
 };
 //#endregion
 //#region src/registered-command-adapter.ts
-function commandToForkCommand(session, command, storage, host) {
+function commandToForkCommand(session, command, storage) {
 	return {
 		name: command.name,
 		consumesStdin: treeConsumesStdin(command),
 		execute: async (args, ctx) => {
-			const stdin = decodeForkStdin(ctx.stdin);
+			const stdinText = decodeForkStdin(ctx.stdin);
 			const io = createForwardingIO();
 			const argv = [command.name, ...args];
 			try {
 				const result = await runRegisteredCommand(command, {
 					argv,
-					stdin,
+					stdin: { text: stdinText },
 					env: mapToRecord(ctx.env),
 					cwd: ctx.cwd,
 					io,
-					storage,
-					host
+					storage
 				});
 				session.accumulator.audit.push({
 					kind: "registered-command",
@@ -692,8 +685,7 @@ function commandToForkCommand(session, command, storage, host) {
 					metadata: result.metadata
 				});
 				return {
-					stdout: io.stdoutLatin1(),
-					stdoutKind: "bytes",
+					stdout: io.stdoutText(),
 					stderr: io.stderrText(),
 					exitCode: result.exitCode
 				};
@@ -706,31 +698,38 @@ function commandToForkCommand(session, command, storage, host) {
 					exitCode: 1
 				});
 				return {
-					stdout: io.stdoutLatin1(),
-					stdoutKind: "bytes",
+					stdout: io.stdoutText(),
 					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);
 	}
-	stdoutLatin1() {
-		return decodeLatin1(concatBytes(this.stdoutChunks));
+	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();
@@ -744,52 +743,26 @@ function mapToRecord(map) {
 	for (const [key, value] of map) record[key] = value;
 	return record;
 }
-/** Pipes hand stdin over as a latin1-packed byte string; expose bytes and a UTF-8 text view. */
 function decodeForkStdin(stdin) {
-	if (!stdin) return {
-		text: "",
-		bytes: /* @__PURE__ */ new Uint8Array(0)
-	};
-	if (stdin instanceof Uint8Array) return {
-		text: decodeUtf8(stdin),
-		bytes: stdin
-	};
+	if (!stdin) return "";
+	if (stdin instanceof Uint8Array) return decodeUtf8(stdin);
 	const latin1 = stdin;
-	if (!latin1) return {
-		text: "",
-		bytes: /* @__PURE__ */ new Uint8Array(0)
-	};
-	const bytes = encodeLatin1(latin1);
+	if (!latin1) return "";
 	let hasHighByte = false;
-	let hasWideChar = false;
 	for (let i = 0; i < latin1.length; i += 1) {
 		const code = latin1.charCodeAt(i);
-		if (code > 255) hasWideChar = true;
-		else if (code > 127) hasHighByte = true;
+		if (code > 255) return latin1;
+		if (code > 127) hasHighByte = true;
 	}
-	if (hasWideChar) return {
-		text: latin1,
-		bytes: encodeUtf8(latin1)
-	};
-	if (!hasHighByte) return {
-		text: latin1,
-		bytes
-	};
-	return {
-		text: decodeUtf8(bytes),
-		bytes
-	};
+	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;
-/**
-* Ceiling for a raw-byte final stream. Sized so an ordinary viewing-grade clip
-* survives the shell and reaches the layer that decides what to do with it,
-* while still bounding a runaway producer.
-*/
-const DEFAULT_BINARY_LIMIT_BYTES = 16 * 1024 * 1024;
 /** Upper bound for a single exec observation window (also the command-bridge wait ceiling). */
 const MAX_TIMEOUT_MS = 6e5;
 var BashEnvironment = class {
@@ -798,8 +771,8 @@ var BashEnvironment = class {
 	shellIdFactory;
 	commandIdFactory;
 	initialEnv;
+	execEnv;
 	defaultOutputLimitBytes;
-	defaultBinaryLimitBytes;
 	shells = /* @__PURE__ */ new Map();
 	defaultShellByAgentSessionId = /* @__PURE__ */ new Map();
 	commandsById = /* @__PURE__ */ new Map();
@@ -811,15 +784,12 @@ var BashEnvironment = class {
 		this.shellIdFactory = options.shellIdFactory ?? (() => globalThis.crypto.randomUUID());
 		this.commandIdFactory = options.commandIdFactory ?? (() => globalThis.crypto.randomUUID());
 		this.initialEnv = options.initialEnv ?? {};
+		this.execEnv = options.execEnv;
 		this.defaultOutputLimitBytes = options.maxOutputBytes ?? DEFAULT_OUTPUT_LIMIT_BYTES;
-		this.defaultBinaryLimitBytes = options.maxBinaryBytes ?? DEFAULT_BINARY_LIMIT_BYTES;
 	}
 	getShell(shellId) {
 		return this.shells.get(shellId) ?? null;
 	}
-	hasCommand(commandId) {
-		return this.commandsById.has(commandId);
-	}
 	registerCommand(command) {
 		if (this.commands.get(command.name)) return;
 		this.commands.register(command);
@@ -829,13 +799,20 @@ var BashEnvironment = class {
 	}
 	async exec(input) {
 		const timeoutMs = normalizeTimeoutMs(input.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-		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);
+		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}"`);
@@ -847,7 +824,7 @@ var BashEnvironment = class {
 	}
 	async status(input) {
 		const record = this.requireCommand(input.commandId);
-		return this.commandStatus(record, input);
+		return this.snapshotCommand(record, input);
 	}
 	async write(input) {
 		const record = this.requireCommand(input.commandId);
@@ -857,11 +834,11 @@ var BashEnvironment = class {
 		const data = typeof input.stdin === "string" ? encodeUtf8(input.stdin) : input.stdin;
 		if (data.byteLength === 0) throw new Error("shell_write field \"stdin\" must not be empty; use shell_status to poll");
 		await foreground.handle.writeStdin(data);
-		return this.commandStatus(record, input);
+		return this.snapshotCommand(record, input);
 	}
 	async abort(input) {
 		const record = this.requireCommand(input.commandId);
-		if (record.status !== "running") return this.commandStatus(record, input);
+		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();
@@ -873,7 +850,7 @@ var BashEnvironment = class {
 		const record = this.commandsById.get(commandId);
 		if (!record || record.status === "running") return false;
 		this.commandsById.delete(commandId);
-		await this.artifacts.release(record.commandStorageId, commandId);
+		await this.artifacts.release(record.commandScopeId, commandId);
 		return true;
 	}
 	async disposeShell(shellId) {
@@ -939,22 +916,25 @@ var BashEnvironment = class {
 		if (!agentSessionId || shell.exited || !shell.pendingExec && !shell.foreground) return shell;
 		return this.createShell(agentSessionId);
 	}
-	createShell(agentSessionId, initialCwd) {
+	createShell(agentSessionId) {
 		const id = this.shellIdFactory();
-		const commandStorageId = agentSessionId ?? id;
-		const cwd = initialCwd ?? this.host.defaultCwd;
-		const fs = new HostBackedFileSystem(this.host, { lookup: (path) => this.lookupVirtualArtifact(commandStorageId, path) });
+		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);
-		if (agentSessionId) env.set("DEMI_SESSION_ID", agentSessionId);
+		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_SHELL_ID"]);
-		if (agentSessionId) exportedVars.add("DEMI_SESSION_ID");
+		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 = {
@@ -1015,8 +995,7 @@ var BashEnvironment = class {
 		const forkCommands = /* @__PURE__ */ new Map();
 		const session = {
 			id,
-			agentSessionId: agentSessionId ?? null,
-			commandStorageId,
+			commandScopeId,
 			state,
 			fs,
 			interpreter: void 0,
@@ -1025,7 +1004,8 @@ var BashEnvironment = class {
 				stdout: "",
 				stderr: "",
 				audit: [],
-				commandMetadata: []
+				commandMetadata: [],
+				assets: []
 			},
 			foregroundWaiters: /* @__PURE__ */ new Set(),
 			backgroundJobs: /* @__PURE__ */ new Map(),
@@ -1033,8 +1013,8 @@ var BashEnvironment = class {
 			exited: false
 		};
 		for (const command of createPortableCommands(session)) forkCommands.set(command.name, command);
-		const storage = new AgentSessionCommandStorage(this.host.store, commandStorageId);
-		for (const command of this.commands.list()) forkCommands.set(command.name, commandToForkCommand(session, command, storage, this.host));
+		const storage = new AgentSessionCommandStorage(this.host.store, commandScopeId);
+		for (const command of this.commands.list()) forkCommands.set(command.name, commandToForkCommand(session, command, storage));
 		session.abortController = new AbortController();
 		session.interpreter = new Interpreter({
 			fs,
@@ -1064,7 +1044,6 @@ 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);
@@ -1076,7 +1055,7 @@ var BashEnvironment = class {
 				record.exitCode = 2;
 				session.state.lastExitCode = 2;
 				session.activeCommandId = void 0;
-				return this.commandStatus(record, input);
+				return this.snapshotCommand(record, input);
 			}
 			throw error;
 		}
@@ -1084,7 +1063,8 @@ var BashEnvironment = class {
 			stdout: "",
 			stderr: "",
 			audit: [],
-			commandMetadata: []
+			commandMetadata: [],
+			assets: []
 		};
 		session.abortController = new AbortController();
 		session.activeCommandId = record.id;
@@ -1107,7 +1087,7 @@ var BashEnvironment = class {
 		const record = {
 			id,
 			shellId: session.id,
-			commandStorageId: session.commandStorageId,
+			commandScopeId: session.commandScopeId,
 			script,
 			startedAt: now,
 			lastOutputAt: now,
@@ -1120,7 +1100,7 @@ var BashEnvironment = class {
 			outputOffset: 0,
 			audit: [],
 			commandMetadata: [],
-			outputLimitBytes: this.defaultOutputLimitBytes
+			assets: []
 		};
 		this.commandsById.set(id, record);
 		return record;
@@ -1241,7 +1221,7 @@ var BashEnvironment = class {
 				foreground = outcome.foreground;
 				continue;
 			}
-			if (outcome.kind === "timeout") return this.commandStatus(record, input);
+			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);
@@ -1326,7 +1306,6 @@ var BashEnvironment = class {
 			startedAt,
 			lastOutputAt: startedAt,
 			rawStdoutBuffer: "",
-			rawStdoutBytes: [],
 			rawStderrBuffer: "",
 			stdoutBuffer: "",
 			stderrBuffer: "",
@@ -1347,7 +1326,7 @@ var BashEnvironment = class {
 		};
 		session.foreground = foreground;
 		notifyForegroundWaiters(session.foregroundWaiters, foreground);
-		if (opts.stdin && opts.stdin.length > 0) await handle.writeStdin(encodeLatin1(opts.stdin));
+		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) => {
@@ -1360,7 +1339,7 @@ var BashEnvironment = class {
 		}
 		const exit = await foreground.exitPromise;
 		await Promise.allSettled([foreground.stdoutPump, foreground.stderrPump]);
-		const stdout = decodeLatin1(concatBytes(foreground.rawStdoutBytes));
+		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] = {
@@ -1381,13 +1360,12 @@ var BashEnvironment = class {
 		session.foreground = void 0;
 		return {
 			stdout,
-			stdoutKind: "bytes",
 			stderr,
 			exitCode
 		};
 	}
 	collectExited(session, record, resultOrError, foreground, input = {}) {
-		if (record.status !== "running") return this.commandStatus(record, input);
+		if (record.status !== "running") return this.snapshotCommand(record, input);
 		if (resultOrError instanceof Error) {
 			if (resultOrError instanceof ExitError) {
 				session.exited = true;
@@ -1425,36 +1403,12 @@ var BashEnvironment = class {
 			appendRecordOutput(record, "stderr", text);
 			return this.finishExited(session, record, 1, input);
 		}
-		const raw = resultOrError.stdout;
-		let stdoutText;
-		let binary;
-		if (hasWideChar(raw)) stdoutText = raw;
-		else {
-			const bytes = encodeLatin1(raw);
-			const strict = decodeUtf8Strict(bytes);
-			if (strict !== null) stdoutText = strict;
-			else {
-				const cap = this.defaultBinaryLimitBytes;
-				const truncated = bytes.length > cap;
-				binary = {
-					data: truncated ? bytes.slice(0, cap) : bytes,
-					truncated,
-					totalBytes: bytes.length,
-					limitBytes: cap
-				};
-				stdoutText = `<binary stdout: ${bytes.length} bytes${truncated ? `, exceeds the ${cap}-byte binary limit` : ""}; raw bytes at /@/commands/${record.id}/stdout.bin>\n`;
-			}
-		}
+		const 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 (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) {
+		if (foreground) record.outputChunks = [...foreground.outputChunks];
+		else if (record.outputChunks.length === 0) {
 			appendRecordOutput(record, "stdout", stdoutText);
 			appendRecordOutput(record, "stderr", stderrText);
 		}
@@ -1473,12 +1427,13 @@ 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.commandStatus(record, input);
+		return this.snapshotCommand(record, input);
 	}
 	async collectAborted(session, record, foreground, input = {}) {
-		if (record.status !== "running") return this.commandStatus(record, input);
+		if (record.status !== "running") return this.snapshotCommand(record, input);
 		foreground.abortController.abort();
 		foreground.handle.kill("SIGTERM").catch(() => {});
 		await flushForegroundSinks(session, foreground);
@@ -1490,10 +1445,10 @@ var BashEnvironment = class {
 		session.foreground = void 0;
 		session.pendingExec = void 0;
 		if (session.activeCommandId === record.id) session.activeCommandId = void 0;
-		return this.commandStatus(record, input);
+		return this.snapshotCommand(record, input);
 	}
 	collectAbortedWithoutForeground(session, record, input = {}) {
-		if (record.status !== "running") return this.commandStatus(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;
@@ -1505,9 +1460,9 @@ var BashEnvironment = class {
 		}
 		record.lastOutputAt = Date.now();
 		record.status = "aborted";
-		return this.commandStatus(record, input);
+		return this.snapshotCommand(record, input);
 	}
-	commandStatus(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;
@@ -1516,9 +1471,9 @@ var BashEnvironment = class {
 			record.lastOutputAt = foreground.lastOutputAt;
 		}
 		const maxOutputBytes = input.maxOutputBytes ?? this.defaultOutputLimitBytes;
-		const stdout = streamView(record, "stdout", input.stdoutOffset, maxOutputBytes);
-		const stderr = streamView(record, "stderr", input.stderrOffset, maxOutputBytes);
-		const output = mergedOutputView(record, input.outputOffset, maxOutputBytes);
+		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,
@@ -1537,7 +1492,7 @@ var BashEnvironment = class {
 				audit: record.audit
 			};
 			if (record.commandMetadata.length > 0) result.commandMetadata = record.commandMetadata;
-			if (record.binaryStdout) result.binaryStdout = record.binaryStdout;
+			if (record.assets.length > 0) result.assets = record.assets;
 			return result;
 		}
 		if (record.status === "aborted") return {
@@ -1549,56 +1504,52 @@ var BashEnvironment = class {
 			status: "running"
 		};
 	}
-	async lookupVirtualArtifact(commandStorageId, path) {
+	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(commandStorageId));
+		if (parts.length === 2 && parts[0] === "@" && parts[1] === "commands") return virtualDirectory(await this.commandArtifactIds(scopeId));
 		if (parts.length === 3 && parts[0] === "@" && parts[1] === "commands") {
-			const artifact = await this.commandArtifact(commandStorageId, parts[2]);
-			if (!artifact) return null;
-			const entries = [
+			if (!await this.commandArtifact(scopeId, parts[2])) return null;
+			return virtualDirectory([
 				"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(commandStorageId, parts[2]);
+		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;
 	}
-	async commandArtifactIds(commandStorageId) {
+	async commandArtifactIds(scopeId) {
 		const ids = /* @__PURE__ */ new Set();
-		for (const record of this.commandsById.values()) if (record.commandStorageId === commandStorageId && !this.artifacts.isReleased(commandStorageId, record.id)) ids.add(record.id);
-		const keys = await this.artifacts.storageFor(commandStorageId).list("commands").catch(() => []);
+		for (const 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(commandStorageId, match[1])) ids.add(match[1]);
+			if (match && !this.artifacts.isReleased(scopeId, match[1])) ids.add(match[1]);
 		}
 		return [...ids];
 	}
-	async commandArtifact(commandStorageId, commandId) {
-		if (this.artifacts.isReleased(commandStorageId, commandId)) return null;
+	async commandArtifact(scopeId, commandId) {
+		if (this.artifacts.isReleased(scopeId, commandId)) return null;
 		const record = this.commandsById.get(commandId);
-		if (record?.commandStorageId === commandStorageId) {
+		if (record?.commandScopeId === scopeId) {
 			this.syncRunningRecord(record);
-			return commandArtifactFromRecord(record);
+			return persistedArtifactFromRecord(record);
 		}
-		const value = await this.artifacts.storageFor(commandStorageId).readJson(`commands/${commandId}/artifact.json`).catch(() => null);
-		return isCommandArtifact(value) ? value : null;
+		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}:${record.binaryStdout?.totalBytes ?? ""}`;
+		const fingerprint = `${record.status}:${record.exitCode ?? ""}:${record.stdout.length}:${record.stderr.length}`;
 		if (record.persistedFingerprint === fingerprint) return;
 		record.persistedFingerprint = fingerprint;
-		this.artifacts.persist(record.commandStorageId, record.id, commandArtifactFromRecord(record));
+		this.artifacts.persist(record.commandScopeId, record.id, persistedArtifactFromRecord(record));
 	}
 	syncRunningRecord(record) {
 		const foreground = this.shells.get(record.shellId)?.foreground;
@@ -1626,16 +1577,11 @@ function createPortableCommands(session) {
 		}
 	}));
 }
-/** True when the string contains a char > 0xFF, i.e. already-decoded Unicode text. */
-function hasWideChar(value) {
-	for (let i = 0; i < value.length; i += 1) if (value.charCodeAt(i) > 255) return true;
-	return false;
-}
 function normalizeTimeoutMs(value) {
 	if (!Number.isFinite(value) || value < 1 || value > 6e5) throw new Error(`timeoutMs must be between 1 and ${MAX_TIMEOUT_MS}`);
 	return Math.floor(value);
 }
-function streamView(record, stream, explicitOffset, maxOutputBytes) {
+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);
@@ -1655,7 +1601,7 @@ function streamView(record, stream, explicitOffset, maxOutputBytes) {
 		truncated
 	};
 }
-function mergedOutputView(record, explicitOffset, maxOutputBytes) {
+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));
@@ -1709,7 +1655,7 @@ function ensureRecordOutputCoverage(record) {
 	appendRecordOutput(record, "stdout", record.stdout);
 	appendRecordOutput(record, "stderr", record.stderr);
 }
-function commandArtifactFromRecord(record) {
+function persistedArtifactFromRecord(record) {
 	return {
 		status: record.status,
 		shellId: record.shellId,
@@ -1718,12 +1664,7 @@ function commandArtifactFromRecord(record) {
 		lastOutputAt: record.lastOutputAt,
 		exitCode: record.exitCode ?? null,
 		stdout: record.stdout,
-		stderr: record.stderr,
-		...record.binaryStdout ? { stdoutBinary: {
-			base64: bytesToBase64(record.binaryStdout.data),
-			truncated: record.binaryStdout.truncated,
-			totalBytes: record.binaryStdout.totalBytes
-		} } : {}
+		stderr: record.stderr
 	};
 }
 function commandArtifactMeta(artifact) {
@@ -1745,15 +1686,10 @@ 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 isCommandArtifact(value) {
+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";
@@ -1785,4 +1721,4 @@ function heredocDelimiter(body) {
 	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 };
+export { AgentSessionCommandStorage, BashEnvironment, COMMAND_PROMPT_DEFAULTS, CommandRegistry, DEMI_PORTABLE_COMMANDS, HostBackedFileSystem, MAX_TIMEOUT_MS, RESERVED_COMMAND_NAMES, heredocDelimiter, parseCommandInput, renderCommandPrompt, runRegisteredCommand, shellQuote, virtualDirectory, virtualFile };

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

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

package/dist/storage.d.mts

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

package/dist/storage.mjs

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

package/package.json

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