// The Linux VM: CheerpX (WebVM's engine) + an xterm.js terminal. // // The agent and the user share ONE interactive bash. To run a command, the agent // writes it to a script on the /data device and types ` __lwa ` into the // terminal. The rc file below defines __lwa, which sources the script (so `cd` and // exported variables persist, like a human typing) and brackets its output with // invisible OSC escape sequences that carry the id and exit status. Those markers // are how output is captured reliably; terminals ignore unknown OSC sequences. import { CX_BASE, DISK_VIRTUAL_URL } from "./config.js"; import { shQuote } from "./toolcalls.js"; import { Terminal } from "../vendor/xterm/xterm.mjs"; import { FitAddon } from "../vendor/xterm/addon-fit.mjs"; const RC = String.raw` [ -f /etc/bash.bashrc ] && . /etc/bash.bashrc [ -f ~/.bashrc ] && . ~/.bashrc HISTCONTROL=ignoreboth PS1='\[\e[32m\]\u@localwebagent\[\e[0m\]:\[\e[34m\]\w\[\e[0m\]\$ ' __lwa_prompt() { printf '\033]777;lwa;prompt\007'; } PROMPT_COMMAND="__lwa_prompt" # Runs agent command . First replaces the echoed " __lwa " line with the # prompt followed by the real command (or a short label), so the terminal reads # as if the agent had typed it. __lwa() { local f="/data/lwa_cmd_$1.sh" p="${"$"}{PS1@P}" p="${"$"}{p//$'\001'/}"; p="${"$"}{p//$'\002'/}" printf '\033[1A\r\033[2K%s' "$p" if [ -f "/data/lwa_label_$1" ]; then printf '\033[90m# %s\033[0m\n' "$(cat "/data/lwa_label_$1")" else sed -n '1p' "$f" sed -n '2,12s/^/> /p' "$f" [ "$(wc -l < "$f")" -gt 12 ] && printf '\033[90m> …\033[0m\n' fi printf '\033]777;lwa;start;%s\007' "$1" . "/data/lwa_cmd_$1.sh" < /dev/null printf '\033]777;lwa;end;%s;%s\007' "$1" "$?" } if [ -z "$__LWA_MOTD" ]; then export __LWA_MOTD=1; cat /etc/motd 2>/dev/null; fi `; const MARK_RE = /\x1b\]777;lwa;([^\x07]*)\x07/g; export class VM { constructor() { this.term = null; this.cx = null; this.data = null; this.send = null; this.idle = false; // bash is sitting at its prompt this.agentBusy = false; // agent owns the terminal this.onActivity = null; // (busy:boolean) CPU activity this.onIdleChange = null; this.#decoder = new TextDecoder(); } #decoder; #carry = ""; #capture = null; // { id, started, out, resolve } #seq = 0; #idleWaiters = []; mountTerminal(el) { this.term = new Terminal({ cursorBlink: true, convertEol: true, fontSize: 12.5, lineHeight: 1.25, scrollback: 5000, fontFamily: '"JetBrains Mono", "Cascadia Code", Menlo, Consolas, monospace', theme: { background: "#0c0c0e", foreground: "#d4d4d8", cursor: "#ececef", cursorAccent: "#0c0c0e", selectionBackground: "#3f3f4699", black: "#18181b", brightBlack: "#52525b", red: "#f87171", green: "#4ade80", yellow: "#facc15", blue: "#60a5fa", magenta: "#c084fc", cyan: "#22d3ee", white: "#d4d4d8", brightRed: "#fca5a5", brightGreen: "#86efac", brightYellow: "#fde047", brightBlue: "#93c5fd", brightMagenta: "#d8b4fe", brightCyan: "#67e8f9", brightWhite: "#fafafa", }, }); this.fit = new FitAddon(); this.term.loadAddon(this.fit); this.term.open(el); this.fit.fit(); // A hidden pane (mobile tab) measures as ~0 columns; give the console a sane size. if (this.term.cols < 40 || this.term.rows < 10) this.term.resize(100, 30); new ResizeObserver(() => { try { this.fit.fit(); } catch {} }).observe(el); this.term.onData((str) => { if (!this.send) return; if (this.agentBusy) { // While the agent runs a command, only let Ctrl-C through (to interrupt it). if (str === "\x03") this.#type("\x03"); return; } if (str.includes("\r")) this.#setIdle(false); this.#type(str); }); this.term.writeln("\x1b[90mStarting Debian (CheerpX)…\x1b[0m"); } async boot({ diskId, onStatus }) { onStatus?.("Loading CheerpX runtime"); const CX = await import(CX_BASE + "cx.esm.js"); onStatus?.("Attaching disk"); const disk = await CX.HttpBytesDevice.create(DISK_VIRTUAL_URL); // Writes go to IndexedDB, keyed by the image id so a new image never mixes with old blocks. this.overlayName = "lwa-overlay-" + diskId; const idb = await CX.IDBDevice.create(this.overlayName); const overlay = await CX.OverlayDevice.create(disk, idb); this.data = await CX.DataDevice.create(); // VM -> page channel for the file viewer: hidden processes copy files here and the // page reads them back from IndexedDB. Never shown in the terminal. this.exportDev = await CX.IDBDevice.create("lwa-export"); onStatus?.("Booting Linux"); this.cx = await CX.Linux.create({ mounts: [ { type: "ext2", dev: overlay, path: "/" }, { type: "dir", dev: this.data, path: "/data" }, { type: "dir", dev: this.exportDev, path: "/export" }, { type: "devs", path: "/dev" }, { type: "devpts", path: "/dev/pts" }, { type: "proc", path: "/proc" }, { type: "sys", path: "/sys" }, ], }); this.cx.registerCallback("cpuActivity", (s) => this.onActivity?.(s === "ready" ? false : true)); this.send = this.cx.setCustomConsole((buf, vt) => this.#onOutput(buf, vt), this.term.cols, this.term.rows); await this.data.writeFile("/lwarc.sh", RC); this.#shellLoop(); await this.waitIdle(60000); onStatus?.("Ready"); } async #shellLoop() { // Like WebVM: restart the shell whenever it exits. for (;;) { this.#setIdle(false); await this.cx.run("/bin/bash", ["--rcfile", "/data/lwarc.sh", "-i"], { env: ["HOME=/home/user", "TERM=xterm-256color", "USER=user", "SHELL=/bin/bash", "EDITOR=vim", "LANG=C.UTF-8", "LC_ALL=C.UTF-8", "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"], cwd: "/home/user", uid: 1000, gid: 1000, }); // If the agent's command exited the shell, finish its capture. if (this.#capture) this.#finishCapture(null); } } #type(str) { for (let i = 0; i < str.length; i++) this.send(str.charCodeAt(i)); } #setIdle(v) { if (this.idle === v) return; this.idle = v; this.onIdleChange?.(v); if (v) { const w = this.#idleWaiters; this.#idleWaiters = []; w.forEach((f) => f(true)); } } waitIdle(ms) { if (this.idle) return Promise.resolve(true); return new Promise((resolve) => { this.#idleWaiters.push(resolve); setTimeout(() => resolve(false), ms); }); } #onOutput(buf, vt) { if (vt !== 1) return; const bytes = new Uint8Array(buf); this.term.write(bytes); let text = this.#carry + this.#decoder.decode(bytes, { stream: true }); // Keep a possibly-incomplete marker for the next chunk. const lastEsc = text.lastIndexOf("\x1b]777;"); if (lastEsc >= 0 && text.indexOf("\x07", lastEsc) < 0) { this.#carry = text.slice(lastEsc); text = text.slice(0, lastEsc); } else this.#carry = ""; let last = 0; for (const m of text.matchAll(MARK_RE)) { this.#appendCapture(text.slice(last, m.index)); last = m.index + m[0].length; const [kind, id, status] = m[1].split(";"); if (kind === "prompt") { if (this.#capture) this.#finishCapture(null); // shell came back without an end marker this.#setIdle(true); } else if (kind === "start" && this.#capture?.id === id) { this.#capture.started = true; } else if (kind === "end" && this.#capture?.id === id) { this.#finishCapture(Number(status)); } } this.#appendCapture(text.slice(last)); } #appendCapture(s) { const c = this.#capture; if (!c || !c.started || !s) return; c.out += s; if (c.out.length > 400_000) c.out = c.out.slice(0, 100_000) + c.out.slice(-200_000); // bound memory } #finishCapture(exitCode) { const c = this.#capture; if (!c) return; this.#capture = null; clearTimeout(c.timer); c.resolve({ exitCode, output: cleanTerminalText(c.out), timedOut: c.timedOut }); } /** Runs a bash snippet in the shared terminal. Resolves {exitCode, output, timedOut}. */ async exec(command, { timeoutSec = 90, label = null } = {}) { if (!this.send) throw new Error("VM not running"); if (!(await this.waitIdle(5000))) { return { exitCode: null, output: "The terminal is busy: a program is running in the foreground. Ask the user to finish or press Ctrl-C.", timedOut: false, busy: true }; } const id = String(++this.#seq); await this.data.writeFile(`/lwa_cmd_${id}.sh`, command.endsWith("\n") ? command : command + "\n"); if (label) await this.data.writeFile(`/lwa_label_${id}`, label); this.agentBusy = true; try { const result = await new Promise((resolve) => { this.#capture = { id, started: false, out: "", resolve, timedOut: false }; this.#capture.timer = setTimeout(() => { if (!this.#capture) return; this.#capture.timedOut = true; this.#type("\x03"); // Ctrl-C setTimeout(() => this.#finishCapture(null), 3000); }, timeoutSec * 1000); this.#setIdle(false); this.#type("\x15 __lwa " + id + "\r"); // Ctrl-U clears any half-typed input first }); await this.waitIdle(3000); return result; } finally { this.agentBusy = false; } } /** Writes a file inside the VM (path relative to the shell's current directory). */ async writeFile(path, content) { const id = "f" + ++this.#seq; await this.data.writeFile(`/lwa_${id}`, content); const p = shQuote(path); // `cat >` rather than `cp`: /data files are read-only and cp would copy that mode. const lines = content.replace(/\n$/, "").split("\n").length; return this.exec(`mkdir -p -- "$(dirname -- ${p})" && cat /data/lwa_${id} > ${p} && echo "wrote $(wc -c < ${p}) bytes to $(readlink -f -- ${p})"`, { label: `write ${path} (${lines} line${lines === 1 ? "" : "s"})` }); } interrupt() { if (this.send) this.#type("\x03"); } // ---------- hidden file access (for the file viewer) ---------- // Files written to the IndexedDB-backed /export only become visible (even to the VM // itself) after an explicit sync, hence the "&& sync" after every write. #hiddenQueue = Promise.resolve(); #xseq = 0; /** Runs a bash snippet in a separate, invisible process. Its output must be redirected. */ hidden(script) { const run = () => this.cx.run("/bin/bash", ["-c", script + " /dev/null 2>&1"], { env: ["HOME=/home/user", "USER=user", "LANG=C.UTF-8", "PATH=/usr/local/bin:/usr/bin:/bin"], cwd: "/home/user", uid: 1000, gid: 1000, }); const p = this.#hiddenQueue.then(run, run); this.#hiddenQueue = p.catch(() => {}); return p; } async #exported(name) { const blob = await this.exportDev.readFileAsBlob("/" + name); this.hidden(`rm -f /export/${name}`); return blob; } /** Lists a directory: { path, entries: [{name, type: 'd'|'f'|'l', size, mtime}] } */ async listDir(path) { const n = "l" + ++this.#xseq; const r = await this.hidden(`cd -- ${shQuote(path)} || exit 2; { pwd -P; find . -maxdepth 1 -mindepth 1 -printf '%y\t%s\t%T@\t%f\n'; } > /export/${n} && sync /export/${n}`); if (r.status !== 0) throw new Error(r.status === 2 ? `Can't open ${path}` : `ls failed (${r.status})`); const [abs, ...lines] = (await (await this.#exported(n)).text()).split("\n"); const entries = lines.filter(Boolean).map((l) => { const [type, size, mtime, ...name] = l.split("\t"); return { name: name.join("\t"), type: type === "d" ? "d" : type === "l" ? "l" : "f", size: Number(size), mtime: Number(mtime) * 1000 }; }); return { path: abs, entries }; } /** Reads a file as a Blob (throws if it is a directory, unreadable or larger than maxBytes). */ async readFile(path, maxBytes = 25e6) { const n = "r" + ++this.#xseq; const r = await this.hidden(`f=${shQuote(path)}; [ -d "$f" ] && exit 3; [ -r "$f" ] || exit 2; [ "$(stat -L -c %s -- "$f")" -le ${Math.floor(maxBytes)} ] || exit 4; cat -- "$f" > /export/${n} && sync /export/${n}`); if (r.status === 3) throw Object.assign(new Error("is a directory"), { code: "EISDIR" }); if (r.status === 2) throw Object.assign(new Error(`Can't read ${path}`), { code: "ENOENT" }); if (r.status === 4) throw Object.assign(new Error(`File is larger than ${Math.round(maxBytes / 1e6)} MB`), { code: "EFBIG" }); if (r.status !== 0) throw new Error(`read failed (${r.status})`); return this.#exported(n); } /** Resolves a path relative to the interactive shell's home to an absolute path. */ async realpath(path) { const n = "p" + ++this.#xseq; const r = await this.hidden(`readlink -f -- ${shQuote(path)} > /export/${n} && sync /export/${n}`); if (r.status !== 0) throw new Error(`Can't resolve ${path}`); return (await (await this.#exported(n)).text()).trim(); } } /** Turns raw terminal bytes into plain text: drops escape sequences, applies \r overwrites. */ export function cleanTerminalText(s) { s = s .replace(/\x1b\][^\x07\x1b]*(\x07|\x1b\\)/g, "") // OSC .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "") // CSI .replace(/\x1b[@-Z\\-_]/g, "") // other ESC .replace(/\r+\n/g, "\n"); return s .split("\n") .map((line) => { const i = line.lastIndexOf("\r"); return (i >= 0 ? line.slice(i + 1) : line).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ""); }) .join("\n") .replace(/\n+$/, ""); }